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

  1. Command line as CDEFS_EXTRA="<configuration variable>=<value>".
  2. A file named config.h in the application root folder.
  3. The default configuration file, src/config_default.h.

PlatformIO

  1. The variable build_flags in platformio.ini as build_flags = -D<configuration variable>=<value>.
  2. A file named config.h in the application source folder src.
  3. The default configuration file, src/config_default.h.

Arduino IDE

  1. A file (also called a tab) named config.h in the sketch.
  2. The default configuration file, src/config_default.h.

Default Settings

In this section you can find some important and widly used settings.

Console UART

The default configuration of the system console’s UART can be found at the page of particular boards in the Boards in the Default Configuration section.

Variables

All configuration variables are listed below. Their default values are defined in src/config_default.h.

Defines

PORT_HAS_I2C_SOFT
PORT_HAS_OWI
PORT_HAS_PIN
PORT_HAS_UART
PORT_HAS_XBEE
PORT_HAS_XBEE_CLIENT
PORT_HAS_HX711
PORT_HAS_GNSS
PORT_HAS_HD44780
PORT_HAS_ICSP_SOFT
PORT_HAS_JTAG_SOFT
PORT_HAS_I2C

Used to include driver header files and the c-file source.

CONFIG_SOFTWARE_I2C
PORT_HAS_DS3231
PORT_HAS_EEPROM_I2C
PORT_HAS_SHT3XD
PORT_HAS_DS18B20
PORT_HAS_BMP280
CONFIG_SYS_CONFIG_STRING

The system configuration string contains a list of all configration varialbes and their values.

CONFIG_SYS_SIMBA_MAIN_STACK_MAX

Main thread stack size for ports with a fixed size main thread stack.

CONFIG_SYS_PANIC_KICK_WATCHDOG

Kick the watchdog in sys_panic() before writing to the console.

CONFIG_SYS_PANIC_BACKTRACE_DEPTH

Maximum backtrace depth in sys_panic().

CONFIG_ASSERT

Assertions are used to check various conditions during the application execution. A typical usage is to validate function input arguments.

CONFIG_ASSERT_FORCE_FATAL

Force all assertions to be fatal.

CONFIG_ASSERT_FORCE_PANIC

Force all assertions to be panics.

CONFIG_FATAL_ASSERT

Enable fatal assertions, FATAL_ASSERT*().

CONFIG_PANIC_ASSERT

Enable panic assertions, PANIC_ASSERT*().

CONFIG_PANIC_ASSERT_FILE_LINE

Include file and line in panic assert output.

CONFIG_DEBUG

Include more debug information.

CONFIG_LINUX_SOCKET_DEVICE

Enable linux driver implementations as TCP sockets. Can be used to simulate driver communication in an application running on linux.

CONFIG_ADC

Enable the adc driver.

CONFIG_ANALOG_INPUT_PIN

Enable the analog_input_pin driver.

CONFIG_ANALOG_OUTPUT_PIN

Enable the analog_output_pin driver.

CONFIG_POWER

Enable the power driver.

CONFIG_CAN

Enable the can driver.

CONFIG_CAN_FRAME_TIMESTAMP

Timestamp received CAN frames.

CONFIG_CHIPID

Enable the chipid driver.

CONFIG_RANDOM

Enable the random driver.

CONFIG_WS2812

Enable the ws2812 driver.

CONFIG_LED_7SEG_HT16K33

Enable the led_7seg_ht16k33 driver.

CONFIG_SHT3XD

Enable the sht3xd driver.

CONFIG_DAC

Enable the dac driver.

CONFIG_DS18B20

Enable the ds18b20 driver.

CONFIG_DS3231

Enable the ds3231 driver.

CONFIG_EEPROM_SOFT

Enable the eeprom_soft driver.

CONFIG_ESP_WIFI

Enable the esp_wifi driver.

CONFIG_ESP_WIFI_FS_COMMAND_STATUS

Debug file system command to print the Espressif WiFi status.

