A

Using netBufLib

A.1 Introduction

Using netBufLib, you can set up and manage a memory pool specialized to the needs of network interface drivers and network services (protocols). In a netBufLib memory pool, data is held in clusters. Elements of the network stack exchange references to these clusters using data structures called mBlks and clBlks.

The VxWorks stack uses netBufLib to manage its internal system and data memory pools. Likewise, the supplied network drivers use netBufLib to manage their memory pools. This facilitates their sharing buffers with the MUX, which expects buffers organized using mBlk and clBlk structures.

To include netBufLib in VxWorks, include INCLUDE_NETWORK.

Replacing netBufLib

Because the buffer management code in the VxWorks stack access only the published netBufLib API, you can safely replace the shipped netBufLib implementation with your own. If your implementation supports all the public netBufLib function calls and structures, the current stack and network interface drivers should continue to function normally. However, the replacements must conform to the API of the existing routines. Otherwise, the network stack will be unable to access memory.

A.2 How a netBufLib Pool Organizes Memory

The memory in a netBufLib memory pool is organized using pools of mBlk structures, pools of clBlk structures, and pools of cluster buffers (simple character arrays). A netPoolInit( ) call joins all these sub-pools into a single pool that is organized around M_CL_CONFIG and CL_DESC structures.

To reserve a buffer from a netBufLib pool, call netTupleGet( ). This call returns a tuple, a construct consisting of an mBlk structure, a clBlk structure, and a cluster buffer. The mBlk and clBlk structures provide information necessary to support buffer loaning and buffer chaining for the data that is stored in the clusters. The clusters come in sizes determined by the CL_DESC table that describes the memory pool.

Clusters

Valid cluster sizes are within bounds set by powers of two to up to 64KB (65536) - see Figure A-5. Exactly which cluster sizes are valid within a particular memory pool depends on the contents of the CL_DESC table submitted to the netPoolInit( ) call that initializes the pool.

mBlks and clBlks

To support buffer (cluster) loaning, netBufLib tracks clusters using mBlk and clBlk structures. For each cluster in a memory pool, there needs to be a corresponding clBlk structure. The clBlk structure tracks how many mBlks share its underlying cluster. Above the clBlk, is the mBlk structure. This structure stores a link to a clBlk and can store a link to another mBlk. By chaining mBlks, you can reference an arbitrarily large amount of data, such as a packet chain (see Figure A-1).

Figure A-1 : Presentation of Two Packets in One mBlk Chain

The mBlk structure is the primary object you use to access the data that resides in a memory pool. Because an mBlk is only a reference to the data available through a clBlk, network layers can exchange data without copying between internal buffers. Each mBlk structure stores separate links for the data within a packet and for the data that starts a new packet.

Because the mBlk references the cluster data through a clBlk, duplicating an mBlk need not copy the cluster data. For example, mBlk A in Figure A-2 is a duplicate of mBlk 1. Creating this duplicate did not require the copying of the underlying cluster. However, the duplication did require incrementing the external reference count stored in the clBlk that manages the underlying cluster. This is critical when it comes time to free an mBlk.

Figure A-2 : Different mBlks Can Share the Same Cluster

If you use netBufLib to free the mBlk, the mBlk is freed back to the pool and the reference count in the underlying clBlk is decremented. If this reference count drops to zero (indicating that no mBlks are referencing the cluster), the clBlk and cluster are also freed back to the memory pool.

A.3 Setting Up a Memory Pool

Setting up a memory pool culminates in a call to netPoolInit( ). Before calling netPoolInit( ), you must have allocated all the memory you want to include in the pool. You then reference that memory in the CL_DESC and M_CL_CONFIG structures that you submit to netPoolInit( ). The CL_DESC and M_CL_CONFIG structures supply netPoolInit( ) with the memory pointers, structure counts, buffer sizes, and buffer counts that define the memory pool.

M_CL_CONFIG

An M_CL_CONFIG table contains only one row. The elements in the row specify the pool's clBlk count, its mBlk count, and a previously allocated memory area identified by a starting address and a size. The count values are analogous to the NET_NUM_BLK and NET_CL_BLKS values you specified for the network system memory table.

