NdisMAllocateSharedMemoryAsyncEx function


For ARM and ARM64 processors, we strongly recommend that NDIS driver writers use WDF DMA or WDM DMA instead of NDIS Scatter/Gather DMA.

For more information about WDF DMA, see Handling DMA Operations in KMDF Drivers.

For more information about WDM DMA, see the DMA-related child topics of Managing Input/Output for Drivers.

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.

Return Value

NdisMAllocateSharedMemoryAsyncEx can return one of the following:

Return code Description
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.


Note  A miniport driver must have already called NdisMRegisterScatterGatherDma or NdisMRegisterDmaChannel to initialize a scatter/gather DMA channel before calling NdisMAllocateSharedMemoryAsyncEx.
Drivers of bus-master DMA NICs call NdisMAllocateSharedMemoryAsyncEx to dynamically allocate shared memory. Such drivers also allocate shared memory space during initialization. These drivers use the dynamically allocated shared memory for transfer operations when high network traffic places excessive demands on the existing shared memory space.

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.


Minimum supported client Supported in NDIS 6.0 and later.
Target Platform Universal
Header ndis.h (include Ndis.h)
DDI compliance rules Irql_Gather_DMA_Function

See Also