Share via


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:

    Value Meaning

    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 code Description
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

Target platform

Universal

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)

Library

Ndis.lib

IRQL

See Remarks section

See also

MiniportInitialize

NdisAllocateMemoryWithTag

NdisFreeMemory

NdisMAllocateSharedMemory

NdisMSetAttributes

NdisMSetAttributesEx

 

 

Send comments about this topic to Microsoft