Pond Configuration Reference

This topic describes the file that configures the Comms pond.

At the moment, there is only one pond in the Comms Frameowrk. This pond manages the pools of MBufs available to the device drivers and to the Comms Framework components. The pond is initialised by the Root Server when the device starts. For each pool, you specify the initial and maximum number of buffers and the size of these buffers by specifying options in the c32start.ini file. This file is located in z\private\101f7988.

Options

To describe the pond, define MBufSizeAllocInfo <n> for each pool.

Each MBufSizeAllocInfo <n> line describes a pool of RMBufs. The <n> suffix must be a unique number.

# MBufSizeAllocInfo[n] = size, initial, growth, threshold
# for example 
MBufSizeAllocInfo1 = 128, 128, 64, 48 
MBufSizeAllocInfo2 = 1600, 64, 16, 12 

The following table lists theMBufSizeAllocInfo parameters in the order they must be specified:

Parameter Unit Description

size

bytes

Size of the payload of the RMBuf.

initial

buffers

Amount of pre-allocated RMBuf s in the pool at startup.

growth

buffers

Amount of RMBuf s added to the pool when it grows.

threshold

buffers

Minimum amount of free RMBuf s before making the pool grow. When the amount of free buffers in the pool falls below the threshold value, the pond adds growth buffers to the pool.

The initial allocation of memory is defined by the sum of the initial allocations from each of the MBufSizeAllocInfo <n> specifications.

If no MBufSizeAllocInfo <n> options are provided, the system builds a default pool of 128-byte buffers, initially set at 128 buffers, with a growth of 64 buffers and a threshold of 40 buffers.

Recommendations

Growth thresholds are typically set at around 25% so that the background allocator can allocate new buffers before the current pool is exhausted. Systems where there is potential to use buffers in sudden bursts should set the threshold to a higher number or start with a larger initial number of buffers.

Legacy code may rely on 128-byte buffers. 128-byte buffers also work well as the small buffers used when adding headers to the data. You should always specify a pool of 128-byte buffers in your c32start.ini file. You should also avoid having a pool of buffers smaller than 128 bytes, because some legacy code may assume 128 bytes as the minimum size.

The Maximum Transmission Unit (MTU) is an important characteristic of Communications protocols. The MTU is the maximum size of the data packet in a given layer. For example, the Ethernet protocol fixes its MTU to 1,500 bytes, and the 802.11 protocol has a 2,272-bytes MTU. To ensure that incoming data can be written into a single buffer rather than split, you need to specify your pools according to the protocols in use in your system. For each of these protocols, the pond should contain a pool with buffers as large or larger than the MTU. Protocols with similar MTUs usually share the same pool, to avoid increasing the allocation time with searches through too many pools.

Increasing the number of pools increases the time required to fulfil an allocation request. Therefore, you should keep the number of pools small. You need to find a balance between searching many pools for a single adequate buffer and searching fewer pools but having to construct a chain of buffers to fulfil an allocation request.

Note: if the c32start.ini configuration specifies more memory than the device has available, or an impossible combination of initial pool sizes and total pond size, the pond initialisation will fail and the Root Server will panic during device start-up.

Example

Here is a sample c32start.ini file:

[Global]

MBufSizeAllocInfo1 = 128, 128, 64, 48
MBufSizeAllocInfo2 = 1600, 64, 16, 12

This file corresponds to the following configuration:

  • The pond contains two pools for a total of 128x128 + 64x1600 = 118,784 bytes (116kB).

  • The first pool contains 128-byte buffers. It starts with 128 buffers and will grow by 64 buffers whenever fewer than 48 free buffers remain.

  • The second pool contains 1,600-byte buffers. It starts with 64 buffers and will grow by 16 buffers whenever fewer than 12 free buffers remain.