This documentation is archived and is not being maintained.

NdisAllocateBufferPool function

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisAllocateBufferPool returns a handle with which the caller can allocate buffer descriptors by calling NdisAllocateBuffer.

Syntax


VOID NdisAllocateBufferPool(
  _Out_ PNDIS_STATUS Status,
  _Out_ PNDIS_HANDLE PoolHandle,
  _In_  UINT         NumberOfDescriptors
);

Parameters

Status [out]

Pointer to a caller-supplied variable in which this function returns the final status of the buffer pool allocation.

PoolHandle [out]

Pointer to a caller-supplied variable in which this function returns a handle to the buffer pool. This handle is a required parameter to the NdisXxxBuffer functions that the driver calls subsequently. Do not test the PoolHandle value to verify the success of an NdisAllocateBufferPool call. NULL is a valid value for PoolHandle on some Windows versions.

NumberOfDescriptors [in]

Specifies the number of buffer descriptors the caller expects to allocate from the buffer pool without releasing any allocated buffer descriptors back to the pool.

Return value

None

Remarks

After NdisAllocateBufferPool returns, the driver calls NdisAllocateBuffer one or more times to allocate the buffer descriptors that it requires. A driver should call NdisAllocateBufferPool during initialization.

The NumberOfDescriptors specified by a NIC driver usually depends on the features of the NIC. For example, the driver of a bus-master DMA NIC with ring buffers would specify at least a large enough NumberOfDescriptors to map the full ring.

The NumberOfDescriptors specified in the call to NdisAllocateBufferPool is the effective limit on how many times the driver can call NdisAllocateBuffer before it must call NdisFreeBuffer to return a buffer descriptor to the free list for the buffer pool.

When a driver no longer needs the buffer pool it allocated, it calls NdisFreeBufferPool to release the buffer pool handle.

All lower-level NDIS drivers must allocate all buffer descriptors that they chain to packets from buffer pool. Only highest-level protocol drivers can be given OS-dependent descriptors mapping virtual memory ranges, and, if these memory descriptors are equivalent to NDIS buffer descriptors, a highest-level protocol can pass such descriptors as parameters to NdisXxx functions.

Requirements

Target platform

Universal

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)

Library

Ndis.lib

IRQL

<= DISPATCH_LEVEL.

See also

NdisAdjustBufferLength
NdisAllocateBuffer
NdisChainBufferAtBack
NdisChainBufferAtFront
NdisCopyBuffer
NdisCreateLookaheadBufferFromSharedMemory
NdisFreeBuffer
NdisFreeBufferPool
NdisQueryBuffer
NdisQueryBufferSafe
NdisReleaseSpinLock

 

 

Send comments about this topic to Microsoft

Show: