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_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 |  | ) |
| 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: the pool was created using ixOsBuffPoolInitNoAlloc() a NULL value was supplied at the time of creation for the bufDataPtr parameter of ixOsBuffPoolInitNoAlloc(). See the API description of the function ixOsBuffPoolInitNoAlloc(). 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