The clBlk count you specify must be equal to the number of clusters in the memory pool. The mBlk count must be at least as large, but could be larger, depending on how you use the memory pool. The allocated memory referenced in the supplied pointer should be large enough to contain all the clBlk and mBlk structures specified by the supplied counts.

CL_DESC

A CL_DESC table associates a cluster size with a cluster count and a memory area identified by a starting address and a size. Although you did not need to provide the memory area starting address and size in clDescTbl[ ] and sysClDescTbl[ ], you do need to provide this information in any CL_DESC you create. In other words, you must make the memory allocation calls that reserve memory for the pool.

If you are setting up a CL_DESC table for a network driver pool, your table will likely need only one row. This row specifies a cluster size close to the MTU of the underlying device. For example, the Lance Ethernet driver uses a cluster size is 1520 bytes, which is the Ethernet MTU plus some slack (see Figure A-3). The CL_DESC table for a network protocol will likely contain several rows. This is because protocols typically require buffers of several different sizes (see Figure A-4).

Figure A-3 : A Driver Memory Pool

Figure A-4 : A Protocol Memory Pool

When deciding on cluster sizes, choose a size that is alone within a power of two boundary (see Figure A-5) and that is large enough to contain the buffer you want to store in the cluster. In addition, no two rows in the table can share the use the same cluster size.

Figure A-5 shows two examples of sets of cluster sizes. The first, {48, 92, 244}, is correct, because there is at least one power of two between the different sizes. The second, {48, 88, 132, 192}, is incorrect, because the cluster sizes of 132 and 192 both fall between the adjacent powers of two of 128 and 256.

Figure A-5 : Choosing Correct Cluster Sizes

A.4 Storing and Using Data in Clusters

When your driver or protocol needs a buffer for a packet, reserve an appropriately sized cluster buffer from an established memory pool. Then associate that cluster with an mBlk and a clBlk structure from the pool.

To create an mBlk/clBlk/cluster construct one step at a time:

Call netClusterGet( ) to reserve a cluster buffer for your data.

Call netClBlkGet( ) to reserve a clBlk structure.

Call netClBlkJoin( ) to join the clBlk to the cluster containing the packet.

Call netMblkGet( ) to reserve a mBlk structure.

Call netMblkClJoin( ) to join the mBlk structure to the clBlk/cluster construct.

Alternatively, you can reduce all of the above allocations and joins to a single netTupleGet( ) call (see the netBufLib reference entry).

Now that the data is contained within an mBlk/clBlk/cluster construct, you can use various netBufLib routines to adjust or inspect this data. For example, to read the data in the construct, you can call netMblkToBufCopy( ). In addition, you can use the mBlk chaining feature to prepend or append data to the packet.

NOTE: The various net*Get( ) routines reserve memory from a pre-allocated pool. Internally, they do not use semaphores. Thus, they are safe to call when a call to malloc( ) would be unsafe or impossible.

A.5 Freeing mBlks, clBlks, and Clusters

When you want to return an mBlk/clBlk/cluster chain to its memory pool, call netMblkClChainFree( ). This frees all mBlks in the chain. It also decrements the reference counters in all the clBlks in the chain. If the reference counter for a clBlk drops to zero, that clBlk and its associated cluster are also freed back to the pool. To free a single mBlk/clBlk/cluster back to the memory pool, use netMblkClFree( ).

A.6 Macros for Buffer Manipulation

M_PREPEND(m, plen, how)

This macro prepends plen bytes at the beginning of buffer m. You can set how to M_WAIT or M_DONTWAIT. This corresponds to the canWait parameter in the netMblkGet( ) call. It specifies the desired behavior if there is not enough space in m for plen bytes and a new buffer must be allocated and added to the buffer chain to contain these prepended bytes.

For information on pre-allocating space at the beginning of a buffer, which increases the speed of the M_PREPEND( ) operation, see 10.1.7 Early Link-Level Header Allocation in an NPT Driver, p.187.

M_ALIGN(m, len)

This macro appends an area of len bytes to the buffer m, and aligns this area on a long word boundary. It does not verify that this amount of space is available in the buffer, so if you are in doubt, use M_TRAILINGSPACE( ) to verify this before performing the M_ALIGN( ) operation.

M_LEADINGSPACE(m)

