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.
| Header file: | Ndis.h |
| Windows CE versions: | 2.0 and later |
NDIS_STATUS NdisAllocateMemory( OUT PVOID *VirtualAddress,
IN UINT Length, IN UINT MemoryFlags,
IN NDIS_PHYSICAL_ADDRESS HighestAcceptableAddress );
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.
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.
NdisFreeMemory, NdisMSetAttributes, NdisMSetAttributesEx