W_ALLOCATE_COMPLETE_HANDLER callback function

Article
06/19/2017

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.

The MiniportAllocateComplete function is an optional function, supplied by drivers of bus-master DMA NICs that call NdisMAllocateSharedMemoryAsync.

Syntax

W_ALLOCATE_COMPLETE_HANDLER MiniportAllocateComplete;

VOID MiniportAllocateComplete(
  _In_ NDIS_HANDLE            MiniportAdapterContext,
  _In_ PVOID                  VirtualAddress,
  _In_ PNDIS_PHYSICAL_ADDRESS PhysicalAddress,
  _In_ ULONG                  Length,
  _In_ PVOID                  Context
)
{ ... }

Parameters

MiniportAdapterContext [in]
Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.
VirtualAddress [in]
Specifies the base virtual address of the shared memory allocated by a preceding call to NdisMAllocateSharedMemoryAsync or NULL if the allocation attempt failed.
PhysicalAddress [in]
Specifies the base physical address, suitable for use by the NIC, mapped to VirtualAddress.
Length [in]
Specifies the number of bytes allocated by the preceding call to NdisMAllocateSharedMemoryAsync.
Context [in]
Pointer to a driver-determined context passed in the preceding call to NdisMAllocateSharedMemoryAsync.

Return value

None

Remarks

Drivers of bus-master DMA NICs are most likely to achieve significant performance gains by supporting multipacket receive indications. Such a driver supplies a MiniportAllocateComplete function so it can call NdisMAllocateSharedMemoryAsync when it is running low on shared memory for receive buffers due to high network traffic.

NdisMAllocateSharedMemoryAsync allocates memory that is sharable between the driver, which uses virtual addresses, and its bus-master DMA NIC, which uses the corresponding physical addresses. NdisMAllocateSharedMemoryAsync calls MiniportAllocateComplete whether its allocation attempt succeeds or fails.

A call to NdisMAllocateSharedMemoryAsync can occur at IRQL <= DISPATCH_LEVEL, possibly from the driver's MiniportHandleInterrupt or MiniportTimer function as it indicates incoming receives to bound protocols with NdisMIndicateReceivePacket. Such a driver also must have a MiniportReturnPacket function.

MiniportAllocateComplete should test the value of VirtualAddress to determine whether the call to NdisMAllocateSharedMemoryAsync succeeded. If the call succeeded, VirtualAddress is non-NULL. If the call failed, VirtualAddress is NULL.

If the call to NdisMAllocateSharedMemoryAsync succeeded, MiniportAllocateComplete can set up additional receive buffers in the newly allocated shared memory block. If this call allocated cached memory, MiniportAllocateComplete should align each new receive buffer on a cache-line boundary. MiniportAllocateComplete must allocate the buffer descriptors that map these new receive buffers from buffer pool. Such a miniport driver can continue making multipacket receive indications, which NDIS forwards to the ProtocolReceivePacket function(s) of bound protocol(s) that export this function or as individual packets to the ProtocolReceive functions of other bound protocols.

If the call to NdisMAllocateSharedMemoryAsync failed, MiniportAllocateComplete should set a state variable in the MiniportAdapterContext area to indicate that the driver must set NDIS_STATUS_RESOURCES in the Status member of the out-of-band block for the packets it subsequently indicates. This status causes NDIS to call the ProtocolReceive function(s) of bound protocol(s) with each packet for which the miniport driver set NDIS_STATUS_RESOURCES, so protocol driver(s) release the miniport driver-allocated packets with chained receive buffers individually as they are indicated, rather than holding on to packets until the protocol(s) have processed all indicated data. When the receive buffer space in the miniport driver's existing shared memory area is replenished, the driver can reset its state variable and resume indicating packet arrays with NDIS_STATUS_SUCCESS.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL