Main Page   Modules   Alphabetical List   Data Structures   File List   Data Fields   Globals  

IXP425 OS Memory Buffer Pool Management (IxOsBuffPoolMgt) API

The 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_POOLixOsBuffPoolAllocate (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   ) 
 

Wrapper macro for ixOsBuffPoolUnchainedBufGet() See function description below for details.

Definition at line 319 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_INIT poolPtrPtr,
count,
size,
name   ) 
 

Wrapper macro for ixOsBuffPoolInit() See function description below for details.

Definition at line 301 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_INIT_NO_ALLOC poolPtrPtr,
bufPtr,
dataPtr,
count,
size,
name   ) 
 

Wrapper macro for ixOsBuffPoolInitNoAlloc() See function description below for details.

Definition at line 310 of file IxOsBuffPoolMgt.h.

#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   ) 
 

Wrapper macro for ixOsBuffPoolBufDataPtrReset() See function description below for details.

Definition at line 355 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_NAME_LEN
 

The maximum string length of the pool name.

Definition at line 248 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_PUT bufPtr   ) 
 

Wrapper macro for ixOsBuffPoolBufFree() See function description below for details.

Definition at line 328 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_PUT_CHAIN bufPtr   ) 
 

Wrapper macro for ixOsBuffPoolBufChainFree() See function description below for details.

Definition at line 337 of file IxOsBuffPoolMgt.h.

#define IX_MBUF_POOL_SHOW poolPtr   ) 
 

Wrapper macro for ixOsBuffPoolShow() See function description below for details.

Definition at line 346 of file IxOsBuffPoolMgt.h.

#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

IX_MBUF_POOL * ixOsBuffPoolAllocate void   ) 
 

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:
  • none

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

ixOsBuffPoolShow IX_MBUF_POOL poolPtr  ) 
 

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

ixOsBuffPoolUninit IX_MBUF_POOL pool  ) 
 

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

Automatically generated from sources. © Intel Corp. 2003