Share via

NdisAllocateNetBufferListPool (Compact 2013)

  • Article

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

Header

ndis.h

See Also

Reference

NDIS NET_BUFFER Functions
NdisAllocateNetBufferList
NdisAllocateNetBufferAndNetBufferList
NdisFreeNetBufferList
NdisFreeNetBufferListPool
NET_BUFFER
NET_BUFFER_LIST
NET_BUFFER_LIST_CONTEXT