CONFIG_EXTI

Enable the exti driver.

CONFIG_PCINT

Enable the pin change interrupt driver.

CONFIG_FLASH

Enable the flash driver.

CONFIG_I2C

Enable the i2c driver.

CONFIG_I2C_SOFT

Enable the i2c_soft driver.

CONFIG_ICSP_SOFT

Enable the icsp_soft driver.

CONFIG_JTAG_SOFT

Enable the jtag_soft driver.

CONFIG_EEPROM_I2C

Enable the eeprom_i2c driver.

CONFIG_EEPROM_I2C_NUMBER_OF_ATTEMPTS

Number of write retry attemps before giving up accessing a i2c eeprom.

CONFIG_MCP2515

Enable the mcp2515 driver.

CONFIG_NRF24L01

Enable the nrf24l01 driver.

CONFIG_OWI

Enable the owi driver.

CONFIG_PIN

Enable the pin driver.

CONFIG_PIN_FS_COMMAND_READ

Debug file system command to read the current value of a pin.

CONFIG_PIN_FS_COMMAND_SET_MODE

Debug file system command to set the mode of a pin.

CONFIG_PIN_FS_COMMAND_WRITE

Debug file system command to write a value to a pin.

CONFIG_PWM

Enable the pwm driver.

CONFIG_PWM_SOFT

Enable the pwm_soft driver.

CONFIG_SD

Enable the sd driver.

CONFIG_SPI

Enable the spi driver.

CONFIG_UART

Enable the uart driver.

CONFIG_UART_FS_COUNTERS

Debug file system uart counters.

CONFIG_UART_SOFT

Enable the uart_soft driver.

CONFIG_USB

Enable the usb driver.

CONFIG_USB_DEVICE

Enable the usb_device driver.

CONFIG_USB_DEVICE_FS_COMMAND_LIST

Debug file system command to list all USB devices.

CONFIG_USB_HOST

Enable the usb_host driver.

CONFIG_USB_HOST_FS_COMMAND_LIST

Debug file system command to list all USB devices connected to the USB host.

CONFIG_WATCHDOG

Enable the watchdog driver.

CONFIG_XBEE

Enable the xbee driver.

CONFIG_XBEE_DATA_MAX

Maximum xbee driver frame data size.

CONFIG_XBEE_CLIENT

Enable the xbee_client driver.

CONFIG_XBEE_CLIENT_DEBUG_LOG_MASK

xbee_client driver debug log mask.

CONFIG_XBEE_CLIENT_RESPONSE_TIMEOUT_MS

xbee_client packet response timeout in milliseconds.

CONFIG_HX711

Enable the hx711 driver.

CONFIG_GNSS

Enable the gnss driver.

CONFIG_GNSS_DEBUG_LOG_MASK

GNSS driver debug log mask.

CONFIG_BMP280

Enable the bmp280 driver.

CONFIG_BMP280_COVERTION_TIMEOUT_MS

BMP280 convertion timeout in milliseconds.

CONFIG_BMP280_DEBUG_LOG_MASK

BMP280 driver debug log mask.

CONFIG_DHT

Enable the dht driver.

CONFIG_MODULE_INIT_RWLOCK

Initialize the module at system startup.

CONFIG_MODULE_INIT_FS

Initialize the fs module at system startup.

CONFIG_MODULE_INIT_SETTINGS

Initialize the settings module at system startup.

CONFIG_MODULE_INIT_STD

Initialize the std module at system startup.

CONFIG_MODULE_INIT_SEM

Initialize the sem module at system startup.

CONFIG_MODULE_INIT_TIMER

Initialize the timer module at system startup.

CONFIG_MODULE_INIT_LOG

Initialize the log module at system startup.

CONFIG_MODULE_INIT_CHAN

Initialize the chan module at system startup.

CONFIG_MODULE_INIT_THRD

Initialize the thrd module at system startup.

CONFIG_MODULE_INIT_ADC

Initialize the adc driver module at system startup.

