This documentation is archived and is not being maintained.

NdisMAllocateSharedMemoryAsync function

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

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.

Syntax


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

Parameters

MiniportAdapterHandle [in]

Specifies the handle originally input to MiniportInitialize.

Length [in]

Specifies the number of bytes to allocate.

Cached [in]

Specifies TRUE if the memory can be cached.

Context [in]

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:

Return codeDescription
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.

 

Remarks

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.

Requirements

Target platform

Universal

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMAllocateSharedMemoryAsyncExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)

Library

Ndis.lib

IRQL

<= DISPATCH_LEVEL

See also

MiniportAllocateComplete
MiniportHalt
MiniportInitialize
NdisAllocateBuffer
NdisMAllocateSharedMemory
NdisMFreeSharedMemory

 

 

Send comments about this topic to Microsoft

Show: