NdisMAllocateSharedMemoryAsyncEx function

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

MiniportDmaHandle [in]

A handle to a context area that NDIS uses to manage a DMA resource. The caller obtained this handle by calling the NdisMRegisterScatterGatherDma function.

Length [in]

The number of bytes to allocate.

Cached [in]

This parameter is ignored (cached memory is always used on x86 and x64 systems).

Context [in]

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 codeDescription
NDIS_STATUS_PENDING

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.

NDIS_STATUS_FAILURE

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

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.

Requirements

Target platform

Universal

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

DDI compliance rules

Irql_Gather_DMA_Function

See also

MiniportSharedMemoryAllocateComplete
MiniportHaltEx
MiniportInitializeEx
NdisMAllocateSharedMemory
NdisMFreeSharedMemory
NdisMRegisterDmaChannel
NdisMRegisterScatterGatherDma

 

 

Send comments about this topic to Microsoft

Show: