This documentation is archived and is not being maintained.

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

NdisDprAllocatePacketNonInterlocked allocates and initializes a packet descriptor when the caller is running at IRQL = DISPATCH_LEVEL and that caller provides internal synchronization for accessing packet pool.

Syntax


VOID NdisDprAllocatePacketNonInterlocked(
  _Out_ PNDIS_STATUS Status,
  _Out_ PNDIS_PACKET *Packet,
  _In_  NDIS_HANDLE  PoolHandle
);

Parameters

Status [out]

Pointer to a caller-supplied variable in which this function returns the final status of the request, which can be one of the following:

NDIS_STATUS_SUCCESS

The caller can use the packet descriptor returned at Packet.

NDIS_STATUS_RESOURCES

The free list for the packet pool currently has no available entries. The variable at Packet is set to NULL.

Packet [out]

Pointer to a caller-supplied variable in which this function returns a pointer to the allocated packet descriptor.

PoolHandle [in]

Specifies the handle returned by a preceding call to NdisAllocatePacketPool.

Return value

None

Remarks

A caller of NdisDprAllocatePacketNonInterlocked and its reciprocal NdisDprFreePacketNonInterlocked is responsible for synchronizing all accesses to the packet pool that driver allocated with NdisAllocatePacketPool. Otherwise, the driver should let NDIS manage this synchronization on its behalf by calling NdisAllocatePacket or NdisDprAllocatePacket.

NdisDprAllocatePacketNonInterlocked runs slightly faster than NdisAllocatePacket because NDIS need not acquire a spin lock, which NDIS typically uses to synchronize access to packet pools that drivers allocate.

Instead, a caller of NdisDprAllocatePacketNonInterlocked and NdisDprFreePacketNonInterlocked manages the synchronization of its accesses to packet pool internally.

Usually, such a driver protects its packet pool with a driver-allocated spin lock. Before calling NdisDprAllocatePacketNonInterlocked, the driver calls NdisAcquireSpinLock, which raises IRQL to DISPATCH_LEVEL. Only when the driver resumes execution holding its spin lock does it call NdisDprAllocatePacketNonInterlocked. Such a driver releases its spin lock with NdisReleaseSpinLock when NdisDprAllocatePacketNonInterlocked returns control.

In a similar manner, such a driver calls NdisAcquireSpinLock before it releases a packet descriptor back to pool with NdisDprFreePacketNonInterlocked and, then, it calls NdisReleaseSpinLock.

Any packet descriptor allocated with NdisDprAllocatePacketNonInterlocked must be freed with NdisDprFreePacketNonInterlocked except, possibly, when a driver is releasing its allocated resources just before being unloaded. Otherwise, it is a run-time synchronization error that can cause race conditions to release any packet descriptor with NdisDprFreePacket or NdisFreePacket if that packet descriptor was allocated with NdisDprAllocatePacketNonInterlocked.

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

NdisAcquireSpinLock
NdisAllocatePacket
NdisAllocatePacketPool
NdisAllocateSpinLock
NdisDprAllocatePacket
NdisDprFreePacket
NdisDprFreePacketNonInterlocked
NdisFreePacket
NdisReleaseSpinLock

 

 

Send comments about this topic to Microsoft

Show: