VxWorks Reference Manual : Libraries
netBufLib - network buffer library
netBufLibInit( ) - initialize netBufLib
netPoolInit( ) - initialize a netBufLib-managed memory pool
netPoolDelete( ) - delete a memory pool
netMblkFree( ) - free an mBlk back to its memory pool
netClBlkFree( ) - free a clBlk-cluster construct back to the memory pool
netClFree( ) - free a cluster back to the memory pool
netMblkClFree( ) - free an mBlk-clBlk-cluster construct
netMblkClChainFree( ) - free a chain of mBlk-clBlk-cluster constructs
netMblkGet( ) - get an mBlk from a memory pool
netClBlkGet( ) - get a clBlk
netClusterGet( ) - get a cluster from the specified cluster pool
netMblkClGet( ) - get a clBlk-cluster and join it to the specified mBlk
netTupleGet( ) - get an mBlk-clBlk-cluster
netClBlkJoin( ) - join a cluster to a clBlk structure
netMblkClJoin( ) - join an mBlk to a clBlk-cluster construct
netClPoolIdGet( ) - return a CL_POOL_ID for a specified buffer size
netMblkToBufCopy( ) - copy data from an mBlk to a buffer
netMblkDup( ) - duplicate an mBlk
netMblkChainDup( ) - duplicate an mBlk chain
This library contains routines that you can use to organize and maintain a memory pool that consists of pools of mBlk structures, pools of clBlk structures, and pools of clusters. The mBlk and clBlk structures are used to manage the clusters. The clusters are containers for the data described by the mBlk and clBlk structures.
These structures and the various routines of this library constitute a buffering API that has been designed to meet the needs both of network protocols and network device drivers.
The mBlk structure is the primary vehicle for passing data between a network driver and a protocol. However, the mBlk structure must first be properly joined with a clBlk structure that was previously joined with a cluster. Thus, the actual vehicle for passing data is not merely an mBlk structure but an mBlk-clBlk-cluster construct.
To include netBufLib in VxWorks, add the INCLUDE_NETWORK component. This configuration uses the netBufLibInit( ) routine to setup the network stack buffer library.
netBufLib.h
-----------| |-----------|
| mBlk | | mBlk |
| | | |
| | | |
| | | |
| | | |
|-----------\ /-----------|
\ /
\ /
\ /
\|------------|/
| clBlk |
| |
|clRefCnt = 2|
| |
| |
|------------\
\
|---------------|
| cluster |
| |
| |
|---------------|
netBufLibInit( ) - initialize netBufLib
STATUS netBufLibInit (void)
This routine executes during system startup if INCLUDE_NETWORK is defined when the image is built. It links the network buffer library into the image.
OK or ERROR.
netPoolInit( ) - initialize a netBufLib-managed memory pool
STATUS netPoolInit ( NET_POOL_ID pNetPool, /* pointer to a net pool */ M_CL_CONFIG * pMclBlkConfig, /* pointer to a mBlk configuration */ CL_DESC * pClDescTbl, /* pointer to cluster desc table */ int clDescTblNumEnt, /* number of cluster desc entries */ POOL_FUNC * pFuncTbl /* pointer to pool function table */ )
Call this routine to set up a netBufLib-managed memory pool. Within this pool, netPoolInit( ) organizes several sub-pools: one for mBlk structures, one for clBlk structures, and as many cluster sub-pools are there are cluster sizes. As input, this routine expects the following parameters:
- pNetPool
- Expects a NET_POOL_ID that points to a previously allocated NET_POOL structure. You need not initialize any values in this structure. That is handled by netPoolInit( ).
- pMclBlkConfig
- Expects a pointer to a previously allocated and initialized M_CL_CONFIG structure. Within this structure, you must provide four values: mBlkNum, a count of mBlk structures; clBlkNum, a count of clBlk structures; memArea, a pointer to an area of memory that can contain all the mBlk and clBlk structures; and memSize, the size of that memory area. For example, you can set up an M_CL_CONFIG structure as follows:
M_CL_CONFIG mClBlkConfig = /* mBlk, clBlk configuration table */ { mBlkNum clBlkNum memArea memSize ---------- ---- ------- ------- 400, 245, 0xfe000000, 21260 };You can calculate the memArea and memSize values. Such code could first define a table as shown above, but set both memArea and memSize as follows:mClBlkConfig.memSize = (mClBlkConfig.mBlkNum * (M_BLK_SZ + sizeof(long))) + (mClBlkConfig.clBlkNum * CL_BLK_SZ);You can set the memArea value to a pointer to private memory, or you can reserve the memory with a call to malloc( ). For example:mClBlkConfig.memArea = malloc(mClBlkConfig.memSize);The netBufLib.h file defines M_BLK_SZ as:sizeof(struct mBlk)Currently, this evaluates to 32 bytes. Likewise, this file defines CL_BLK_SZ as:sizeof(struct clBlk)Currently, this evaluates to 32 bytes.When choosing values for mBlkNum and clBlkNum, remember that you need as many clBlk structures as you have clusters (data buffers). You also need at least as many mBlk structures as you have clBlk structures, but you will most likely need more. That is because netBufLib shares buffers by letting multiple mBlk structures join to the same clBlk and thus to its underlying cluster. The clBlk keeps a count of the number of mBlk structures that reference it.
- pClDescTbl
- Expects a pointer to a table of previously allocated and initialized CL_DESC structures. Each structure in this table describes a single cluster pool. You need a dedicated cluster pool for each cluster size you want to support. Within each CL_DESC structure, you must provide four values: clusterSize, the size of a cluster in this cluster pool; num, the number of clusters in this cluster pool; memArea, a pointer to an area of memory that can contain all the clusters; and memSize, the size of that memory area.
Thus, if you need to support six different cluster sizes, this parameter must point to a table containing six CL_DESC structures. For example, consider the following:
CL_DESC clDescTbl [] = /* cluster descriptor table */ { /* clusterSize num memArea memSize ---------- ---- ------- ------- */ {64, 100, 0x10000, 6800}, {128, 50, 0x20000, 6600}, {256, 50, 0x30000, 13000}, {512, 25, 0x40000, 12900}, {1024, 10, 0x50000, 10280}, {2048, 10, 0x60000, 20520} };As with the memArea and memSize members in the M_CL_CONFIG structure, you can set these members of the CL_DESC structures by calculation after you create the table. The formula would be as follows:clDescTbl[n].memSize = (clDescTbl[n].num * (clDescTbl[n].clusterSize + sizeof(long)));The memArea member can point to a private memory area that you know to be available for storing clusters, or you can use malloc( ).clDescTbl[n].memArea = malloc( clDescTbl[n].memSize );Valid cluster sizes range from 64 bytes to 65536 bytes. If there are multiple cluster pools, valid sizes are further restricted to powers of two (for example, 64, 128, 256, and so on). If there is only one cluster pool (as is often the case for the memory pool specific to a single device driver), there is no power of two restriction. Thus, the cluster can be of any size between 64 bytes and 65536 bytes on 4-byte alignment. A typical buffer size for Ethernet devices is 1514 bytes. However, because a cluster size requires a 4-byte alignment, the cluster size for this Ethernet buffer would have to be increased to at least 1516 bytes.
- clDescTblNumEnt
- Expects a count of the elements in the CL_DESC table referenced by the pClDescTbl parameter. This is a count of the number of cluster pools. You can get this value using the NELEMENTS macro defined in vxWorks.h. For example:
int clDescTblNumEnt = (NELEMENTS(clDescTbl));- pFuncTbl
- Expects a NULL or a pointer to a function table. This table contains pointers to the functions used to manage the buffers in this memory pool. Using a NULL for this parameter tells netBufLib to use its default function table. If you opt for the default function table, every mBlk and every cluster is prepended by a 4-byte header (which is why the size calculations above for clusters and mBlk structures contained an extra sizeof(long)). However, users need not concern themselves with this header when accessing these buffers. The returned pointers from functions such as netClusterGet( ) return pointers to the start of data, which is just after the header.
Assuming you have set up the configuration tables as shown above, a typical call to netPoolInit( ) would be as follows:
int clDescTblNumEnt = (NELEMENTS(clDescTbl)); NET_POOL netPool; NET_POOL_ID pNetPool = &netPool; if (netPoolInit (pNetPool, &mClBlkConfig, &clDescTbl [0], clDescTblNumEnt, NULL) != OK) return (ERROR);
OK or ERROR.
S_netBufLib_MEMSIZE_INVALID
S_netBufLib_CLSIZE_INVALID
S_netBufLib_NO_SYSTEM_MEMORY
S_netBufLib_MEM_UNALIGNED
S_netBufLib_MEMSIZE_UNALIGNED
S_netBufLib_MEMAREA_INVALID
netPoolDelete( ) - delete a memory pool
STATUS netPoolDelete ( NET_POOL_ID pNetPool /* pointer to a net pool */ )
This routine deletes the specified netBufLib-managed memory pool.
OK or ERROR.
S_netBufLib_NETPOOL_INVALID
netMblkFree( ) - free an mBlk back to its memory pool
void netMblkFree ( NET_POOL_ID pNetPool, /* pointer to the net pool */ M_BLK_ID pMblk /* mBlk to free */ )
This routine frees the specified mBlk back to the specified memory pool.
N/A
netClBlkFree( ) - free a clBlk-cluster construct back to the memory pool
void netClBlkFree ( NET_POOL_ID pNetPool, /* pointer to the net pool */ CL_BLK_ID pClBlk /* pointer to the clBlk to free */ )
This routine decrements the reference counter in the specified clBlk. If the reference count falls to zero, this routine frees both the clBlk and its associated cluster back to the specified memory pool.
N/A
netClFree( ) - free a cluster back to the memory pool
void netClFree ( NET_POOL_ID pNetPool, /* pointer to the net pool */ UCHAR * pClBuf /* pointer to the cluster buffer */ )
This routine returns the specified cluster buffer back to the specified memory pool.
N/A
netMblkClFree( ) - free an mBlk-clBlk-cluster construct
M_BLK_ID netMblkClFree ( M_BLK_ID pMblk /* pointer to the mBlk */ )
For the specified mBlk-clBlk-cluster construct, this routine frees the mBlk back to the specified memory pool. It also decrements the reference count in the clBlk structure. If the reference count falls to zero, no other mBlk structure reference this clBlk. In that case, this routine also frees the clBlk structure and its associated cluster back to the specified memory pool.
If the specified mBlk was part of an mBlk chain, this routine returns a pointer to the next mBlk. Otherwise, it returns a NULL.
S_netBufLib_MBLK_INVALID
netMblkClChainFree( ) - free a chain of mBlk-clBlk-cluster constructs
void netMblkClChainFree ( M_BLK_ID pMblk /* pointer to the mBlk */ )
For the specified chain of mBlk-clBlk-cluster constructs, this routine frees all the mBlk structures back to the specified memory pool. It also decrements the reference count in all the clBlk structures. If the reference count in a clBlk falls to zero, this routine also frees that clBlk and its associated cluster back to the specified memory pool.
N/A
S_netBufLib_MBLK_INVALID
netMblkGet( ) - get an mBlk from a memory pool
M_BLK_ID netMblkGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ int canWait, /* M_WAIT/M_DONTWAIT */ UCHAR type /* mBlk type */ )
This routine allocates an mBlk from the specified memory pool, if available.
- pNetPool
- Expects a pointer to the pool from which you want an mBlk.
- canWait
- Expects either M_WAIT or M_DONTWAIT. If no mBlk is immediately available, the M_WAIT value allows this routine to repeat the allocation attempt after performing garbage collection. It omits these steps when the M_DONTWAIT value is used.
- type
- Expects the type value that you want to associate with the returned mBlk.
M_BLK_ID or NULL if no mBlk is available.
S_netBufLib_MBLK_INVALID
netClBlkGet( ) - get a clBlk
CL_BLK_ID netClBlkGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ int canWait /* M_WAIT/M_DONTWAIT */ )
This routine gets a clBlk from the specified memory pool.
- pNetPool
- Expects a pointer to the pool from which you want a clBlk.
- canWait
- Expects either M_WAIT or M_DONTWAIT. If no clBlk is immediately available, the M_WAIT value allows this routine to repeat the allocation attempt after performing garbage collection. It omits these steps when the M_DONTWAIT value is used.
CL_BLK_ID or a NULL if no clBlk was available.
netClusterGet( ) - get a cluster from the specified cluster pool
char * netClusterGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ CL_POOL_ID pClPool /* ptr to the cluster pool */ )
This routine gets a cluster from the specified cluster pool pClPool within the specified memory pool pNetPool.
This routine returns a character pointer to a cluster buffer or NULL if none was available.
netMblkClGet( ) - get a clBlk-cluster and join it to the specified mBlk
STATUS netMblkClGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ M_BLK_ID pMblk, /* mBlk to embed the cluster in */ int bufSize, /* size of the buffer to get */ int canWait, /* wait or dontwait */ BOOL bestFit /* TRUE/FALSE */ )
This routine gets a clBlk-cluster pair from the specified memory pool and joins it to the specified mBlk structure. The mBlk-clBlk-cluster triplet it produces is the basic structure for handling data at all layers of the network stack.
.SH
- pNetPool
- Expects a pointer to the memory pool from which you want to get a free clBlk-cluster pair.
- pMbkl
- Expects a pointer to the mBlk structure (previously allocated) to which you want to join the retrieved clBlk-cluster pair.
- bufSize
- Expects the size, in bytes, of the cluster in the clBlk-cluster pair.
- canWait
- Expects either M_WAIT or M_DONTWAIT. If either item is not immediately available, the M_WAIT value allows this routine to repeat the allocation attempt after performing garbage collection. It omits those steps when the M_DONTWAIT value is used.
- bestFit
- Expects either TRUE or FALSE. If bestFit is TRUE and a cluster of the exact size is unavailable, this routine gets a larger cluster (if available). If bestFit is FALSE and an exact size cluster is unavailable, this routine gets either a smaller or a larger cluster (depending on what is available). Otherwise, it returns immediately with an ERROR value. For memory pools containing only one cluster size, bestFit should always be set to FALSE.
"RETURNS" OK or ERROR.
S_netBufLib_CLSIZE_INVALID
netTupleGet( ) - get an mBlk-clBlk-cluster
M_BLK_ID netTupleGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ int bufSize, /* size of the buffer to get */ int canWait, /* wait or dontwait */ UCHAR type, /* type of data */ BOOL bestFit /* TRUE/FALSE */ )
This routine gets an mBlk-clBlk-cluster triplet from the specified memory pool. The resulting structure is the basic method for accessing data at all layers of the network stack.
- pNetPool
- Expects a pointer to the memory pool with which you want to build a mBlk-clBlk-cluster triplet.
- bufSize
- Expects the size, in bytes, of the cluster in the clBlk-cluster pair.
- canWait
- Expects either M_WAIT or M_DONTWAIT. If any item in the triplet is not immediately available, the M_WAIT value allows this routine to repeat the allocation attempt after performing garbage collection. The M_DONTWAIT value prevents those extra steps.
- type
- Expects the type of data. For example MT_DATA, MT_HEADER. The various values for this type are defined in netBufLib.h.
- bestFit
- Expects either TRUE or FALSE. If bestFit is TRUE and a cluster of the exact size is unavailable, this routine gets a larger cluster (if available). If bestFit is FALSE and an exact size cluster is unavailable, this routine gets either a smaller or a larger cluster (depending on what is available). Otherwise, it returns immediately with an ERROR value. For memory pools containing only one cluster size, bestFit should always be set to FALSE.
* M_BLK_ID or NULL.
S_netBufLib_MBLK_INVALID
S_netBufLib_CLSIZE_INVALID
S_netBufLib_NETPOOL_INVALID
netClBlkJoin( ) - join a cluster to a clBlk structure
CL_BLK_ID netClBlkJoin ( CL_BLK_ID pClBlk, /* pointer to a cluster Blk */ char * pClBuf, /* pointer to a cluster buffer */ int size, /* size of the cluster buffer */ FUNCPTR pFreeRtn, /* pointer to the free routine */ int arg1, /* argument 1 of the free routine */ int arg2, /* argument 2 of the free routine */ int arg3 /* argument 3 of the free routine */ )
This routine joins the previously reserved cluster specified by pClBuf to the previously reserved clBlk structure specified by pClBlk. The size parameter passes in the size of the cluster referenced in pClBuf. The arguments pFreeRtn, arg1, arg2, arg3 set the values of the pCLFreeRtn, clFreeArg1, clFreeArg2, and clFreeArg1, members of the specified clBlk structure.
CL_BLK_ID or NULL.
netMblkClJoin( ) - join an mBlk to a clBlk-cluster construct
M_BLK_ID netMblkClJoin ( M_BLK_ID pMblk, /* pointer to an mBlk */ CL_BLK_ID pClBlk /* pointer to a cluster Blk */ )
This routine joins the previously reserved mBlk referenced in pMblk to the clBlk-cluster construct referenced in pClBlk. Internally, this routine sets the M_EXT flag in mBlk.mBlkHdr.mFlags. It also and sets the mBlk.mBlkHdr.mData to point to the start of the data in the cluster.
M_BLK_ID or NULL.
netClPoolIdGet( ) - return a CL_POOL_ID for a specified buffer size
CL_POOL_ID netClPoolIdGet ( NET_POOL_ID pNetPool, /* pointer to the net pool */ int bufSize, /* size of the buffer */ BOOL bestFit /* TRUE/FALSE */ )
This routine returns a CL_POOL_ID for a cluster pool containing clusters that match the specified bufSize. If bestFit is TRUE, this routine returns a CL_POOL_ID for a pool that contains clusters greater than or equal to bufSize. If bestFit is FALSE, this routine returns a CL_POOL_ID for a cluster from whatever cluster pool is available. If the memory pool specified by pNetPool contains only one cluster pool, bestFit should always be FALSE.
CL_POOL_ID or NULL.
netMblkToBufCopy( ) - copy data from an mBlk to a buffer
int netMblkToBufCopy ( M_BLK_ID pMblk, /* pointer to an mBlk */ char * pBuf, /* pointer to the buffer to copy */ FUNCPTR pCopyRtn /* function pointer for copy routine */ )
This routine copies data from the mBlk chain referenced in pMblk to the buffer referenced in pBuf. It is assumed that pBuf points to enough memory to contain all the data in the entire mBlk chain. The argument pCopyRtn expects either a NULL or a function pointer to a copy routine. The arguments passed to the copy routine are source pointer, destination pointer and the length of data to copy. If pCopyRtn is NULL, netMblkToBufCopy( ) uses a default routine to extract the data from the chain.
The length of data copied or zero.
netMblkDup( ) - duplicate an mBlk
M_BLK_ID netMblkDup ( M_BLK_ID pSrcMblk, /* pointer to source mBlk */ M_BLK_ID pDestMblk /* pointer to the destination mBlk */ )
This routine copies the references from a source mBlk in an mBlk-clBlk-cluster construct to a stand-alone mBlk. This lets the two mBlk structures share the same clBlk-cluster construct. This routine also increments the reference count in the shared clBlk. The pSrcMblk expects a pointer to the source mBlk. The pDescMblk parameter expects a pointer to the destination mBlk.
A pointer to the destination mBlk or NULL if the source mBlk referenced in pSrcMblk is not part of a valid mBlk-clBlk-cluster construct.
netMblkChainDup( ) - duplicate an mBlk chain
M_BLK_ID netMblkChainDup ( NET_POOL_ID pNetPool, /* pointer to the pool */ M_BLK_ID pMblk, /* pointer to source mBlk chain */ int offset, /* offset to duplicate from */ int len, /* length to copy */ int canWait /* M_DONTWAIT/M_WAIT */ )
This routine makes a copy of an mBlk chain starting at offset bytes from the beginning of the chain and continuing for len bytes. If len is M_COPYALL, then this routine will copy the entire mBlk chain from the offset.
This routine copies the references from a source pMblk chain to a newly allocated mBlk chain. This lets the two mBlk chains share the same clBlk-cluster constructs. This routine also increments the reference count in the shared clBlk. The pMblk expects a pointer to the source mBlk chain. The pNetPool parameter expects a pointer to the netPool from which the new mBlk chain is allocated.
The canWait parameter determines the behavior if any required mBlk is not immediately available. A value of M_WAIT allows this routine to repeat the allocation attempt after performing garbage collection. The M_DONTWAIT value prevents those extra steps.
netMblkDup( )
A pointer to the newly allocated mBlk chain or NULL.
S_netBufLib_INVALID_ARGUMENT
S_netBufLib_NO_POOL_MEMORY