Memory is allocated to µC/TCP-IP device drivers through the µC/LIB memory module. You must enable and configure the size of the µC/LIB memory heap available to the system. The following configuration constants should be defined from within lib_cfg.h and set to match the application requirements.
#define LIB_MEM_CFG_ALLOC_EN DEF_ENABLED
#define LIB_MEM_CFG_HEAP_SIZE 58000
The heap size is specified in bytes. 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 by calling Mem_Init() prior to calling Net_Init(). We recommend initializing the memory module before calling OSStart(), or near the top of the startup task.
Approximate Calculation of Heap Memory
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
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: 152
- Large transmit buffers: 1594 for maximum sized TCP packets
- 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:
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)
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 the variable Mem_PoolHeap.SegSizeRem after all interfaces have been successfully initialized and any additional application allocations (if applicable) have been completed.
Excess heap space, if present, may be subtracted from the lib heap size configuration macro, LIB_MEM_CFG_HEAP_SIZE, present in app_cfg.h.