CONFIG_MODULE_INIT_ANALOG_INPUT_PIN

Initialize the analog_input_pin driver module at system startup.

CONFIG_MODULE_INIT_ANALOG_OUTPUT_PIN

Initialize the analog_output_pin driver module at system startup.

CONFIG_MODULE_INIT_CAN

Initialize the can driver module at system startup.

CONFIG_MODULE_INIT_CHIPID

Initialize the chipid driver module at system startup.

CONFIG_MODULE_INIT_RANDOM

Initialize the random driver module at system startup.

CONFIG_MODULE_INIT_DAC

Initialize the dac driver module at system startup.

CONFIG_MODULE_INIT_DS18B20

Initialize the ds18b20 driver module at system startup.

CONFIG_MODULE_INIT_DHT

Initialize the dht driver module at system startup.

CONFIG_DS18B20_FS_COMMAND_LIST

Debug file system command to list all DS18B20 sensors on the bus.

CONFIG_DHT_COMMAND_READ

Debug file system command to read DHT sensor on the bus.

CONFIG_MODULE_INIT_DS3231

Initialize the ds3231 driver module at system startup.

CONFIG_MODULE_INIT_ESP_WIFI

Initialize the esp_wifi driver module at system startup.

CONFIG_MODULE_INIT_EXTI

Initialize the exti driver module at system startup.

CONFIG_MODULE_INIT_FLASH

Initialize the flash driver module at system startup.

CONFIG_MODULE_INIT_I2C

Initialize the i2c driver module at system startup.

CONFIG_MODULE_INIT_I2C_SOFT

Initialize the i2c_soft driver module at system startup.

CONFIG_MODULE_INIT_MCP2515

Initialize the mcp2515 driver module at system startup.

CONFIG_MODULE_INIT_NRF24L01

Initialize the nrf24l01 driver module at system startup.

CONFIG_MODULE_INIT_OWI

Initialize the owi driver module at system startup.

CONFIG_MODULE_INIT_PIN

Initialize the pin driver module at system startup.

CONFIG_MODULE_INIT_POWER

Initialize the power driver module at system startup.

CONFIG_MODULE_INIT_PWM

Initialize the pwm driver module at system startup.

CONFIG_MODULE_INIT_PWM_SOFT

Initialize the pwm_soft driver module at system startup.

CONFIG_MODULE_INIT_SD

Initialize the sd driver module at system startup.

CONFIG_MODULE_INIT_SPI

Initialize the spi driver module at system startup.

CONFIG_MODULE_INIT_UART

Initialize the uart driver module at system startup.

CONFIG_MODULE_INIT_UART_SOFT

Initialize the uart_soft driver module at system startup.

CONFIG_MODULE_INIT_USB

Initialize the usb driver module at system startup.

CONFIG_MODULE_INIT_USB_DEVICE

Initialize the usb_device driver module at system startup.

CONFIG_MODULE_INIT_USB_HOST

Initialize the usb_host driver module at system startup.

CONFIG_MODULE_INIT_WATCHDOG

Initialize the watchdog driver module at system startup.

CONFIG_MODULE_INIT_BUS

Initialize the bus module at system startup.

CONFIG_MODULE_INIT_INET

Initialize the inet module at system startup.

CONFIG_MODULE_INIT_PING

Initialize the ping module at system startup.

CONFIG_MODULE_INIT_SOCKET

Initialize the socket module at system startup.

CONFIG_MODULE_INIT_NETWORK_INTERFACE

Initialize the network_interface module at system startup.

CONFIG_MODULE_INIT_SSL

Initialize the ssl module at system startup.

CONFIG_MODULE_INIT_UPGRADE

Initialize the upgrade module at system startup.

CONFIG_MODULE_INIT_RE

Initialize the regular expression module at system startup.

CONFIG_I2C_FS_COMMAND_READ

Debug file system command to read from a i2c bus.

CONFIG_I2C_FS_COMMAND_WRITE

Debug file system command to write to a i2c bus.

