NdisAllocateMemory

NdisAllocateMemory

NDIS_STATUS
NdisAllocateMemory(
OUT PVOID *VirtualAddress,
IN UINT Length,
IN UINT MemoryFlags,
IN NDIS_PHYSICAL_ADDRESS HighestAcceptableAddress
);

NdisAllocateMemory allocates resident (nonpaged) system-space memory, optionally within a specified address limit, as a physically contiguous allocation, and/or as a noncached allocation.

Parameters

VirtualAddress

Points 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

Specifies the size in bytes to be allocated.

MemoryFlags

Specifies zero or a bitmask designating the type(s) of memory to allocate, as follows:

Value	Meaning
zero	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 contiguous and/or noncached memory during driver initialization. These two flags can be ORed into MemoryFlags before NdisAllocateMemory is called.

HighestAcceptableAddress

Specifies -1.

Return Value

NdisAllocateMemory can return either of the following:

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.

Comments

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) runtime 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 NIC miniports 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 specifies physically contiguous memory in a call to NdisAllocateMemory, the virtual memory allocation maps to a single physically contiguous region. If a miniport 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 runtime 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.