Custom memory pools

lwIP provides a way to define your own custom memory pools to be used in addition to the standard ones provided by lwIP. There are two reasons you may need to do this:

1. You want to use a pool-based mem_malloc, as described in the next section
2. You want to add extra pools for your architecture (for example, you have a custom IP protocol, or your sys_arch requires extra data structures not explicitly provided already, or you are using lwIP's memory pool manager in your OS or application).

Defining custom pools

The standard memory pools are defined in the memp_std.h file. If you define the MEMP_USE_CUSTOM_POOLS macro, then lwIP will also search for a lwippools.h file. This file should be created in the same directory as lwipopts.h and only needs to contain additional pools not defined in memp_std.h.

There are three "kinds" of pools that can be defined:

1. LWIP_MEMPOOL(pool_name, number_elements, element_size, pool_desc). This is a normal memory pool that has the given number of elements, each with a given size.
2. LWIP_PBUF_MEMPOOL(pool_name, number_elements, payload_size, pool_desc). This is a shortcut to create a pool that will hold pbuf's. The overhead for the pbuf structure will be added to the payload size for these kinds of pools. Further, these pools are intended to be used by pbuf_alloc.
3. LWIP_MALLOC_MEMPOOL(number_buffers, buffer_size). This is used to define pools for a mem_malloc (see next section).

Simply include a definition in your lwippools.h file for each additional pool you want to be included in lwIP's memory subsystem. An example is provided at the end of this chapter.

Pool-based mem_malloc

To enable a pool-based mem_malloc, you must first define a set of chunk sizes. When lwIP calls mem_malloc for a block of size "x", it will attempt to allocate a chunk of size at least as big as "x".

For example, if your chunk sizes are 256 (for small blocks), 512 (for medium blocks) and 1512 (for full Ethernet frames), then calling mem_malloc for blocks of size 100, 400, and 1000 will result in a block of each size. The example below shows how to do this setup.

The definitions for all malloc memory pools must be made contiguously as a single group, starting with a LWIP_MALLOC_MEMPOOL_START and ending with a LWIP_MALLOC_MEMPOOL_END.

WARNING: The memory pool allocator will pick the first pool size that fits the requested size, testing them in the order that you list them in the lwippools.h file. Therefore, you probably want to list them in order of increasing size! If the allocation fails, it does not test pools later on in the list.

Example

lwipopts.h

// ..... (lots of stuff irrelevant to our discussion)
 #define MEM_USE_POOLS 1
 #define MEM_USE_CUSTOM_POOLS 1
 // .....
 

lwippools.h

/* Define three pools with sizes 256, 512, and 1512 bytes */
LWIP_MALLOC_MEMPOOL_START 
LWIP_MALLOC_MEMPOOL(20, 256)
LWIP_MALLOC_MEMPOOL(10, 512) 
LWIP_MALLOC_MEMPOOL(5, 1512)
LWIP_MALLOC_MEMPOOL_END 

/* My sys_arch uses memory pools to allocate mbox and sems */
LWIP_MEMPOOL(SYS_MBOX, 22, sizeof(struct sys_mbox_struct), "SYS_MBOX")
LWIP_MEMPOOL(SYS_SEM, 12, sizeof(struct sys_sem_struct), "SYS_SEM")