CONFIG_I2C_FS_COMMAND_SCAN

Debug file system command to scan a i2c bus.

CONFIG_LOG_FS_COMMANDS

Debug file system command to list all log objects.

CONFIG_NETWORK_INTERFACE_FS_COMMAND_LIST

Debug file system command to list all network interfaces.

CONFIG_PING_FS_COMMAND_PING

Debug file system command to ping a host.

CONFIG_SERVICE_FS_COMMAND_LIST

Debug file system command to list all services.

CONFIG_SERVICE_FS_COMMAND_START

Debug file system command to start a service.

CONFIG_SERVICE_FS_COMMAND_STOP

Debug file system command to stop a services.

CONFIG_SETTINGS_FS_COMMAND_LIST

Debug file system command to list all settings.

CONFIG_SETTINGS_FS_COMMAND_READ

Debug file system command to read the value of a setting.

CONFIG_SETTINGS_FS_COMMAND_RESET

Debug file system command to reset the settings to their original values.

CONFIG_SETTINGS_FS_COMMAND_WRITE

Debug file system command to write a value to a setting.

CONFIG_SYS_FS_COMMANDS

Sys module debug file system commands.

CONFIG_THRD_FS_COMMANDS

Thrd module debug file system commands.

CONFIG_UPGRADE_FS_COMMAND_APPLICATION_ENTER

Debug file system command to enter the application.

CONFIG_UPGRADE_FS_COMMAND_APPLICATION_ERASE

Debug file system command to erase the application.

CONFIG_UPGRADE_FS_COMMAND_APPLICATION_IS_VALID

Debug file system command to check if the application is valid.

CONFIG_UPGRADE_FS_COMMAND_BOOTLOADER_ENTER

Debug file system command to enter the bootloader.

CONFIG_FS_PATH_MAX

The maximum length of an absolute path in the file system.

CONFIG_FS_COMMAND_ARGS_MAX

Maximum number of command arguments, including the command name.

CONFIG_FS_FS_COMMAND_APPEND

Debug file system command to append to a file.

CONFIG_FS_FS_COMMAND_COUNTERS_LIST

Debug file system command to list all counters.

CONFIG_FS_FS_COMMAND_COUNTERS_RESET

Debug file system command to set all counters to zero.

CONFIG_FS_FS_COMMAND_FILESYSTEMS_LIST

Debug file system command to list all registered file systems.

CONFIG_FS_FS_COMMAND_LIST

Debug file system command to list all registered file systems.

CONFIG_FS_FS_COMMAND_FORMAT

Debug file system command to format a file system.

CONFIG_FS_FS_COMMAND_PARAMETERS_LIST

Debug file system command to list all parameters.

CONFIG_FS_FS_COMMAND_READ

Debug file system command to read from a file.

CONFIG_FS_FS_COMMAND_REMOVE

Debug file system command to remove a file.

CONFIG_FS_FS_COMMAND_WRITE

Debug file system command to write to a file.

CONFIG_MONITOR_THREAD

Start the monitor thread to gather statistics of the scheulder.

CONFIG_MONITOR_THREAD_PERIOD_US

Default period of the monitor thread in microseconds.

CONFIG_PREEMPTIVE_SCHEDULER

Use a preemptive scheduler.

CONFIG_PROFILE_STACK

Profile the stack usage in runtime. It’s a cheap operation and is recommended to have enabled.

CONFIG_SETTINGS_AREA_SIZE

Size of the settings area. This size MUST have the same size as the settings generated by the settings.py script.

CONFIG_SETTINGS_BLOB

Enable the blob setting type.

CONFIG_SHELL_COMMAND_MAX

Maximum number of characters in a shell command.

CONFIG_SHELL_HISTORY_SIZE

Size of the shell history buffer.

CONFIG_SHELL_MINIMAL

Minimal shell functionality to minimize the code size of the shell module.

CONFIG_SHELL_PROMPT

The shell prompt string.

CONFIG_SOCKET_RAW

