LIB Memory Heap Configuration

µC/TCP-IP is using µC/LIB to allocated internal data such as OS objects (semaphore, mutex), device driver's buffers and DMA descriptors, etc. µC/TCP-IP internal tasks stack can be also allocated using µC/LIB. Therefore µC/LIB memory module must be configured properly for µC/TCP-IP. If the heap size is not configured large enough, an error will be returned during the Network Protocol Stack initialization, or during interface addition.

Since the needed heap size is related to the stack configuration (net_cfg.h) and is specific to each device driver, it’s not possible to provide an exact formula to calculate it. Thus to optimize the heap size, you should try different heap size until no error is returned for all interfaces added.

Note: The memory module must be initialized by the application prior to calling Net_Init(). We recommend initializing the memory module before calling starting the RTOS, or near the top of the startup task.

Please refer to section libdoc for more details on the µC/LIB module and its configuration.

Heap Memory Calculation for an Interface

The µC/LIB memory heap is used for allocation of the following objects:

Transmit small buffers
Transmit large buffers
Receive large buffers
Network Buffers (Network Buffer header and pointer to data area)
DMA receive descriptors
DMA transmit descriptors
Interface data area
Device driver data area
OS objects (Semaphore, mutex, stack)
ICMP Echo request objects (note that object are only allocated when the ICMP Echo request is sent, not at during the Network Protocol Stack initialization)

In the following example, the use of a Network Device Driver with DMA support is assumed. DMA descriptors are included in the analysis. The size of Network Buffer Data Areas (1, 2, 3) vary based on configuration. Refer to Chapter 9, “Buffer Management”. However, for this example, the following object sizes in bytes are assumed:

Small transmit buffers: 60
Large transmit buffers: 1518
Large receive buffers: 1518
Size of DMA receive descriptor: 8
Size of DMA transmit descriptor: 8
Ethernet interface data area: 7
Average Ethernet device driver data area: 108

With a 4-byte alignment on all memory pool objects, it results in a worst case disposal of three leading bytes for each object. In practice this is not usually true since the size of most objects tend to be even multiples of four. Therefore, the alignment is preserved after having aligned the start of the pool data area. However, this makes the case for allocating objects with size to the next greatest multiple of four in order to prevent lost space due to misalignment.

The approximate memory heap size may be determined according to the following expressions:

nbr buf per interface     = nbr small Tx buf + 
                            nbr large Tx buf + 
                            nbr large Rx buf 
  
nbr net buf per interface = nbr buf per interface 
  
nbr objects   =  nbr buf per interface     + 
                 nbr net buf per interface + 
                 nbr Rx descriptors        + 
                 nbr Tx descriptors        + 
                 1 Ethernet      data area + 
                 1 Device driver data area 
  
interface mem = (nbr small Tx buf       *   60) + 
                (nbr large Tx buf       * 1518) + 
                (nbr large Rx buf       * 1518) + 
                (nbr Rx descriptors     *    8) + 
                (nbr Tx descriptors     *    8) + 
                (Ethernet IF  data area *    7) + 
                (Ethernet Drv data area *  108) + 
                (nbr objects            *    3) 
  
total mem required = nbr interfaces * interface mem

Example

With the following configuration, the memory heap required is:

10 small transmit buffers
10 large transmit buffers
10 large receive buffers
6 receive descriptors
20 transmit descriptors
Ethernet interface (interface + device driver data area required)

          nbr     buf per interface = 10 + 10 + 10               = 30
          nbr net buf per interface = nbr buf per interface      = 30
          nbr objects               = (30 + 30 + 6 + 20 + 1 + 1) = 88
          interface mem             = (10 *   60) + 
                                      (10 * 1518) + 
                                      (10 * 1518) + 
                                      ( 6 *    8) +
                                      (20 *    8) +
                                      ( 1 *    7) +
                                      ( 1 *  108) +
                                      (88 *    3) = 31,547 bytes
           
          total mem required > 31,547 ( + localhost memory, if enabled)

The localhost interface, when enabled, requires a similar amount of memory except that it does not require Rx and Tx descriptors, an IF data area, or a device driver data area.

The value determined by these expressions is only an estimate. In some cases, it may be possible to reduce the size of the µC/LIB memory heap by inspecting µC/LIB (see libdoc) after all interfaces have been successfully initialized and any additional application allocations (if applicable) have been completed.