This macro reports the size of the leading space that comes before the data held in the cluster belonging to buffer m. Knowing the size of this leading space is useful before calling M_PREPEND( ). If you find that there is not enough space, you can allocate a new buffer.

M_TRAILINGSPACE(m)

This macro computes the amount of space past the data held in the cluster belonging to mbuf m. This can be used to estimate how large a data block can be added with an M_ALIGN( ) operation on that mbuf.

A.7 The netBufLib Library

This library contains routines that you can use to organize and maintain a memory pool consisting 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 actual data.

These structures and the functions in this library constitute a buffering API that has been designed to meet the needs both of network services and network drivers.

The mBlk structure is the primary vehicle for passing data between a network driver and a service. However, the mBlk structure must first be properly joined with a clBlk structure that was previously joined with a data cluster. The actual vehicle for passing data is not merely an mBlk structure but an mBlk/clBlk/cluster construct.

To include netBufLib in VxWorks, build your image with basic network support by including INCLUDE_NETWORK.

netBufLibInit( )

This function initializes the netBufLib. If INCLUDE_NETWORK is included in the configuration of your VxWorks image, VxWorks automatically calls netBufLibInit( ).

STATUS netBufLibInit (void)

The function returns OK on successful initialization or ERROR otherwise.

netClBlkFree( )

This function frees the clBlk/cluster construct from an mBlk. If there are no other mBlks that refer to the construct, both the clBlk and its associated cluster are freed back into the specified memory pool.

void netClBlkFree 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    CL_BLK_ID    pClBlk     /* pointer to the clBlk to be freed */ 
    )

netClBlkGet( )

This function gets a clBlk from the specified memory pool. Set the canWait parameter either to M_WAIT or M_DONTWAIT. If canWait is set to M_WAIT, and if a clBlk is not initially available, netClBlkGet( ) attempts garbage collection before failing. If canWait is set to M_DONTWAIT and if no clBlk is available, netClBlkGet( ) returns a NULL value immediately.

CL_BLK_ID netClBlkGet 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    int          canWait    /* M_WAIT/M_DONTWAIT */ 
    )

This function returns a clBlk identifier, or NULL if none are available and canWait is set to M_DONTWAIT.

netClBlkJoin( )

This function joins the previously reserved cluster specified by pClBuf to the previously reserved clBlk structure specified by pClBlk. The size parameter indicates the size of the cluster referenced in pClBuf. The arguments pFreeRtn, arg1, arg2, and arg3 set the values of the pCLFreeRtn, clFreeArg1, clFreeArg2, and clFreeArg1 members of the specified 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 function returns a CL_BLK_ID corresponding to the new pClBlk, or NULL if it was unable to perform the join.

netClFree( )

This function returns the specified cluster back to the specified memory pool.

void netClFree 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    UCHAR *      pClBuf     /* pointer to the cluster buffer */ 
    )

netClPoolIdGet( )

This function returns a CL_POOL_ID corresponding to 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 set to FALSE.

CL_POOL_ID netClPoolIdGet 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    int          bufSize,   /* size of the buffer */ 
    BOOL         bestFit    /* TRUE/FALSE */ 
    )

This function returns either a CL_POOL_ID corresponding to a particular cluster pool, or NULL if no such cluster pool could be found.

netClusterGet( )

This function retrieves a cluster from the specified cluster pool pClPool within the specified memory pool pNetPool.

char * netClusterGet 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    CL_POOL_ID   pClPool    /* ptr to the cluster pool */ 
    )

The function returns a character pointer referring to a cluster buffer, or NULL if no buffer is available in the specified pool.

netMblkChainDup( )

This function copies an mBlk chain or a portion of an mBlk chain, and returns a new M_BLK_ID referring to a new mBlk allocated from pNetPool that holds the copy. The copy starts at offset bytes from the beginning of the chain specified by pMblk, and continues for len bytes, or, if len is set to M_COPYALL, for the remainder of the mBlk chain.

M_BLK_ID netMblkChainDup 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the pool         */ 
    M_BLK_ID     pMblk,     /* pointer to source mBlk chai */ 
    int          offset,    /* offset to duplicate from    */ 
    int          len,       /* length to copy              */ 
    int          canWait    /* M_DONTWAIT/M_WAIT           */ 
    )

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 canWait parameter expects either M_WAIT or M_DONTWAIT. If canWait is M_WAIT, this routine will make an attempt at garbage collection before failing if an mBlk is not initially available. If canWait is M_DONTWAIT and no mBlk is immediately available, this routine returns immediately with a NULL value.

