NdisAllocateMemory

This function allocates resident (nonpaged) system-space memory. The memory can be allocated within a specified address limit and, if necessary, can be uncached as well.

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

Parameters

• VirtualAddress
  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
  Specifies the size, in bytes, to be allocated.

• MemoryFlags
  Specifies 0 or a bitmask designating the type(s) of memory to allocate. One of the following values:

  Value	Description
  0	Allocate nonpaged system-space memory.
  NDIS_MEMORY_CONTIGUOUS	Not supported.
  NDIS_MEMORY_NONCACHED	Allocate noncached memory.

• HighestAcceptableAddress
  Specifies –1.

Return Values

NDIS_STATUS_SUCCESS indicates that the caller can use the allocated memory range starting at the value returned at the VirtualAddress parameter. NDIS_STATUS_FAILURE indicates that the attempt to allocate the requested memory failed. This does not necessarily mean that a subsequent call will fail.

Remarks

If the NDIS_MEMORY_NONCACHED flag is specified, Windows CE NDIS uses the VirtualAlloc function to allocate the memory; otherwise, it uses the LocalAlloc function.

Any NDIS driver might call this function with the MemoryFlags set to 0. for example, NDIS drivers that export a set of NDIS upper-edge (miniport) functions can call this function to allocate a context area in which the driver maintains per-NIC or per-virtual-NIC run-time state information and pass the pointer returned at VirtualAddress to the NdisMSetAttributes or the NdisMSetAttributesEx function. NDIS drivers that export a set of NDIS lower-edge (protocol) functions can also call this function whenever such a driver needs to allocate buffer space.

Only NIC miniports set the MemoryFlags with either or both of the flags when they make initialization-time calls to this function. 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 this function, the virtual memory allocation maps to a single physically contiguous region. If a miniport specifies noncached memory, the allocated virtual range is not cached. An NIC driver can access noncached memory without flushing cache buffers during DMA operations.

Whatever the value of the input MemoryFlags, a successful caller to this function 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.

An NIC driver should never request more noncached memory than it needs.

If an initialization-time call fails, an NIC driver can attempt to allocate one or more smaller blocks of noncached memory, rather than failing to initialize if it cannot allocate a large block.

A driver that calls this function can run at IRQL <=DISPATCH_LEVEL to allocate memory from a nonpaged pool. NIC drivers that allocate noncached memory must be running at IRQL PASSIVE_LEVEL during initialization.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Ndis.h

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

NdisFreeMemory, NdisMSetAttributes, NdisMSetAttributesEx

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.