NdisAllocateMemory (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

NDIS_STATUS NdisAllocateMemory(
  PVOID* VirtualAddress,
  UINT Length,
  UINT MemoryFlags,
  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 0 or a bitmask designating the types of memory to allocate. The following table shows valid Memory Flag values.

  Value	Description
  0	Allocate system-space memory.
  NDIS_MEMORY_CONTIGUOUS	Not supported. Using this flag will cause NdisAllocateMemory to return NDIS_STATUS_FAILURE. This flag is ignored by NdisAllocateMemory in Windows CE 3.0 and earlier.
  NDIS_MEMORY_NONCACHED	Allocate noncached memory.

• HighestAcceptableAddress
  [in] Specifies –1.

Return Value

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 Embedded 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.

Requirements

See Also

Reference

NDIS Library Functions
NdisFreeMemory
NdisMSetAttributes
NdisMSetAttributesEx

Other Resources

LocalAlloc
VirtualAlloc