NdisAllocatePacketPool 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.
NdisAllocatePacketPool allocates and initializes a block of storage for a pool of packet descriptors.
Syntax
VOID NdisAllocatePacketPool(
_Out_ PNDIS_STATUS Status,
_Out_ PNDIS_HANDLE PoolHandle,
_In_ UINT NumberOfDescriptors,
_In_ UINT ProtocolReservedLength
);
Parameters
Status [out]
Pointer to a caller-supplied variable in which this function returns the status of the packet pool allocation, which can be one of the following:NDIS_STATUS_SUCCESS
The driver can make calls to NdisAllocatePacket when it needs packet descriptors to make indications up to higher-level drivers or to send packets down to lower-level drivers.NDIS_STATUS_RESOURCES
The attempt to allocate packet pool failed, possibly due to a shortage of memory. This return does not necessarily mean that a subsequent call will fail. However, the caller might attempt to decrease the NumberOfDescriptors and call again immediately.
PoolHandle [out]
Pointer to a caller-supplied variable in which this function returns a handle to the packet pool. This handle is a required parameter to the NdisXxxPacket functions that the driver calls subsequently.NumberOfDescriptors [in]
Specifies the number of packet descriptors the pool should contain.ProtocolReservedLength [in]
Specifies the number of bytes to be allocated for the ProtocolReserved array of each packet descriptor. When allocating a pool for packets to be used in receive indications, a miniport driver should set this parameter to PROTOCOL_RESERVED_SIZE_IN_PACKET. On 32-bit systems, PROTOCOL_RESERVED_SIZE_IN_PACKET' equals 16 bytes. On 64-bit systems, PROTOCOL_RESERVED_SIZE_IN_PACKET 'equals 32 bytes.
Return value
None
Remarks
A successful call to NdisAllocatePacketPool returns a handle to the packet pool, which the caller should save. Usually, the driver next calls NdisAllocatePacket one or more times with this handle to allocate a set of packet descriptors. The NumberOfDescriptors specified in the call to NdisAllocatePacketPool is the effective limit on how many times the driver can call NdisAllocatePacket before it must call NdisFreePacket to return a packet descriptor to the free list for the packet pool.
As packets sent or indicated are returned to the allocating driver, it can reuse each packet descriptor after calling NdisReinitializePacket and setting it up again with a chain of buffer descriptors, or the driver can call NdisFreePacket to return that packet to the free list. Reinitializing and reusing packets allocated from packet pool is far faster than freeing and, then, having to reallocate them again. Before a driver calls NdisReinitializePacket with a packet descriptor, it must save the pointers to buffer descriptors that are chained to the packet descriptor since NdisReinitializePacket sets the head of the buffer chain to NULL.
When the driver no longer needs the packet pool, it calls NdisFreePacketPool to release the packet pool storage.
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisAllocateNetBufferListPool instead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. Use NdisAllocatePacketPoolEx instead. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL. |
See also
NdisDprAllocatePacketNonInterlocked