Configuration¶
Standard Library¶
The Library Reference is configured at compile time using
defines named CONFIG_*
. The default configuration includes most
functionality, as most application wants that. If an application has
special requirements, for example memory constraints, it has to be
configured to remove unnecessaray functionality.
Search order¶
Highest priority first.
Simba build system¶
- Command line as
CDEFS_EXTRA="<configuration variable>=<value>"
. - A file named
config.h
in the application root folder. - The default configuration file, src/config_default.h.
PlatformIO¶
- The variable
build_flags
inplatformio.ini
asbuild_flags = -D<configuration variable>=<value>
. - A file named
config.h
in the application source foldersrc
. - The default configuration file, src/config_default.h.
Arduino IDE¶
- A file (also called a tab) named
config.h
in the sketch. - The default configuration file, src/config_default.h.
Variables¶
All configuration variables are listed below. Their default values are defined in src/config_default.h.
Defines
-
CONFIG_SYS_CONFIG_STRING
1¶
-
CONFIG_SYS_SIMBA_MAIN_STACK_MAX
4096¶ Main thread stack size for ports with a fixed size main thread stack.
-
CONFIG_SYS_RESET_CAUSE
1¶ Read, and when needed clear, the reset cause at startup.
-
CONFIG_SYS_PANIC_KICK_WATCHDOG
0¶ Kick the watchdog in
sys_panic()
before writing to the console.
-
CONFIG_ASSERT
1¶ Assertions are used to check various conditions during the application execution. A typical usage is to validate function input arguments.
-
CONFIG_ASSERT_FORCE_FATAL
1¶ Force all assertions to be fatal.
-
CONFIG_FATAL_ASSERT
1¶ Enable fatal assertions,
FATAL_ASSERT*()
.
-
CONFIG_PANIC_ASSERT
1¶ Enable panic assertions,
PANIC_ASSERT*()
.
-
CONFIG_DEBUG
1¶ Include more debug information.
-
CONFIG_LINUX_SOCKET_DEVICE
0¶ Enable linux driver implementations as TCP sockets. Can be used to simulate driver communication in an application running on linux.
-
CONFIG_ADC
0¶ Enable the adc driver.
-
CONFIG_ANALOG_INPUT_PIN
0¶ Enable the analog_input_pin driver.
-
CONFIG_ANALOG_OUTPUT_PIN
0¶ Enable the analog_output_pin driver.
-
CONFIG_CAN
0¶ Enable the can driver.
-
CONFIG_CAN_FRAME_TIMESTAMP
1¶ Timestamp received CAN frames.
-
CONFIG_CHIPID
0¶ Enable the chipid driver.
-
CONFIG_RANDOM
0¶ Enable the random driver.
-
CONFIG_LED_7SEG_HT16K33
0¶ Enable the led_7seg_ht16k33 driver.
-
CONFIG_SHT3XD
0¶ Enable the sht3xd driver.
-
CONFIG_DAC
0¶ Enable the dac driver.
-
CONFIG_DS18B20
0¶ Enable the ds18b20 driver.
-
CONFIG_DS3231
0¶ Enable the ds3231 driver.
-
CONFIG_ESP_WIFI
0¶ Enable the esp_wifi driver.
-
CONFIG_EXTI
0¶ Enable the exti driver.
-
CONFIG_FLASH
0¶ Enable the flash driver.
-
CONFIG_I2C
0¶ Enable the i2c driver.
-
CONFIG_I2C_SOFT
0¶ Enable the i2c_soft driver.
-
CONFIG_MCP2515
0¶ Enable the mcp2515 driver.
-
CONFIG_NRF24L01
0¶ Enable the nrf24l01 driver.
-
CONFIG_OWI
0¶ Enable the owi driver.
-
CONFIG_PIN
0¶ Enable the pin driver.
-
CONFIG_PWM
0¶ Enable the pwm driver.
-
CONFIG_PWM_SOFT
0¶ Enable the pwm_soft driver.
-
CONFIG_SD
0¶ Enable the sd driver.
-
CONFIG_SPI
0¶ Enable the spi driver.
-
CONFIG_UART
1¶ Enable the uart driver.
-
CONFIG_UART_SOFT
0¶ Enable the uart_soft driver.
-
CONFIG_USB
0¶ Enable the usb driver.
-
CONFIG_USB_DEVICE
0¶ Enable the usb_device driver.
-
CONFIG_USB_HOST
0¶ Enable the usb_host driver.
-
CONFIG_WATCHDOG
0¶ Enable the watchdog driver.
-
CONFIG_MODULE_INIT_RWLOCK
1¶ Initialize the module at system startup.
-
CONFIG_MODULE_INIT_FS
1¶ Initialize the fs module at system startup.
-
CONFIG_MODULE_INIT_SETTINGS
1¶ Initialize the settings module at system startup.
-
CONFIG_MODULE_INIT_STD
1¶ Initialize the std module at system startup.
-
CONFIG_MODULE_INIT_SEM
1¶ Initialize the sem module at system startup.
-
CONFIG_MODULE_INIT_TIMER
1¶ Initialize the timer module at system startup.
-
CONFIG_MODULE_INIT_LOG
1¶ Initialize the log module at system startup.
-
CONFIG_MODULE_INIT_CHAN
1¶ Initialize the chan module at system startup.
-
CONFIG_MODULE_INIT_THRD
1¶ Initialize the thrd module at system startup.
-
CONFIG_MODULE_INIT_ADC
0¶ Initialize the adc driver module at system startup.
-
CONFIG_MODULE_INIT_ANALOG_INPUT_PIN
0¶ Initialize the analog_input_pin driver module at system startup.
-
CONFIG_MODULE_INIT_ANALOG_OUTPUT_PIN
0¶ Initialize the analog_output_pin driver module at system startup.
-
CONFIG_MODULE_INIT_CAN
0¶ Initialize the can driver module at system startup.
-
CONFIG_MODULE_INIT_CHIPID
0¶ Initialize the chipid driver module at system startup.
-
CONFIG_MODULE_INIT_RANDOM
0¶ Initialize the random driver module at system startup.
-
CONFIG_MODULE_INIT_DAC
0¶ Initialize the dac driver module at system startup.
-
CONFIG_MODULE_INIT_DS18B20
0¶ Initialize the ds18b20 driver module at system startup.
-
CONFIG_MODULE_INIT_DS3231
0¶ Initialize the ds3231 driver module at system startup.
-
CONFIG_MODULE_INIT_ESP_WIFI
0¶ Initialize the esp_wifi driver module at system startup.
-
CONFIG_MODULE_INIT_EXTI
0¶ Initialize the exti driver module at system startup.
-
CONFIG_MODULE_INIT_FLASH
0¶ Initialize the flash driver module at system startup.
-
CONFIG_MODULE_INIT_I2C
0¶ Initialize the i2c driver module at system startup.
-
CONFIG_MODULE_INIT_I2C_SOFT
0¶ Initialize the i2c_soft driver module at system startup.
-
CONFIG_MODULE_INIT_MCP2515
0¶ Initialize the mcp2515 driver module at system startup.
-
CONFIG_MODULE_INIT_NRF24L01
0¶ Initialize the nrf24l01 driver module at system startup.
-
CONFIG_MODULE_INIT_OWI
0¶ Initialize the owi driver module at system startup.
-
CONFIG_MODULE_INIT_PIN
0¶ Initialize the pin driver module at system startup.
-
CONFIG_MODULE_INIT_PWM
0¶ Initialize the pwm driver module at system startup.
-
CONFIG_MODULE_INIT_PWM_SOFT
0¶ Initialize the pwm_soft driver module at system startup.
-
CONFIG_MODULE_INIT_SD
0¶ Initialize the sd driver module at system startup.
-
CONFIG_MODULE_INIT_SPI
0¶ Initialize the spi driver module at system startup.
-
CONFIG_MODULE_INIT_UART
1¶ Initialize the uart driver module at system startup.
-
CONFIG_MODULE_INIT_UART_SOFT
0¶ Initialize the uart_soft driver module at system startup.
-
CONFIG_MODULE_INIT_USB
0¶ Initialize the usb driver module at system startup.
-
CONFIG_MODULE_INIT_USB_DEVICE
0¶ Initialize the usb_device driver module at system startup.
-
CONFIG_MODULE_INIT_USB_HOST
0¶ Initialize the usb_host driver module at system startup.
-
CONFIG_MODULE_INIT_WATCHDOG
0¶ Initialize the watchdog driver module at system startup.
-
CONFIG_MODULE_INIT_BUS
1¶ Initialize the bus module at system startup.
-
CONFIG_MODULE_INIT_INET
1¶ Initialize the inet module at system startup.
-
CONFIG_MODULE_INIT_PING
1¶ Initialize the ping module at system startup.
-
CONFIG_MODULE_INIT_SOCKET
1¶ Initialize the socket module at system startup.
-
CONFIG_MODULE_INIT_NETWORK_INTERFACE
1¶ Initialize the network_interface module at system startup.
-
CONFIG_MODULE_INIT_SSL
0¶ Initialize the ssl module at system startup.
-
CONFIG_MODULE_INIT_UPGRADE
0¶ Initialize the upgrade module at system startup.
-
CONFIG_FS_CMD_DS18B20_LIST
1¶ Debug file system command to list all DS18B20 sensors on the bus.
-
CONFIG_FS_CMD_ESP_WIFI_STATUS
0¶ Debug file system command to print the Espressif WiFi status.
-
CONFIG_FS_CMD_FS_APPEND
1¶ Debug file system command to append to a file.
-
CONFIG_FS_CMD_FS_COUNTERS_LIST
1¶ Debug file system command to list all counters.
-
CONFIG_FS_CMD_FS_COUNTERS_RESET
1¶ Debug file system command to set all counters to zero.
-
CONFIG_FS_CMD_FS_FILESYSTEMS_LIST
1¶ Debug file system command to list all registered file systems.
-
CONFIG_FS_CMD_FS_LIST
1¶ Debug file system command to list all registered file systems.
-
CONFIG_FS_CMD_FS_FORMAT
1¶ Debug file system command to format a file system.
-
CONFIG_FS_CMD_FS_PARAMETERS_LIST
1¶ Debug file system command to list all parameters.
-
CONFIG_FS_CMD_FS_READ
1¶ Debug file system command to read from a file.
-
CONFIG_FS_CMD_FS_REMOVE
1¶ Debug file system command to remove a file.
-
CONFIG_FS_CMD_FS_WRITE
1¶ Debug file system command to write to a file.
-
CONFIG_FS_CMD_I2C_READ
1¶ Debug file system command to read from a i2c bus.
-
CONFIG_FS_CMD_I2C_WRITE
1¶ Debug file system command to write to a i2c bus.
-
CONFIG_FS_CMD_LOG_LIST
1¶ Debug file system command to list all log objects.
-
CONFIG_FS_CMD_LOG_PRINT
1¶ Debug file system command to create a log entry and print it. Mainly used for debugging.
-
CONFIG_FS_CMD_LOG_SET_LOG_MASK
1¶ Debug file system command to set the log mask of a log object.
-
CONFIG_FS_CMD_NETWORK_INTERFACE_LIST
1¶ Debug file system command to list all network interfaces.
-
CONFIG_FS_CMD_PIN_READ
1¶ Debug file system command to read the current value of a pin.
-
CONFIG_FS_CMD_PIN_SET_MODE
1¶ Debug file system command to set the mode of a pin.
-
CONFIG_FS_CMD_PIN_WRITE
1¶ Debug file system command to write a value to a pin.
-
CONFIG_FS_CMD_PING_PING
1¶ Debug file system command to ping a host.
-
CONFIG_FS_CMD_SERVICE_LIST
1¶ Debug file system command to list all services.
-
CONFIG_FS_CMD_SERVICE_START
1¶ Debug file system command to start a service.
-
CONFIG_FS_CMD_SERVICE_STOP
1¶ Debug file system command to stop a services.
-
CONFIG_FS_CMD_SETTINGS_LIST
1¶ Debug file system command to list all settings.
-
CONFIG_FS_CMD_SETTINGS_READ
1¶ Debug file system command to read the value of a setting.
-
CONFIG_FS_CMD_SETTINGS_RESET
1¶ Debug file system command to reset the settings to their original values.
-
CONFIG_FS_CMD_SETTINGS_WRITE
1¶ Debug file system command to write a value to a setting.
-
CONFIG_FS_CMD_SYS_CONFIG
1¶ Debug file system command to print the system configuration.
-
CONFIG_FS_CMD_SYS_INFO
1¶ Debug file system command to print the system information.
-
CONFIG_FS_CMD_SYS_UPTIME
1¶ Debug file system command to print the system uptime.
-
CONFIG_FS_CMD_SYS_PANIC
1¶ Debug file system command to force a panic of the system.
-
CONFIG_FS_CMD_SYS_REBOOT
1¶ Debug file system command to reboot the system.
-
CONFIG_FS_CMD_SYS_BACKTRACE
1¶ Debug file system command to print a backtrace.
-
CONFIG_FS_CMD_SYS_RESET_CAUSE
1¶ Debug file system command to print the system reset cause.
-
CONFIG_FS_CMD_THRD_LIST
1¶ Debug file system command to list threads’ information.
-
CONFIG_FS_CMD_THRD_SET_LOG_MASK
1¶ Debug file system command to set the log mask of a thread.
-
CONFIG_FS_CMD_UPGRADE_APPLICATION_ENTER
1¶ Debug file system command to enter the application.
-
CONFIG_FS_CMD_UPGRADE_APPLICATION_ERASE
1¶ Debug file system command to erase the application.
-
CONFIG_FS_CMD_UPGRADE_APPLICATION_IS_VALID
1¶ Debug file system command to check if the application is valid.
-
CONFIG_FS_CMD_UPGRADE_BOOTLOADER_ENTER
1¶ Debug file system command to enter the bootloader.
-
CONFIG_FS_CMD_USB_DEVICE_LIST
1¶ Debug file system command to list all USB devices.
-
CONFIG_FS_CMD_USB_HOST_LIST
1¶ Debug file system command to list all USB devices connected to the USB host.
-
CONFIG_FS_CMD_NVM_READ
1¶ Debug file system command to read for non-volatile memory.
-
CONFIG_FS_CMD_NVM_WRITE
1¶ Debug file system command to write for non-volatile memory.
-
CONFIG_FS_PATH_MAX
64¶ The maximum length of an absolute path in the file system.
-
CONFIG_MONITOR_THREAD
1¶ Start the monitor thread to gather statistics of the scheulder.
-
CONFIG_MONITOR_THREAD_PERIOD_US
2000000¶ Default period of the monitor thread in microseconds.
-
CONFIG_PREEMPTIVE_SCHEDULER
0¶ Use a preemptive scheduler.
-
CONFIG_PROFILE_STACK
1¶ Profile the stack usage in runtime. It’s a cheap operation and is recommended to have enabled.
-
CONFIG_SETTINGS_AREA_SIZE
256¶ Size of the settings area. This size MUST have the same size as the settings generated by the settings.py script.
-
CONFIG_SETTINGS_BLOB
1¶ Enable the blob setting type.
-
CONFIG_SHELL_COMMAND_MAX
64¶ Maximum number of characters in a shell command.
-
CONFIG_SHELL_HISTORY_SIZE
768¶ Size of the shell history buffer.
-
CONFIG_SHELL_MINIMAL
0¶ Minimal shell functionality to minimize the code size of the shell module.
-
CONFIG_SHELL_PROMPT
"$ "¶ The shell prompt string.
-
CONFIG_SOCKET_RAW
1¶ Raw socket support.
-
CONFIG_SPIFFS
0¶ SPIFFS is a flash file system applicable for boards that has a reasonably big modifiable flash.
-
CONFIG_FAT16
1¶ FAT16 is a file system.
-
CONFIG_FILESYSTEM_GENERIC
1¶ Generic file system.
-
CONFIG_START_CONSOLE
CONFIG_START_CONSOLE_UART¶ Start the console device (UART/USB CDC) on system startup.
-
CONFIG_START_CONSOLE_DEVICE_INDEX
0¶ Console device index.
-
CONFIG_START_CONSOLE_UART_BAUDRATE
38400¶ Console UART baudrate.
-
CONFIG_START_CONSOLE_UART_RX_BUFFER_SIZE
32¶ Console UART baudrate.
-
CONFIG_START_CONSOLE_USB_CDC_CONTROL_INTERFACE
0¶ Console USB CDC control interface number.
-
CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_IN
2¶ Console USB CDC input endpoint.
-
CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_OUT
3¶ Console USB CDC output endpoint.
-
CONFIG_START_CONSOLE_USB_CDC_WAIT_FOR_CONNETION
1¶ Wait for the host to connect after starting the console.
-
CONFIG_START_FILESYSTEM
0¶ Configure a default file system.
-
CONFIG_START_FILESYSTEM_ADDRESS
0¶ Configure a default file system start address.
-
CONFIG_START_FILESYSTEM_SIZE
65536¶ Configure a default file system size.
-
CONFIG_START_NVM
1¶ Configure a default non-volatile memory.
-
CONFIG_NVM_SIZE
2040¶ Non-volatile memory size in bytes.
-
CONFIG_NVM_EEPROM_SOFT
1¶ Use the software EEPROM implementation in the non-volatile memory module.
-
CONFIG_NVM_EEPROM_SOFT_BLOCK_0_SIZE
16384¶ Non-volatile memory software EEPROM block 0 size. Must be a multiple of
CONFIG_NVM_EEPROM_SOFT_CHUNK_SIZE
.
-
CONFIG_NVM_EEPROM_SOFT_BLOCK_1_SIZE
16384¶ Non-volatile memory software EEPROM block 1 size. Must be a multiple of
CONFIG_NVM_EEPROM_SOFT_CHUNK_SIZE
.
-
CONFIG_NVM_EEPROM_SOFT_CHUNK_SIZE
(CONFIG_NVM_SIZE + 8)¶ Non-volatile software EEPROM chunk size. Must be a power of two.
-
CONFIG_NVM_EEPROM_SOFT_FLASH_DEVICE_INDEX
0¶ Non-volatile software EEPROM flash device index.
-
CONFIG_START_NETWORK
0¶ Setup the ip stack and connect to all configured networks.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_CONNECT_TIMEOUT
30¶ WiFi connect timeout is seconds.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_SSID
MyWiFiSSID¶ SSID of the WiFi to connect to.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD
MyWiFiPassword¶ Password of the WiFi to connect to.
-
CONFIG_START_SHELL
1¶ Start a shell thread communication over the console channels.
-
CONFIG_START_SHELL_PRIO
30¶ Shell thread priority.
-
CONFIG_START_SHELL_STACK_SIZE
768¶ Shell thread stack size in words.
-
CONFIG_START_SOAM
0¶ Start a SOAM thread communication over the console channels.
-
CONFIG_START_SOAM_PRIO
30¶ SOAM thread priority.
-
CONFIG_START_SOAM_STACK_SIZE
840¶ SOAM thread stack size in words.
-
CONFIG_STD_OUTPUT_BUFFER_MAX
16¶ Maximum number of bytes in the print output buffer.
-
CONFIG_FLOAT
1¶ Use floating point numbers instead of intergers where applicable.
-
CONFIG_SYSTEM_TICK_FREQUENCY
100¶ System tick frequency in Hertz.
-
CONFIG_SYSTEM_INTERRUPTS
1¶ Use interrupts.
-
CONFIG_SYSTEM_INTERRUPT_STACK_SIZE
0¶ Interrupt stack size in bytes. Set to a value greater than zero to enable the interrupt stack.
-
CONFIG_THRD_CPU_USAGE
1¶ Calculate thread CPU usage.
-
CONFIG_THRD_DEFAULT_LOG_MASK
LOG_UPTO(INFO)¶ Default thread log mask.
-
CONFIG_THRD_ENV
1¶ Each thread has a list of environment variables associated with it. A typical example of an environment variable is “CWD” - Current Working Directory.
-
CONFIG_THRD_IDLE_STACK_SIZE
1024¶ Stack size of the idle thread.
-
CONFIG_THRD_MONITOR_STACK_SIZE
1024¶ Stack size of the monitor thread.
-
CONFIG_THRD_SCHEDULED
1¶ Count the number of times each thread has been scheduled.
-
CONFIG_THRD_STACK_HEAP
0¶ Enable the thread stack heap allocator.
-
CONFIG_THRD_STACK_HEAP_SIZE
0¶ Size in bytes of the thread stack heap.
-
CONFIG_THRD_TERMINATE
1¶ Threads are allowed to terminate.
-
CONFIG_USB_DEVICE_VID
0x2341¶ USB device vendor id.
-
CONFIG_USB_DEVICE_PID
0x8037¶ USB device product id.
-
CONFIG_EMACS_COLUMNS_MAX
80¶ Number of colums in Emacs text editor.
-
CONFIG_EMACS_ROWS_MAX
24¶ Number of rows in Emacs text editor.
-
CONFIG_EMACS_HEAP_SIZE
32768¶ Heap size of the emacs text editor.
-
CONFIG_SYSTEM_TICK_SOFTWARE
0¶ System tick using a software timer instead of a hardware timer. Suitable for ESP8266 to enable software PWM.
-
CONFIG_HTTP_SERVER_SSL
0¶ Add support to wrap the HTTP server in SSL, creating a HTTPS server.
-
CONFIG_HARNESS_SLEEP_MS
300¶ Sleep in the test harness before executing the first testcase.
-
CONFIG_HARNESS_EXPECT_BUFFER_SIZE
512¶ Maximum buffer size the expect function can handle.
-
CONFIG_HARNESS_HEAP_MAX
2048¶ Size of the harness heap, required for harness_mock_write() and harness_mock_read().
-
CONFIG_HARNESS_MOCK_VERBOSE
1¶ Verbose mock framework.
-
CONFIG_HTTP_SERVER_REQUEST_BUFFER_SIZE
128¶ Size of the HTTP server request buffer. This buffer is used when parsing received HTTP request headers.
-
CONFIG_CRC_TABLE_LOOKUP
1¶ Use lookup tables for CRC calculations. It is faster, but uses more memory.
-
CONFIG_SPC5_BOOT_ENTRY_RCHW
1¶
-
CONFIG_SPC5_RAM_CLEAR_ALL
1¶
-
CONFIG_TIME_UNIX_TIME_TO_DATE
1¶ Include the function time_unix_time_to_date().
-
CONFIG_SOAM_EMBEDDED_DATABASE
0¶ Embed the SOAM database in the application.
-
CONFIG_SYS_LOG_MASK
LOG_UPTO(INFO)¶ System module log mask.
-
CONFIG_EXTERNAL_OSCILLATOR_FREQUENCY_HZ
16000000¶ The external oscillator frequency in Hertz.
-
CONFIG_FLASH_DEVICE_SEMAPHORE
1¶ Semaphore protected device access in the flash driver module.
-
CONFIG_EEPROM_SOFT_SEMAPHORE
1¶ Semaphore protected software eeprom accesses.
-
CONFIG_EEPROM_SOFT_CRC_32
0¶
-
CONFIG_EEPROM_SOFT_CRC_CCITT
1¶
-
CONFIG_EEPROM_SOFT_CRC
CONFIG_EEPROM_SOFT_CRC_32¶ Software eeprom crc algorithm.
lwIP¶
Use config.h
to fully configure lwIP and all of its modules. You
do not need to define every option that lwIP provides; if you do not
define an option, a default value will be used. Therefore, your
config.h
provides a way to override much of the behavior of lwIP.
By default Simba overrides a few of the variables in src/inet/lwipopts.h.
Module support (Code size)¶
Enabling and disabling modules¶
You can tune your code size by only compiling the features you really need. The following is a list of what gets compiled in “out of the box” with lwIP.
Default inclusions:
- ARP (
LWIP_ARP
) - IP and fragmentation (
IP_FRAG
) and reassembly (IP_REASSEMBLY
) - Raw IP PCB support (
LWIP_RAW
) - UDP (
LWIP_UDP
) and UDP-Lite (LWIP_UDPLITE
) - TCP (
LWIP_TCP
) – this is a big one! - Statistics (
LWIP_STATS
)
Default exclusions:
- DHCP (
LWIP_DHCP
) - AUTOIP (
LWIP_AUTOIP
) - SNMP (
LWIP_SNMP
) - IGMP (
LWIP_IGMP
) - PPP (
PPP_SUPPORT
)
If you would like to change this, then you just need to set the
options listed below. For example, if you would like to disable UDP
and enable DHCP, the following config.h
file would do it:
/* Disable UDP */
#define LWIP_UDP 0
/* Enable DHCP */
#define LWIP_DHCP 1
Memory management (RAM usage)¶
Memory pools¶
In an embedded environment, memory pools make for fast and efficient memory allocation. lwIP provides a flexible way to manage memory pool sizes and organization.
lwIP reserves a fixed-size static chunk of memory in the data segment,
which is subdivided into the various pools that lwip uses for the
various data structures. For example, there is a pool just for struct
tcp_pcb’s, and another pool just for struct udp_pcb’s. Each pool can
be configured to hold a fixed number of data structures; this number
can be changed in the config.h
file by changing the various
MEMP_NUM_*
values. For example, MEMP_NUM_TCP_PCB
and
MEMP_NUM_UDP_PCB
control the maximum number of tcp_pcb and udp_pcb
structures that can be active in the system at any given time.
It is also possible to create custom memory pools in addition to the standard ones provided by lwIP.
Dynamic allocation: mem_malloc¶
lwIP uses a custom function mem_malloc for all dynamic allocation; therefore, it is easy to change how lwIP uses its RAM. There are three possibilities provided out-of-the-box:
- (default) lwIP’s custom heap-based mem_malloc. By default, lwIP
uses a statically-allocated chunk of memory like a heap for all
memory operations. Use
MEM_SIZE
to change the size of the lwIP heap. - C standard library malloc and free. If you wish to have lwIP use
the standard library functions provided by your
compiler/architecture, then define the option
MEM_LIBC_MALLOC
. - Memory pools. lwIP can also emulate dynamic allocation using custom
memory pools (see that chapter for more information). This involves
the options
MEM_USE_POOLS
andMEMP_USE_CUSTOM_POOLS
and a new custom filelwippools.h
.
Understanding/changing memory usage¶
lwIP uses memory for:
code (depending on your system, may use ROM instead of RAM)
statically allocated variables (some initialized, some not initialized)
task stack
dynamically allocated memory
- heap
- memp pools
Unless you use a C library heap implementation (by defining
MEM_LIBC_MALLOC
to 1), dynamically allocated memory must be statically
allocated somewhere. This means you reserve a specific amount of
memory for the heap or the memp pools from which the code dynamically
allocates memory at runtime.
The size of this heap and memp pools can be adjusted to save RAM:
There are 3 types of pbufs:
- REF/ROM, RAM and POOL.
PBUF_POOL_SIZE
*PBUF_POOL_BUFSIZE
only refers to type POOL. - RAM pbufs are allocated in the memory defined by
MEM_SIZE
(this memory is not used much aside from RAM pbufs) - this is the heap and it is allocated as mem_memory. - REF/ROM pbufs as well as pcbs and some other stuff is allocated from
dedicated pools per structure type. The amount of structures is
defined by the various
MEMP_NUM_
defines. Together, this memory is allocated as memp_memory and it includes the pbuf POOL.
However, if you define MEMP_MEM_MALLOC
to 1 in your config.h
,
every piece of dynamically allocated memory will come from the heap
(the size of which is defined by MEM_SIZE
). If you then even
define MEM_LIBC_MALLOC
to 1, too, lwIP doesn’t need extra memory
for dynamically allocated memory but only uses the C library heap
instead. However, you then have to make sure that this heap is big
enough to run your application.
To tweak the various MEMP_NUM_
defines, define LWIP_STATS=1
and LWIP_STATS_DISPLAY=1
and call stats_display() to see how
many entries of each pool are used (or have a look at the global
variable lwip_stats
instead).
Fine-tuning even more¶
To see the options that you can set, open 3pp/lwip-1.4.1/src/include/lwip/opt.h. This file is fully commented and explains how many of the options are used.