NdisAllocateNetBufferListPool (Compact 2013)

3/26/2014

Call this function to allocate a pool of NET_BUFFER_LIST structures.

Syntax

NDIS_HANDLE
  NdisAllocateNetBufferListPool(
    IN NDIS_HANDLE  NdisHandle,
    IN PNET_BUFFER_LIST_POOL_PARAMETERS Parameters
    );

Parameters

• NdisHandle
  An NDIS handle that was obtained during caller initialization.

• Parameters
  A pointer to a NET_BUFFER_LIST_POOL_PARAMETERS structure that defines the parameters for the pool. The structure is defined as follows:

  typedef struct _NET_BUFFER_LIST_POOL_PARAMETERS {
    NDIS_OBJECT_HEADER  Header;
    UCHAR  ProtocolId;
    BOOLEAN  fAllocateNetBuffer;
    USHORT  ContextSize;
    ULONG  PoolTag;
    ULONG  DataSize;
  } NET_BUFFER_LIST_POOL_PARAMETERS, *PNET_BUFFER_LIST_POOL_PARAMETERS;
  

  This structure includes the following members:

  • Header
    The NDIS_OBJECT_HEADER structure for the NET_BUFFER_LIST_POOL_PARAMETERS structure. Set the Type member of the structure that Header specifies to NDIS_OBJECT_TYPE_DEFAULT, the Revision member to NET_BUFFER_LIST_POOL_PARAMETERS_REVISION_1, and the Size member to NDIS_SIZEOF_NET_BUFFER_LIST_POOL_PARAMETERS_REVISION_1.

  • ProtocolId
    The type of caller. Miniport, filter, and intermediate drivers set this field to zero (NDIS_PROTOCOL_ID_DEFAULT). Protocol drivers use one of the following values:

    • NDIS_PROTOCOL_ID_DEFAULT
      Specifies a default protocol driver identifier.
    • NDIS_PROTOCOL_ID_TCP_IP
      Specifies the TCP/IP protocol.
    • NDIS_PROTOCOL_ID_IPX
      Specifies the IPX protocol.
    • NDIS_PROTOCOL_ID_NBF
      Specifies the NetBEUI protocol.
  • fAllocateNetBuffer
    If TRUE, this member specifies that NDIS will allocate a pool of NET_BUFFER_LIST structures with each NET_BUFFER_LIST structure initialized with one NET_BUFFER structure. If FALSE, NDIS will not allocate NET_BUFFER structures.
  • ContextSize
    The size, in bytes, of the preallocated NET_BUFFER_LIST_CONTEXT structure data that NDIS should provide for the NET_BUFFER_LIST structures in this pool. The ContextSize must be a multiple of the value that is defined by MEMORY_ALLOCATION_ALIGNMENT.
  • PoolTag
    A kernel pool tag that the caller uses when it allocates NET_BUFFER_LIST structures from this pool. The tag is a string, delimited by single quotation marks, with up to four characters, usually specified in reversed order. The kernel pool tag helps NDIS to identify the owner of the NET_BUFFER_LIST structures that are allocated from this pool.

  • DataSize
    The default data size, in bytes, for data buffers that are associated with this NET_BUFFER_LIST pool, if any. NDIS uses this value to set the size of any data buffers that it allocates for any associated NET_BUFFER structures.

    If fAllocateNetBuffer is FALSE, NDIS will not allocate NET_BUFFER structures, and DataSize should be set to zero.

    If DataSize is not zero, fAllocateNetBuffer must be TRUE, and NDIS allocates the NET_BUFFER structure and a data buffer with the specified size.

    If DataSize is zero and fAllocateNetBuffer is TRUE, NDIS allocates the NET_BUFFER structure but not the data buffer.

Return Value

NdisAllocateNetBufferListPool returns a handle to the NET_BUFFER_LIST structure pool that NDIS allocates. If the allocation was unsuccessful, this handle is NULL. This handle is a required parameter in subsequent calls to NDIS functions that allocate and free NET_BUFFER_LIST structures from this pool.

Remarks

In most cases, a caller that allocates a NET_BUFFER_LIST structure will allocate and queue at least one NET_BUFFER structure on that NET_BUFFER_LIST structure. It is more efficient to preallocate NET_BUFFER structures when you allocate a pool of NET_BUFFER_LIST structures than allocating NET_BUFFER_LIST structures and NET_BUFFER structures separately.

You can call the NdisAllocateNetBufferListPool function by using the fAllocateNetBuffer value set to TRUE when creating a NET_BUFFER_LIST structure pool. In this case, a NET_BUFFER structure is preallocated with each NET_BUFFER_LIST structure that the caller allocates from the pool. You can call the NdisAllocateNetBufferAndNetBufferList function or the NdisAllocateNetBufferList function to allocate NET_BUFFER_LIST structures from such a pool. Call NdisAllocateNetBufferAndNetBufferList only if fAllocateNetBuffer is TRUE and DataSize is zero.

You can also call NdisAllocateNetBufferListPool and set the DataSize member to a nonzero value when creating a NET_BUFFER_LIST structure pool. In this case, a NET_BUFFER structure, MDL, and data is preallocated with each NET_BUFFER_LIST structure that the caller allocates from the pool.

NET_BUFFER structures, MDLs, and data buffers that are allocated with NdisAllocateNetBufferAndNetBufferList or NdisAllocateNetBufferList should not be freed separate from the NET_BUFFER_LIST structure. Such structures are freed with the NET_BUFFER_LIST structure when you call the NdisFreeNetBufferList function.

Call the NdisFreeNetBufferListPool function to free a NET_BUFFER_LIST structure pool.

Requirements

See Also

Reference

NDIS NET_BUFFER Functions
NdisAllocateNetBufferList
NdisAllocateNetBufferAndNetBufferList
NdisFreeNetBufferList
NdisFreeNetBufferListPool
NET_BUFFER
NET_BUFFER_LIST
NET_BUFFER_LIST_CONTEXT