Raw socket support.

CONFIG_SPIFFS

SPIFFS is a flash file system applicable for boards that has a reasonably big modifiable flash.

CONFIG_FAT16

FAT16 is a file system.

CONFIG_FILESYSTEM_GENERIC

Generic file system.

CONFIG_START_CONSOLE

Start the console device (UART/USB CDC) on system startup.

CONFIG_START_CONSOLE_DEVICE_INDEX

Console device index.

CONFIG_START_CONSOLE_UART_BAUDRATE

Console UART baudrate.

CONFIG_START_CONSOLE_UART_RX_BUFFER_SIZE

Console UART reception buffer size.

CONFIG_START_CONSOLE_USB_CDC_CONTROL_INTERFACE

Console USB CDC control interface number.

CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_IN

Console USB CDC input endpoint.

CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_OUT

Console USB CDC output endpoint.

CONFIG_START_CONSOLE_USB_CDC_WAIT_FOR_CONNETION

Wait for the host to connect after starting the console.

CONFIG_START_FILESYSTEM

Configure a default file system.

CONFIG_START_FILESYSTEM_FAT16

Start a FAT16 file system.

CONFIG_START_FILESYSTEM_SPIFFS

Start a flash file system.

CONFIG_START_FILESYSTEM_ADDRESS

Configure a default file system start address.

CONFIG_START_FILESYSTEM_SIZE

Configure a default file system size.

CONFIG_START_NVM

Configure a default non-volatile memory.

CONFIG_NVM_SIZE

Non-volatile memory size in bytes.

CONFIG_NVM_EEPROM_SOFT

Use the software EEPROM implementation in the non-volatile memory module.

CONFIG_NVM_EEPROM_SOFT_BLOCK_0_SIZE

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

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

Non-volatile software EEPROM chunk size. Must be a power of two.

CONFIG_NVM_EEPROM_SOFT_FLASH_DEVICE_INDEX

Non-volatile software EEPROM flash device index.

CONFIG_NVM_FS_COMMAND_READ

Debug file system command to read for non-volatile memory.

CONFIG_NVM_FS_COMMAND_WRITE

Debug file system command to write for non-volatile memory.

CONFIG_START_NETWORK

Setup the ip stack and connect to all configured networks.

CONFIG_START_NETWORK_INTERFACE_WIFI_CONNECT_TIMEOUT

WiFi connect timeout is seconds.

CONFIG_START_NETWORK_INTERFACE_WIFI_SSID

SSID of the WiFi to connect to.

CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD

Password of the WiFi to connect to.

CONFIG_START_SHELL

Start a shell thread communication over the console channels.

CONFIG_START_SHELL_PRIO

Shell thread priority.

CONFIG_START_SHELL_STACK_SIZE

Shell thread stack size in words.

CONFIG_START_SOAM

Start a SOAM thread communication over the console channels.

CONFIG_START_SOAM_PRIO

SOAM thread priority.

CONFIG_START_SOAM_STACK_SIZE

SOAM thread stack size in words.

CONFIG_START_SOAM_RX_BUFFER_SIZE

SOAM reception buffer size.

CONFIG_START_SOAM_TX_BUFFER_SIZE

SOAM transmission buffer size.

CONFIG_STD_OUTPUT_BUFFER_MAX

Maximum number of bytes in the print output buffer.

CONFIG_FLOAT

Use floating point numbers instead of intergers where applicable.

CONFIG_ALIGNMENT

Memory alignment for runtime memory allocations.

CONFIG_SYSTEM_TICK_FREQUENCY

System tick frequency in Hertz.

CONFIG_SYSTEM_INTERRUPTS

Use interrupts.

CONFIG_SYSTEM_INTERRUPT_STACK_SIZE

Interrupt stack size in bytes. Set to a value greater than zero to enable the interrupt stack.

CONFIG_THRD_CPU_USAGE

Calculate thread CPU usage.

CONFIG_THRD_DEFAULT_LOG_MASK

