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 code | Description |
|---|---|
| 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