LwIP buffer management, memory configuration options

http://www.st.com/st-web-ui/static/active/cn/resource/technical/document/application_note/DM00036052.pdf

LwIP TCP/IP stack demonstration for STM32F4x7 microcontrollers

Packet buffer structure

LwIP manages packet buffers using a data structure called pbuf.

The pbuf structure enables the allocation of a dynamic memory to hold a packet content and lets packets reside in the static memory.

Pbufs can be linked together in a chain. This enables packets to span over several pbufs.

• next: pointer to next pbuf in a pbuf chain
• payload: pointer to packet data payload
• len: length of the data content of the pbuf
• tot_len: sum of pbuf len plus all the len fields of the next pbufs in the chain
• ref: (on 4 bits) reference count that indicates the number of pointers that reference the pbuf. A pbuf can be released from memory only when its reference count is zero.
• flags: (on 4 bits) indicate the type of pbuf.

LwIP defines three types of pbufs, depending on the allocation type:

• PBUF_POOL: pbuf allocation is performed from a pool of statically pre-allocated pbufs that have a predefined size.
Depending on the data size that needs to be allocated, one or multiple chained pbufs are allocated.

• PBUF_RAM: pbuf is dynamically allocated in memory (one contiguous chunk of memory for the full pbuf)

• PBUF_ROM: there is no allocation for memory space for user payload, the pbuf payload pointer points to data in the ROM memory (it can be used only for sending constant data).

For packet reception, the suitable pbuf type is PBUF_POOL; it allows to rapidly allocate memory for the received packet from the pool of pbufs.
Depending on the size of the received packet, one or multiple chained pbufs are allocated.
The PBUF_RAM is not suitable for packet reception because dynamic allocation takes some delay. It may also lead to memory fragmentation.

For packet transmission, depending on the data to be transmitted, the user can choose the most suitable pbuf type.

API for managing pbufs LwIP has a specific API for working with pbufs. This API is implemented in the pbuf.c core file.

Note: 1 “pbuf” can be a single pbuf or a chain of pbufs.
2 When working with the Netconn API, netbufs (network buffers) are used for sending/receiving data.
3 A netbuf is simply a wrapper for a pbuf structure. It can accommodate both allocated and referenced data.
4 A dedicated API (implemented in file netbuf.c) is provided for managing netbufs (allocating, freeing, chaining, extracting data,...).

LwIP has several memory configurations options.

These options allow the user to tune the allocated RAM memory usage depending on performance needs
and on application memory constraints.The user options for LwIP are changed in file LwIPopt.h
Table 13 provides a summary of the main options for RAM memory use.

As shown in Table 13, LwIP memory has two main types:

• Heap memory for all dynamic allocations defined by MEM_SIZE.
• Pool memory for static pool structures defined by MEMP_NUM_xx and PBUF_POOL_xx.

The allocation from these two types of memory will define the total size of memory allocated to LwIP.

Below are some recommendations when setting these options:

• MEM_SIZE should be set high when the application needs to send a lot of data to be copied from application buffers to the LwIP send buffer.

• PBUF_POOL_BUFSIZE should be set according to the average size of packets to be received.

• PBUF_POOL_SIZE should be tuned as high as possible in order to achieve the best receive data rate.

• TCP_SND_BUF limits the sender buffer space (data queued to be transmitted).

For optimal performance, this parameter should be equal to the TCP window size of the remote host.
Keep in mind that every active connection might buffer this amount of data, so make sure there is enough RAM (defined by MEM_SIZE)
or limit the number of concurrently active connections.

• TCP_WND is the advertised receive window and should be tuned as high as possible in order to achieve the best performance.