Default thread log mask.

CONFIG_RE_DEBUG_LOG_MASK

Regular expression module debug log mask.

CONFIG_THRD_ENV

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

Stack size of the idle thread.

CONFIG_THRD_MONITOR_STACK_SIZE

Stack size of the monitor thread.

CONFIG_THRD_SCHEDULED

Count the number of times each thread has been scheduled.

CONFIG_THRD_STACK_HEAP

Enable the thread stack heap allocator.

CONFIG_THRD_STACK_HEAP_SIZE

Size in bytes of the thread stack heap.

CONFIG_THRD_TERMINATE

Threads are allowed to terminate.

CONFIG_USB_DEVICE_VID

USB device vendor id.

CONFIG_USB_DEVICE_PID

USB device product id.

CONFIG_EMACS_COLUMNS_MAX

Number of colums in Emacs text editor.

CONFIG_EMACS_ROWS_MAX

Number of rows in Emacs text editor.

CONFIG_EMACS_HEAP_SIZE

Heap size of the emacs text editor.

CONFIG_SYSTEM_TICK_SOFTWARE

System tick using a software timer instead of a hardware timer. Suitable for ESP8266 to enable software PWM.

CONFIG_HTTP_SERVER_SSL

Add support to wrap the HTTP server in SSL, creating a HTTPS server.

CONFIG_HARNESS_SLEEP_MS

Sleep in the test harness before executing the first testcase.

CONFIG_HARNESS_EXPECT_BUFFER_SIZE

Maximum buffer size the expect function can handle.

CONFIG_HARNESS_BACKTRACE_DEPTH_MAX

The maximum harness backtrace depth.

CONFIG_HARNESS_WRITE_BACKTRACE_DEPTH_MAX

The maximum harness write backtrace depth.

CONFIG_HARNESS_MOCK_ENTRIES_MAX

Maximum number of mock entries that can be allocated at any given moment, required for harness_mock_() functions.

CONFIG_HARNESS_EARLY_EXIT

Call sys_exit() immediately on test failure to stop the test suite execution as early as possible.

CONFIG_HARNESS_DEBUG

Output debug information from the harness.

CONFIG_HTTP_SERVER_REQUEST_BUFFER_SIZE

Size of the HTTP server request buffer. This buffer is used when parsing received HTTP request headers.

CONFIG_CRC_TABLE_LOOKUP

Use lookup tables for CRC calculations. It is faster, but uses more memory.

CONFIG_SPC5_BOOT_ENTRY_RCHW
CONFIG_SPC5_RAM_CLEAR_ALL
CONFIG_SPC5_RELOCATE_INIT
CONFIG_SPC5_WATCHDOG_DISABLE
CONFIG_TIME_UNIX_TIME_TO_DATE

Include the function time_unix_time_to_date().

CONFIG_SOAM_EMBEDDED_DATABASE

Embed the SOAM database in the application.

CONFIG_SYS_LOG_MASK

System module log mask.

CONFIG_SYS_RESET_CAUSE

Save reset cause at startup.

CONFIG_SYS_MEASURE_INTERRUPT_LOAD

Save reset cause at startup.

CONFIG_EXTERNAL_OSCILLATOR_FREQUENCY_HZ

The external oscillator frequency in Hertz.

CONFIG_FLASH_DEVICE_SEMAPHORE

Semaphore protected device access in the flash driver module.

CONFIG_EEPROM_SOFT_SEMAPHORE

Semaphore protected software eeprom accesses.

CONFIG_EEPROM_SOFT_CRC_32
CONFIG_EEPROM_SOFT_CRC_CCITT
CONFIG_EEPROM_SOFT_CRC

Software eeprom crc algorithm.

CONFIG_EEPROM_SOFT_OVERWRITE_IDENTICAL_DATA

Overwrite identical data in software eeprom.

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:

  1. (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.
  2. 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.
  3. 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 and MEMP_USE_CUSTOM_POOLS and a new custom file lwippools.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.