Main Page Modules Alphabetical List Data Structures File List Data Fields Globals
IXP425 OS Memory Buffer Pool Management (IxOsBuffPoolMgt) APIThe Public API for the Buffer Pool Management component.
More...
|
Data Structures |
struct | IxMbufPool |
| Implementation of buffer pool structure for use with non-VxWorks OS. More...
|
Defines |
#define | IX_MBUF_POOL_SIZE_ALIGN(size) |
| This macro takes an integer as an argument and rounds it up to be a multiple of the memory cache-line size.
|
#define | IX_MBUF_POOL_MBUF_AREA_SIZE_ALIGNED(count) |
| This macro calculates, from the number of mbufs required, the size of the memory area required to contain the mbuf headers for the buffers in the pool. The size to be used for each mbuf header is rounded up to a multiple of the cache-line size, to ensure each mbuf header aligns on a cache-line boundary. This macro is used by IX_MBUF_POOL_MBUF_AREA_ALLOC().
|
#define | IX_MBUF_POOL_DATA_AREA_SIZE_ALIGNED(count, size) |
| This macro calculates, from the number of mbufs required and the size of the data portion for each mbuf, the size of the data memory area required. The size is adjusted to ensure alignment on cache line boundaries. This macro is used by IX_MBUF_POOL_DATA_AREA_ALLOC().
|
#define | IX_MBUF_POOL_MBUF_AREA_ALLOC(count, memAreaSize) |
| Allocates the memory area needed for the number of mbuf headers specified by count. This macro ensures the mbuf headers align on cache line boundaries. This macro evaluates to a pointer to the memory allocated.
|
#define | IX_MBUF_POOL_DATA_AREA_ALLOC(count, size, memAreaSize) |
| Allocates the memory pool for the data portion of the pool mbufs. The number of mbufs is specified by count. The size of the data portion of each mbuf is specified by size. This macro ensures the mbufs are aligned on cache line boundaries This macro evaluates to a pointer to the memory allocated.
|
#define | IX_MBUF_POOL_FREE_COUNT(poolPtr) |
| Returns the number of free buffers currently in the specified pool.
|
#define | IX_MBUF_MAX_POOLS |
| The maximum number of pools that can be allocated.
|
#define | IX_MBUF_POOL_NAME_LEN |
| The maximum string length of the pool name.
|
#define | IX_MBUF_POOL_INIT(poolPtrPtr, count, size, name) |
| Wrapper macro for ixOsBuffPoolInit() See function description below for details.
|
#define | IX_MBUF_POOL_INIT_NO_ALLOC(poolPtrPtr, bufPtr, dataPtr, count, size, name) |
| Wrapper macro for ixOsBuffPoolInitNoAlloc() See function description below for details.
|
#define | IX_MBUF_POOL_GET(poolPtr, bufPtrPtr) |
| Wrapper macro for ixOsBuffPoolUnchainedBufGet() See function description below for details.
|
#define | IX_MBUF_POOL_PUT(bufPtr) |
| Wrapper macro for ixOsBuffPoolBufFree() See function description below for details.
|
#define | IX_MBUF_POOL_PUT_CHAIN(bufPtr) |
| Wrapper macro for ixOsBuffPoolBufChainFree() See function description below for details.
|
#define | IX_MBUF_POOL_SHOW(poolPtr) |
| Wrapper macro for ixOsBuffPoolShow() See function description below for details.
|
#define | IX_MBUF_POOL_MDATA_RESET(bufPtr) |
| Wrapper macro for ixOsBuffPoolBufDataPtrReset() See function description below for details.
|
Typedefs |
typedef IxMbufPool | IX_MBUF_POOL |
| The buffer pool structure, mapped to appropraite OS-specific implementation.
|
Enumerations |
enum | IxMbufPoolAllocationType {
IX_MBUF_POOL_TYPE_SYS_ALLOC,
IX_MBUF_POOL_TYPE_USER_ALLOC
} |
| Used to indicate how the pool memory was allocated. More...
|
Functions |
IX_STATUS | ixOsBuffPoolInit (IX_MBUF_POOL **poolPtrPtr, int count, int size, char *name) |
| This function creates a new buffer pool.
|
IX_MBUF_POOL * | ixOsBuffPoolAllocate (void) |
| This function allocates buffers from the available pool.
|
UINT32 | ixOsBuffPoolDataAreaSizeGet (int count, int size) |
| This function calcultes the size of data memory required to create a new buffer pool.
|
IX_MBUF * | ixOsBuffPoolMbufInit (int mbufSizeAligned, int dataSizeAligned, IX_MBUF_POOL *poolPtr) |
| Allocate memory for mbuf and data and initialise mbuf header fields.
|
UINT32 | ixOsBuffPoolMbufAreaSizeGet (int count) |
| This function calcultes the size of mbuf memory required to create a new buffer pool.
|
IX_STATUS | ixOsBuffPoolInitNoAlloc (IX_MBUF_POOL **poolPtrPtr, void *poolBufPtr, void *poolDataPtr, int count, int size, char *name) |
| This function creates a new buffer pool, with user-allocated memory.
|
IX_STATUS | ixOsBuffPoolUnchainedBufGet (IX_MBUF_POOL *poolPtr, IX_MBUF **newBufPtrPtr) |
| This function gets a buffer from the buffer pool.
|
IX_MBUF * | ixOsBuffPoolBufFree (IX_MBUF *bufPtr) |
| This function returns a buffer to the buffer pool.
|
void | ixOsBuffPoolBufChainFree (IX_MBUF *bufPtr) |
| This function returns a buffer chain to the buffer pool.
|
IX_STATUS | ixOsBuffPoolShow (IX_MBUF_POOL *poolPtr) |
| This function prints pool statistics.
|
IX_STATUS | ixOsBuffPoolBufDataPtrReset (IX_MBUF *bufPtr) |
| This function resets the data pointer of a buffer.
|
IX_STATUS | ixOsBuffPoolUninit (IX_MBUF_POOL *pool) |
| Unitialize buffer pool.
|
Detailed Description
The Public API for the Buffer Pool Management component.
Define Documentation
#define IX_MBUF_MAX_POOLS
|
|
|
The maximum number of pools that can be allocated.
- Note:
- This can safely be increased if more pools are required.
Definition at line 241 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_DATA_AREA_ALLOC |
( |
count, |
|
|
size, |
|
|
memAreaSize |
|
) |
|
|
|
Allocates the memory pool for the data portion of the pool mbufs. The number of mbufs is specified by count. The size of the data portion of each mbuf is specified by size. This macro ensures the mbufs are aligned on cache line boundaries This macro evaluates to a pointer to the memory allocated.
- Parameters:
-
int | [in] count - the number of mbufs the pool will contain |
int | [in] size - the desired size (in bytes) required for the data portion of each mbuf. Note that this size may be rounded up to ensure alignment on cache-line boundaries. |
int | [out] memAreaSize - the total amount of memory allocated |
- Returns:
- void * - a pointer to the allocated memory area
Definition at line 200 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_DATA_AREA_SIZE_ALIGNED |
( |
count, |
|
|
size |
|
) |
|
|
|
This macro calculates, from the number of mbufs required and the size of the data portion for each mbuf, the size of the data memory area required. The size is adjusted to ensure alignment on cache line boundaries. This macro is used by IX_MBUF_POOL_DATA_AREA_ALLOC().
- Note:
- Refer to the WindRiver "VxWorks 5.5 OS Libraries API Reference" manual for "netBufLib" library documentation, which explains the vxWorks implementation of this macro below.
- Parameters:
-
int | [in] count - The number of mbufs in the pool. |
int | [in] size - The desired size for each mbuf data portion. This size will be rounded up to a multiple of the cache-line size to ensure alignment on cache-line boundaries for each data block. |
- Returns:
- int - the total size required for the pool data area (aligned)
Definition at line 161 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_FREE_COUNT |
( |
poolPtr |
|
) |
|
|
|
Returns the number of free buffers currently in the specified pool.
- Parameters:
-
IX_MBUF_POOL | * [in] poolPtr - a pointer to the pool to query |
- Returns:
- int - the number of free buffers in the pool
Definition at line 214 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_GET |
( |
poolPtr, |
|
|
bufPtrPtr |
|
) |
|
|
#define IX_MBUF_POOL_INIT |
( |
poolPtrPtr, |
|
|
count, |
|
|
size, |
|
|
name |
|
) |
|
|
#define IX_MBUF_POOL_INIT_NO_ALLOC |
( |
poolPtrPtr, |
|
|
bufPtr, |
|
|
dataPtr, |
|
|
count, |
|
|
size, |
|
|
name |
|
) |
|
|
#define IX_MBUF_POOL_MBUF_AREA_ALLOC |
( |
count, |
|
|
memAreaSize |
|
) |
|
|
|
Allocates the memory area needed for the number of mbuf headers specified by count. This macro ensures the mbuf headers align on cache line boundaries. This macro evaluates to a pointer to the memory allocated.
- Parameters:
-
int | [in] count - the number of mbufs the pool will contain |
int | [out] memAreaSize - the total amount of memory allocated |
- Returns:
- void * - a pointer to the allocated memory area
Definition at line 178 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_MBUF_AREA_SIZE_ALIGNED |
( |
count |
|
) |
|
|
|
This macro calculates, from the number of mbufs required, the size of the memory area required to contain the mbuf headers for the buffers in the pool. The size to be used for each mbuf header is rounded up to a multiple of the cache-line size, to ensure each mbuf header aligns on a cache-line boundary. This macro is used by IX_MBUF_POOL_MBUF_AREA_ALLOC().
- Note:
- Refer to the WindRiver "VxWorks 5.5 OS Libraries API Reference" manual for "netBufLib" library documentation, which explains the vxWorks implementation of this macro below.
- Parameters:
-
int | [in] count - the number of buffers the pool will contain |
- Returns:
- int - the total size required for the pool mbuf area (aligned)
Definition at line 137 of file IxOsBuffPoolMgt.h. |
#define IX_MBUF_POOL_MDATA_RESET |
( |
bufPtr |
|
) |
|
|
#define IX_MBUF_POOL_NAME_LEN
|
|
#define IX_MBUF_POOL_PUT |
( |
bufPtr |
|
) |
|
|
#define IX_MBUF_POOL_PUT_CHAIN |
( |
bufPtr |
|
) |
|
|
#define IX_MBUF_POOL_SHOW |
( |
poolPtr |
|
) |
|
|
#define IX_MBUF_POOL_SIZE_ALIGN |
( |
size |
|
) |
|
|
|
This macro takes an integer as an argument and rounds it up to be a multiple of the memory cache-line size.
- Parameters:
-
int | [in] size - the size integer to be rounded up |
- Returns:
- int - the size, rounded up to a multiple of the cache-line size
Definition at line 113 of file IxOsBuffPoolMgt.h. |
Typedef Documentation
typedef NET_POOL IX_MBUF_POOL
|
|
|
The buffer pool structure, mapped to appropraite OS-specific implementation.
Definition at line 282 of file IxOsBuffPoolMgt.h. |
Enumeration Type Documentation
enum IxMbufPoolAllocationType
|
|
|
Used to indicate how the pool memory was allocated.
- Enumeration values:
-
IX_MBUF_POOL_TYPE_SYS_ALLOC |
mbuf pool allocated by the system |
IX_MBUF_POOL_TYPE_USER_ALLOC |
mbuf pool allocated by the user |
Definition at line 257 of file IxOsBuffPoolMgt.h. |
Function Documentation
|
This function allocates buffers from the available pool.
Thread Safe: yes
- Returns:
- IX_MBUF_POOL - pointer to mbuf pool.
|
ixOsBuffPoolBufChainFree |
( |
IX_MBUF * |
bufPtr |
) |
|
|
|
This function returns a buffer chain to the buffer pool.
- Parameters:
-
IX_MBUF | * [in] bufPtr - Pointer to head of the chain.. |
This function returns a buffer chain to the pool, making the buffers available again to ixOsBuffPoolUnchainedBufGet(). The buffer pointed to by bufPtr can be chained or unchained. If it is chained, all buffers in the chain will be returned to the pool.
Thread Safe: yes
- Precondition:
- bufPtr should point to a valid IX_MBUF structure
- Postcondition:
- The buffer (or chain of buffers) supplied will be returned to the pool for reuse.
- Returns:
-
|
ixOsBuffPoolBufDataPtrReset |
( |
IX_MBUF * |
bufPtr |
) |
|
|
|
This function resets the data pointer of a buffer.
- Parameters:
-
IX_MBUF | * [in] bufPtr - Pointer to a valid IX_MBUF buffer. |
This function resets the data pointer of a buffer to point to the start of the memory area allocated to the buffer for data (the buffer payload).
- Note:
- WARNING - This function can NOT be used if BOTH of following conditions are true:
Thread Safe: yes
- Precondition:
- bufPtr should point to a valid IX_MBUF structure
- A non-NULL pointer to the data memory area was supplied when the pool was created (see note above)
- The data pointer is pointing to somewhere within the buffer payload
- Postcondition:
- The data pointer of the mbuf header will point to the start of the data payload section of the buffer, as it did when it was originally obtained from the pool
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if the operation was not successful
|
ixOsBuffPoolBufFree |
( |
IX_MBUF * |
bufPtr |
) |
|
|
|
This function returns a buffer to the buffer pool.
- Parameters:
-
IX_MBUF | * [in] bufPtr - Pointer to a valid IX_MBUF buffer. |
This function returns a buffer to the pool, making it available again to ixOsBuffPoolUnchainedBufGet(). The buffer pointed to by bufPtr can be chained or unchained. If it is chained, only the head of the chain will be freed to the pool, and a pointer to the next buffer in the chain will be returned to the caller.
Thread Safe: yes
- Precondition:
- bufPtr should point to a valid IX_MBUF structure
- Postcondition:
- The buffer supplied will be returned to the pool for reuse.
- Returns:
- If supplied buffer was chained, a pointer to the next buffer in the chain is returned
- Otherwise NULL is returned
|
ixOsBuffPoolDataAreaSizeGet |
( |
int |
count, |
|
|
int |
size |
|
) |
|
|
|
This function calcultes the size of data memory required to create a new buffer pool.
- Parameters:
-
int | [in] count - The number of buffers to have in the pool. |
int | [in] size - The size of each buffer in the pool. |
Thread Safe: yes
- Returns:
- UINT32 the memory size required
|
ixOsBuffPoolInit |
( |
IX_MBUF_POOL ** |
poolPtrPtr, |
|
|
int |
count, |
|
|
int |
size, |
|
|
char * |
name |
|
) |
|
|
|
This function creates a new buffer pool.
- Parameters:
-
IX_MBUF_POOL | ** [out] poolPtrPtr - Pointer to a pool pointer. |
int | [in] count - The number of buffers to have in the pool. |
int | [in] size - The size of each buffer in the pool. |
char | * [in] name - A name string for the pool (used in pool show). |
This function initialises a pool of count buffers, each of size size. It allocates memory for the pool, fills in the pool and buffer data structures, and returns a pointer to the pool in the poolPtrPtr parameter. This pointer should be used with other functions on this API to use the pool. In the current implementation, only a limited number of pools can be allocated. The number of pools is decided by the value of IX_MBUF_MAX_POOLS.
- Note:
- This function has 2 implementations, depending on which OS the code is compiled for. If compiled for VxWorks, an mbuf pool will be created using the VxWorks "netBufLib" OS library. This will produce a pool of mbufs which can be used with the netBufLib library routines if required. If compiled for a different OS, a pool of generic buffers will be produced. These may need to be converted to a different buffer format (such as sk_buffs for Linux) to be used with OS network buffer manipulation routines if required. See the header file IxOsBuffMgt.h which maps the buffer implementations for each OS supported.
Thread Safe: no
- Precondition:
- poolPtrPtr should point to a valid IX_MBUF_POOL pointer
- Postcondition:
- A pool will be initialised and all memory required by the pool will be dynamically allocated from memory.
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if the pool could not be created
|
ixOsBuffPoolInitNoAlloc |
( |
IX_MBUF_POOL ** |
poolPtrPtr, |
|
|
void * |
poolBufPtr, |
|
|
void * |
poolDataPtr, |
|
|
int |
count, |
|
|
int |
size, |
|
|
char * |
name |
|
) |
|
|
|
This function creates a new buffer pool, with user-allocated memory.
- Parameters:
-
IX_MBUF_POOL | ** [out] poolPtrPtr - Pointer to a pool pointer. |
void | * [in] poolBufPtr - pointer to memory allocated with IX_MBUF_POOL_MBUF_AREA_ALLOC() |
void | * [in] poolDataPtr - pointer to memory allocated with IX_MBUF_POOL_DATA_AREA_ALLOC() |
int | [in] count - The number of buffers to have in the pool. |
int | [in] size - The size of each buffer in the pool (i.e. the amount of payload data octets each buffer can hold). |
char | * [in] name - A name string for the pool (used in pool show). |
This function initialises a pool of count buffers, each of size size. It fills in the pool and buffer data structures, and returns a pointer to the pool in the poolPtrPtr parameter. This pointer should be used with other functions on this API to use the pool. In the current implementation, only a limited number of pools can be allocated. The number of pools is decided by the value of IX_MBUF_MAX_POOLS.
- Note:
- This function has 2 implementations, depending on which OS the code is compiled for. If compiled for VxWorks, an mbuf pool will be created using the VxWorks "netBufLib" OS library. This will produce a pool of mbufs which can be used with the netBufLib library routines if required. If compiled for a different OS, a pool of generic buffers will be produced. These may need to be converted to a different buffer format (such as sk_buffs for Linux) to be used with OS network buffer manipulation routines if required. See the header file IxOsBuffMgt.h which maps the buffer implementations for each OS supported.
The pointer to the data area can optionally be NULL, to indicate that the data memory area for the mbuf payload will be assigned by the user later on. In this case, it is expected that the user would assign the data pointer of each mbuf returned by ixOsBuffPoolUnchainedBufGet(). This also means that the function ixOsBuffPoolBufDataPtrReset() cannot be used on buffers from this pool. WARNING - This pointer CANNOT be NULL if VxWorks implementation is used!
Thread Safe: no
- Precondition:
- poolPtrPtr should point to a valid IX_MBUF_POOL pointer
- The memory required for the pool, for mbuf structures and data (if required), should be allocated with the specified macros. See params poolBufPtr and poolDataPtr
- Postcondition:
- A pool will be initialised and all memory required by the pool will be dynamically allocated from memory.
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if the pool could not be created
|
ixOsBuffPoolMbufAreaSizeGet |
( |
int |
count |
) |
|
|
|
This function calcultes the size of mbuf memory required to create a new buffer pool.
- Parameters:
-
int | [in] count - The number of buffers to have in the pool. |
Thread Safe: yes
- Returns:
- UINT32 the memory size required
|
ixOsBuffPoolMbufInit |
( |
int |
mbufSizeAligned, |
|
|
int |
dataSizeAligned, |
|
|
IX_MBUF_POOL * |
poolPtr |
|
) |
|
|
|
Allocate memory for mbuf and data and initialise mbuf header fields.
This function allocates memory for an individual mbuf contained in an mbuf wrapper, defined above. The purpose of the wrapper is to add extra fields to the mbuf header which are hidden from the user. These extra fields are intended for use only by IxOsBuffPoolMgt.
- Parameters:
-
int | [in] mbufSizeAligned - Size aligned mbuf. |
int | [in] dataSizeAligned - Size aligned data. |
IX_MBUF_POOL | *[in]poolPtr - Pointer to buffer pool. |
- Returns:
- IX_MBUF_POOL *[in]poolPtr - Pointer to MBuf
|
|
This function prints pool statistics.
- Parameters:
-
IX_MBUF_POOL | * [in] poolPtr - A pointer to a valid pool. |
This function prints pool statistics, such as the number of free buffers in each pool. The actual statistics printed depends on the implementation which may differ between platforms. This funtion can serve as a useful debugging aid.
Thread Safe: yes
- Precondition:
- poolPtr should point to a valid IX_MBUF_POOL structure
- Postcondition:
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if the pool statistics could not be printed.
|
ixOsBuffPoolUnchainedBufGet |
( |
IX_MBUF_POOL * |
poolPtr, |
|
|
IX_MBUF ** |
newBufPtrPtr |
|
) |
|
|
|
This function gets a buffer from the buffer pool.
- Parameters:
-
IX_MBUF_POOL | * [in] poolPtr - Pointer to a valid pool. |
IX_MBUF | ** [out] newBufPtrPtr - A pointer to a valid IX_MBUF pointer. |
This function gets a free buffer from the specified pool, and returns a pointer to the buffer in the newBufPtrPtr parameter. The buffer obtained will be a single unchained buffer of the size specified when the pool was initialised.
Thread Safe: yes
- Precondition:
- poolPtr should point to a valid IX_MBUF_POOL structure
- newBufPtrPtr should point to a valid IX_MBUF pointer
- Postcondition:
- A free buffer will be allocated from the pool and newBufPtrPtr can be dereferenced to access the pointer to the buffer.
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if a free buffer could not be obtained
|
|
Unitialize buffer pool.
- Parameters:
-
IX_MBUF_POOL | *[in]pool - pointer to buffer pool |
- Returns:
- IX_SUCCESS if the operation was successful
- IX_FAIL if the operation was not successful
|
|