NdisMAllocateSharedMemoryAsync

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

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

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

Pointer to driver-determined 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.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

Drivers of bus-master 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 driver 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.

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 set 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 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.

See Also

MiniportAllocateComplete, MiniportHalt, MiniportInitialize, NdisAllocateBuffer, NdisMAllocateSharedMemory, NdisMFreeSharedMemory