MiniportAllocateComplete

VOID
MiniportAllocateComplete(
IN NDIS_HANDLE MiniportAdapterContext,
IN PVOID VirtualAddress,
IN PNDIS_PHYSICAL_ADDRESS PhysicalAddress,
IN ULONG Length,
IN PVOID Context
);

MiniportAllocateComplete is an optional function, supplied by drivers of busmaster DMA NICs that call NdisMAllocateSharedMemoryAsync.

Parameters

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

Comments

Drivers of busmaster 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 shareable between the driver, which uses virtual addresses, and its busmaster 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.

If the call to NdisMAllocateSharedMemoryAsync succeeds, 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 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 fails, 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 set NDIS_STATUS_RESOURCES, so protocol driver(s) release the miniport-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’s existing shared memory area is replenished, the driver can reset its state variable and resume indicating packet arrays with NDIS_STATUS_SUCCESS.

By default, MiniportAllocateComplete runs at IRQL DISPATCH_LEVEL.