[lwip-users] Re: [lwip] LWIP Memory Buffers And Allocators

[Adam Dunkels]

Hi John!

On Saturday 08 December 2001 05.42, you wrote:
> I'm in the process of porting the lwIP (currently 0.4.2 pending the 0.5
> release) to the Rabbit 2000 using the Softools ANSI C compiler. The
> lwipopts.h has options which control memory pools in three different .c
> files. There also appear to be three different types of allocators:
> memp, mem, and pbuf. What are the differences between these? I
> understand that a pbuf is a packet buffer, but what are the roles of the
> other two? There are two reasons for asking these questions. The first
> is so I have a better understanding of how the code is structured. The
> second is so that I understand the ramifications of modifying the
> default values in the test lwipopts.h file, which allocates more memory
> than is probably suitable for the architecture I'm porting to.

There are two types of memory management in lwIP; the heap memory (mem) and 
the static memory pools (memp). The pbuf management is a hybrid since it both 
manages its own memory (th pbuf pool) and uses the heap (mem). 

The mem is a heap memory manager, such as the C malloc/free manager. A block 
of memory is requsted with a call to mem_malloc() and the memory is freed 
with a call to mem_free(). This is used by code that allocates memory of 
diffrent sizes. An example is when contents of a packet needs to be copied 
into a buffer - since the size of the packet isn't known beforehand, the 
memory is allocated from the heap.

The memp, on the other hand, uses a set of pools of fixed size memory blocks. 
A call to memp_malloc() must specify which kind of memory that is requested. 
This is used by code which frequently allocates and deallocates memory of a 
certain size. An example here is the tcp_seg struct, which is used to 
represent a TCP segment when it is queued. Since this structure needs to be 
allocated quickly and is always of the same size, a memory pool is set up for 
this (MEMP_TCP_SEG).

The pbufs are used to hold packet data. There are essentially three types of 
pbufs, the RAM, ROM, and POOL pbufs. The RAM pbufs uses heap memory to hold 
the data; the memory is allocated using mem_malloc() when the pbuf is 
allocated in pbuf_alloc(). The ROM pbufs does not allocate any extra memory 
for the packet data (it is assumed to be in a static memory area such as 
ROM), but it allocates a struct pbuf from a memory pool. Finally, the POOL 
pbuf manages its own memory similar to the memp pools. They are to be used by 
a network device driver who needs to allocate buffers quickly.

The memory options in lwipopts.h are as follows:

* MEM_SIZE: the size of the heap. If the application will send a lot of data 
that needs to be copied, this should be set high.

* MEMP_NUM_PBUF: the number of memp struct pbufs. If the application sends a 
lot of data out of ROM (or other static memory), this should be set high.

* MEMP_NUM_UDP_PCB: the number of UDP protocol control blocks. One per active 
UDP "connection".

* MEMP_NUM_TCP_PCB: the number of simulatenously active TCP connections.

* MEMP_NUM_TCP_PCB_LISTEN: the number of listening TCP connections.

* MEMP_NUM_TCP_SEG: the number of simultaneously queued TCP segments.

(The following is only used by the sequential API:)

* MEMP_NUM_NETBUF: the number of struct netbufs.

* MEMP_NUM_NETCONN: the number of struct netconns.

* MEMP_NUM_APIMSG: the number of struct api_msg, used for communication 
between the TCP/IP stack and the sequential programs-

* MEMP_NUM_TCPIPMSG: the number of struct tcpip_msg, which is used for 
sequential API communication and incoming packets. Used in src/api/tcpip.c.

Another option is introduced in 0.5:

* MEMP_NUM_SYS_TIMEOUT: the number of simulateously active timeouts.

The pbuf options are:

* PBUF_POOL_SIZE: the number of pbufs in the pool.

* PBUF_POOL_BUFSIZE: the size of each individual pbuf in the pool.

* PBUF_LINK_HLEN: the amount of memory reserved for the link level header in 
each pbuf.

There are three other memory options as well:

* MEM_ALIGNMENT: how memory should be aligned (on a 1, 2, or 4 byte boundary)

* MEM_RECLAIM: 1 if the memory managed should attempt to reclaim memory when 
memory is scarce. Should be 1 unless code and stack size is essential.

* MEMP_RECLAIM: 1 if the memory pool manager should reclaim memory. Should 
definately be 1 (TCP doesn't work well without it).

> This seems to be a very well organized stack by the way. I just got
> through with a port of old K&R C WATTCP code which has a few more bells
> and whistles but is disorganized and has license issues ...

Is that a BSD based stack?

/adam
-- 
Adam Dunkels <address@hidden>
http://www.sics.se/~adam
[This message was sent through the lwip discussion list.]