µ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:
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 µC/LIB (see libdoc) after all interfaces have been successfully initialized and any additional application allocations (if applicable) have been completed.