Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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
Value | Description |
---|---|
0 | Allocate nonpaged system-space memory. |
NDIS_MEMORY_CONTIGUOUS | Not supported. |
NDIS_MEMORY_NONCACHED | Allocate noncached memory. |
Return Values
NDIS_STATUS_SUCCESS indicates that the caller can use the allocated memory range starting at the value returned at the VirtualAddressparameter. 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 VirtualAllocfunction to allocate the memory; otherwise, it uses the LocalAllocfunction.
Any NDIS driver might call this function with the MemoryFlagsset 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-network adapter or per-virtual-network adapter run-time state information and pass the pointer returned at VirtualAddressto the NdisMSetAttributesor the NdisMSetAttributesExfunction. 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 network adapter miniports set the MemoryFlagswith 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 network adapters.
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 network adapter 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 network adapter driver should never request more noncached memory than it needs.
If an initialization-time call fails, a network adapter 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
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Ndis.h | Ndislib.lib |
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
LocalAlloc, NdisFreeMemory, NdisMSetAttributes, NdisMSetAttributesEx, VirtualAlloc