NdisAllocateMemory 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.
NdisAllocateMemory allocates resident (nonpaged) system-space memory, optionally within a specified address limit, as a physically contiguous allocation, and/or as a noncached allocation.
Syntax
NDIS_STATUS NdisAllocateMemory(
_Out_ PVOID *VirtualAddress,
_In_ UINT Length,
_In_ UINT MemoryFlags,
_In_ NDIS_PHYSICAL_ADDRESS HighestAcceptableAddress
);
Parameters
VirtualAddress [out]
Pointer to a caller-supplied variable in which this function returns the base virtual address of the allocated memory or NULL if memory of the specified type is unavailable.Length [in]
Specifies the size in bytes to be allocated.MemoryFlags [in]
Specifies zero or a bitmask designating the type(s) of memory to allocate, as follows:Value Meaning zero
Allocate nonpaged system-space memory.
Note: A driver should call NdisAllocateMemoryWithTag to allocate nonpaged system-space memory.
NDIS_MEMORY_CONTIGUOUS
Allocate physically contiguous memory.
NDIS_MEMORY_NONCACHED
Allocate noncached memory.
Only NIC drivers specify the allocation of either contiguous or noncached memory during driver initialization.
HighestAcceptableAddress [in]
Specifies -1.
Return value
NdisAllocateMemory can return either of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | The caller can use the allocated memory range starting at the value returned at VirtualAddress. |
| NDIS_STATUS_FAILURE | An attempt to allocate the requested memory failed. This return does not necessarily mean that a subsequent call will fail. |
Remarks
Any NDIS driver might call NdisAllocateMemory with the MemoryFlags set to zero. For example, NDIS drivers that export a set of NDIS upper-edge (MiniportXxx) functions can call NdisAllocateMemory to allocate a context area in which the driver will maintain per-NIC (or per-virtual-NIC) run-time state information and pass the pointer returned at VirtualAddress to NdisMSetAttributes(Ex). NDIS drivers that export a set of NDIS lower-edge (ProtocolXxx) functions also can call NdisAllocateMemory whenever such a driver needs to allocate buffer space.
Only miniport drivers can set the MemoryFlags with either or both of the NDIS_MEMORY_XXX when they make initialization-time calls to NdisAllocateMemory. During initialization, miniport drivers allocate these types of memory to be shared with their NICs.
If such a miniport driver specifies physically contiguous memory in a call to NdisAllocateMemory, the virtual memory allocation maps to a single physically contiguous region. If a miniport driver specifies noncached memory, the allocated virtual range is not cached. A NIC driver can access noncached memory without flushing cache buffers during DMA operations.
Whatever the value of the input MemoryFlags, a successful caller of NdisAllocateMemory uses a range of virtual addresses to access the allocated memory. Depending on the size of the allocation and on the type of memory requested, one or more physical memory ranges (pages) back this single virtual range.
While the NDIS_MEMORY_XXX can be ORed in MemoryFlags to request a contiguous and noncached allocation by a NIC driver, both contiguous and noncached memory are very limited system resources. A NIC driver should never request more contiguous memory and/or more noncached memory than it needs. Attempts to allocate either of these types of memory except during driver initialization are a programming error. Such an attempt is unlikely to be successful because system-space memory becomes fragmented due to allocations by other kernel-mode components, including other drivers, and due to run-time paging.
If such an initialization-time call fails, a NIC driver can attempt to allocate one or more smaller blocks of contiguous and/or noncached memory, rather than failing to initialize if it cannot allocate a large block.
Callers of NdisAllocateMemory can run at IRQL <= DISPATCH_LEVEL to allocate memory from nonpaged pool. NIC drivers that allocate contiguous and/or noncached memory must be running at IRQL = PASSIVE_LEVEL during initialization.
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisAllocateMemoryWithTagPriority instead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
See Remarks section |
See also