Miniport drivers call the NdisMAllocateSharedMemoryAsyncEx function to allocate additional memory shared between the driver and its bus-master DMA NIC, usually when the miniport driver is running low on available NIC receive buffers.
NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx( NDIS_HANDLE MiniportDmaHandle, ULONG Length, BOOLEAN Cached, PVOID Context );
A handle to a context area that NDIS uses to manage a DMA resource. The caller obtained this handle by calling the NdisMRegisterScatterGatherDma function.
The number of bytes to allocate.
This parameter is ignored (cached memory is always used on x86 and x64 systems).
A pointer to driver-determined context to be passed to the MiniportSharedMemoryAllocateComplete function when it is called.
NdisMAllocateSharedMemoryAsyncEx can return one of the following:
||NDIS will call the MiniportSharedMemoryAllocateComplete function and provide information that describes the allocated shared memory. If the attempt to allocate shared memory fails, NDIS calls MiniportSharedMemoryAllocateComplete and passes NULL pointers.|
||The requested memory could not be allocated at this time. If NdisMAllocateSharedMemoryAsyncEx returns this status, a subsequent call with the same parameters might succeed, depending on whether system resources have become available.|
Such a miniport driver usually maintains one or more state variables to track the number of shared memory buffers available for incoming transfers. When the number of available buffers reaches a driver-determined low, the miniport driver calls NdisMAllocateSharedMemoryAsyncEx to allocate more buffer space in shared memory. When the number of available buffers climbs to a driver-determined high, the miniport driver calls NdisMFreeSharedMemory one or more times to release its preceding dynamic allocations.
Usually, such a miniport driver retains the block of shared memory that its MiniportInitializeEx function allocated with NdisMAllocateSharedMemory until a NIC is removed. When the NIC is removed, NDIS calls the miniport driver's MiniportHaltEx function. This allocation is sufficient to handle an average demand for transfers through the NIC.
A miniport driver should set a limit on how much shared memory it can allocate. This limit is driver-specific and should be high enough so that the driver does not run out of buffers. Do not et a limit that is excessively high, as this could result in a wasteful consumption of shared memory that could reduce system performance.
Any miniport driver that calls NdisMAllocateSharedMemoryAsyncEx or NdisMAllocateSharedMemory must release all outstanding allocations with one or more calls to NdisMFreeSharedMemory when its NIC is removed.
|Windows version||Supported in NDIS 6.0 and later.|
|Header||ndis.h (include Ndis.h)|
|DDI compliance rules||Irql_Gather_DMA_Function|