NdisMAllocateSharedMemoryAsyncEx function (ndis.h)
Caution
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.
Syntax
NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
[in] NDIS_HANDLE MiniportDmaHandle,
[in] ULONG Length,
[in] BOOLEAN Cached,
[in] PVOID Context
);
Parameters
[in] MiniportDmaHandle
A handle to a context area that NDIS uses to manage a DMA resource. The caller obtained this handle by calling the NdisMRegisterScatterGatherDma function.
[in] Length
The number of bytes to allocate.
[in] Cached
This parameter is ignored (cached memory is always used on x86 and x64 systems).
[in] Context
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. |
Remarks
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported in NDIS 6.0 and later. |
| Target Platform | Universal |
| Header | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |
| DDI compliance rules | Irql_Gather_DMA_Function(ndis) |