This function returns an M_BLK_ID referring to the newly allocated mBlk chain, or NULL if the copy fails. If NULL is returned, errno is set to either of the following:

S_netBufLib_INVALID_ARGUMENT, indicating that one of the parameters is set so that a copy could not take place

S_netBufLib_NO_POOL_MEMORY, indicating that pNetPool does not have enough room for the copied mBlk chain

netMblkClChainFree( )

This function frees a chain of mBlk structures back into its memory pool, and decrements the reference count in the associated clBlk structures. If no other mBlks reference these clBlk structures, they are also freed along with their associated clusters.

void netMblkClChainFree 
    ( 
    M_BLK_ID  pMblk  /* pointer to the mBlk */ 
    )

If pMblk does not refer to a valid M_BLK_ID, this function sets errno to S_netBufLib_MBLK_INVALID.

netMblkClFree( )

This function frees the mBlk specified back into its memory pool, and decrements the reference count in the associated clBlk structure. If no other mBlks reference this clBlk structure, it is also freed along with its associated cluster.

M_BLK_ID netMblkClFree 
    ( 
    M_BLK_ID  pMblk  /* pointer to the mBlk */ 
    )

If the specified mBlk is part of an mBlk chain, this routine returns an M_BLK_ID referring to the next mBlk in the chain, otherwise it returns NULL. If pMblk does not refer to a valid M_BLK_ID, this function sets errno to S_netBufLib_MBLK_INVALID.

netMblkClGet( )

This function retrieves a clBlk/cluster construct of size bufSize from the specified net pool and joins 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 */ 
    )

If canWait is set to M_WAIT, this routine performs garbage collection and makes a second attempt if a clBlk/cluster construct is not initially available. If canWait is set to M_DONTWAIT and no clBlk/cluster construct is available, this routine returns ERROR immediately.

If bestFit is set to TRUE and a cluster of the exact size is unavailable, this routine tries to retrieve a larger cluster instead. If bestFit is set to FALSE and an exactly matching size is unavailable, this routine tries to retrieve either a smaller or larger cluster (depending on what is available). For memory pools containing only one cluster size, bestFit should always be set to FALSE.

This function returns OK if the requested clBlk/cluster was retrieved and joined to the specified mBlk, or ERROR if the attempt fails. If the M_BLK_ID specified does not refer to a valid mBlk, errno is set to S_netBufLib_MBLK_INVALID.

netMblkClJoin( )

This function joins a specified mBlk to a specified clBlk/cluster construct. Internally, this routine sets the M_EXT flag in mBlk.mBlkHdr.mFlags. It also sets the mBlk.mBlkHdr.mData to point to the start of the data in the cluster.

M_BLK_ID netMblkClJoin 
    ( 
    M_BLK_ID   pMblk,  /* pointer to an mBlk */ 
    CL_BLK_ID  pClBlk  /* pointer to a cluster Blk */ 
    )

This function returns an M_BLK_ID corresponding to the modified pMblk, or NULL if either the pMblk or pClBlk arguments are invalid.

netMblkDup( )

This function copies the clBlk/cluster references from the source mBlk into the destination mBlk and increments the reference count in the shared clBlk. This allows the two mBlk structures to share the same clBlk/cluster construct.

M_BLK_ID netMblkDup 
    ( 
    M_BLK_ID  pSrcMblk,  /* pointer to source mBlk */ 
    M_BLK_ID  pDestMblk  /* pointer to the destination mBlk */ 
    )

This function returns a pointer to the destination mBlk, or NULL if the source mBlk is not part of a valid mBlk/clBlk/cluster construct.

netMblkFree( )

This function frees a specified mBlk back into its memory pool.

void netMblkFree 
    ( 
    NET_POOL_ID  pNetPool,  /* pointer to the net pool */ 
    M_BLK_ID     pMblk      /* mBlk to free */ 
    )

netMblkGet( )

