NdisMAllocateSharedMemoryAsync

NDIS_STATUS
NdisMAllocateSharedMemoryAsync(
IN NDIS_HANDLE MiniportAdapterHandle,
IN ULONG Length,
IN BOOLEAN Cached,
IN PVOID Context
);

NdisMAllocateSharedMemoryAsync allocates additional memory shared between a miniport and its busmaster DMA NIC, usually when the miniport is running low on available NIC receive buffers.

Parameters

MiniportAdapterHandle: Specifies the handle originally input to MiniportInitialize.
Length: Specifies the number of bytes to allocate.
Cached: Specifies TRUE if the memory can be cached.
Context: Points to driver-detemined context to be passed to the MiniportAllocateComplete function when it is called.

Return Value

NdisMAllocateSharedMemoryAsync can return one of the following:

NDIS_STATUS_PENDING: The caller’s MiniportAllocateComplete function will be called with mapped virtual and device-accessible logical base addresses for the shared memory range, its Length and the Context pointer when the requested memory is allocated. Otherwise, MiniportAllocateComplete will be called with NULL pointers if the attempt to allocate shared memory fails.
NDIS_STATUS_FAILURE: The requested memory could not be allocated at this time. If NdisMAllocateSharedMemoryAsync returns this status, a subsequent call with the same parameters might succeed, depending on whether system resources have become available.

Comments

Drivers of busmaster DMA NICs call NdisMAllocateSharedMemoryAsync to dynamically allocate shared memory for transfer operations when high network traffic places excessive demands on the shared memory space that the driver allocated during initialization.

Such a NIC 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 calls NdisMAllocateSharedMemoryAsync to allocate more buffer space in shared memory. When the number of available buffers climbs to a driver-determined high, it calls NdisMFreeSharedMemory one or more times to release its preceding dynamic allocation(s).

Usually, such a driver retains the block of shared memory that its MiniportInitialize function allocated with NdisMAllocateSharedMemory until the NIC is removed, when its MiniportHalt function is called. This allocation is sufficient to handle an average demand for transfers through the NIC.

Any miniport that calls NdisMAllocateSharedMemoryAsync or NdisMAllocateSharedMemory must release all outstanding allocations with one or more calls to NdisMFreeSharedMemory when its NIC is removed.

Callers of NdisMAllocateSharedMemoryAsync run at IRQL <= DISPATCH_LEVEL.