Expandir Minimizar

NdisAllocateMemory function

Note   NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

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

Syntax


NDIS_STATUS NdisAllocateMemory(
  _Out_  PVOID *VirtualAddress,
  _In_   UINT Length,
  _In_   UINT MemoryFlags,
  _In_   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 zero or a bitmask designating the type(s) of memory to allocate, as follows:

ValueMeaning

zero

Allocate nonpaged system-space memory.

Note: A driver should call NdisAllocateMemoryWithTag to 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 either contiguous or noncached memory during driver initialization.

HighestAcceptableAddress [in]

Specifies -1.

Return value

NdisAllocateMemory can return either of the following:

Return codeDescription
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.

 

Remarks

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

Requirements

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisAllocateMemoryWithTagPriority instead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)

IRQL

See Remarks section

See also

MiniportInitialize
NdisAllocateMemoryWithTag
NdisFreeMemory
NdisMAllocateSharedMemory
NdisMSetAttributes
NdisMSetAttributesEx

 

 

Send comments about this topic to Microsoft

Mostrar:
© 2014 Microsoft