This function retrieves an mBlk from the specified net pool. If canWait is set to M_WAIT, this routine performs garbage collection and makes a second attempt if an mBlk is not initially available. If canWait is set to M_DONTWAIT and no mBlk is immediately available, this routine returns immediately with a NULL value. The type parameter indicates the type value to be associated with the retrieved mBlk.

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 returns an M_BLK_ID referring to the newly retrieved mBlk, or NULL if no mBlk is available.

netMblkToBufCopy( )

This function copies data from the mBlk chain specified 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.

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 function returns the length of the data copied, or 0 (zero) if no copy takes place.

netPoolDelete( )

This function frees the specified memory pool.

STATUS netPoolDelete 
    ( 
    NET_POOL_ID  pNetPool  /* pointer to a net pool */ 
    )

This routine returns OK if the pool is freed, or ERROR if it is unable to free the specified pool. If pNetPool does not refer to a valid net pool, errno is set to S_netBufLib_NETPOOL_INVALID.

netPoolInit( )

This function initializes a netBufLib-managed memory pool, organizing several sub-pools within it for mBlk structures, clBlk structures and cluster-size-specific sub-pools. Set pNetPool to an identifier referring to a previously allocated NET_POOL structure.

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 */ 
    )

Set pMclBlkConfig to point to a previously allocated and initialized M_CL_CONFIG structure that specifies the requested subdivision of the memory pool. Within this structure, you must provide the following values:

mBlkNum, a count of mBlk structures

clBlkNum, a count of clBlk structures

memArea, a pointer to memory that can contain the mBlk and clBlk structures

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 can 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.

The pClDescTbl argument should be set to point 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 the following 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

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 by being separated by powers of two. See A.3 Setting Up a Memory Pool, p.254 for further discussion of this restriction. 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 has to be increased to at least 1516 bytes.

The clDescTblNumEnt argument should be set to the number of elements in the pClDescTbl table. This is a count of the number of cluster pools. You can get this value by using the NELEMENTS macro defined in vxWorks.h. For example:

int clDescTblNumEnt = (NELEMENTS(clDescTbl));

The pFuncTbl argument should be set either to NULL or to refer to a function table containing 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( ) is 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);

This function returns OK if the initialization succeeds, or ERROR otherwise, in which case errno is set to the following, depending on the reason for the failure:

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

netPoolShow( )

This function displays the distribution of mBlks and clusters in a given network pool, specified by pNetPool.

void netPoolShow 
    ( 
    NET_POOL_ID  pNetPool 
    )

netShowInit( )

This function initializes the network show routines. These routines are included in VxWorks automatically if network show routines are built into the VxWorks image by including INCLUDE_NET_SHOW.

void netShowInit (void)

netStackDataPoolShow( )

This function displays the distribution of mBlks and clusters in the network data pool. This pool is used only for data transfer through the network stack.

void netStackDataPoolShow (void)

netStackSysPoolShow( )

This function displays the distribution of mBlks and clusters in the network system pool. This pool is used only for system structures such as sockets, routes, interface addresses, protocol control blocks, multicast addresses, and multicast route entries.

void netStackSysPoolShow (void)

netTupleGet( )

This function gets a mBlk/clBlk/cluster construct from the memory pool specified by pNetPool. This construct is used to pass data across the layers of the network stack. The bufSize parameter indicates the number of bytes in the 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                */ 
    )

If canWait is M_WAIT, this routine performs garbage collection and makes a second attempt if an mBlk/clBlk/cluster construct is not initially available. If canWait is M_DONTWAIT and no mBlk/clBlk/cluster construct is immediately available, this routine returns immediately with a NULL value.

The type parameter indicates the type of data in the cluster, for example MT_DATA or MT_HEADER. The acceptable type values are defined in netBufLib.h.

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 exactly matching size is unavailable, this routine gets either a smaller or a larger cluster (depending on what is available). Otherwise, it returns immediately with a NULL value. For memory pools containing only one cluster size, bestFit should always be set to FALSE.

This function returns an M_BLK_ID corresponding to an mBlk/clBlk/cluster construct, or NULL if it is unable to get such a construct from the specified net pool. In case of an error, errno may be set to S_netBufLib_MBLK_INVALID, S_netBufLib_CLSIZE_INVALID or S_netBufLib_NETPOOL_INVALID.