Expand Minimize

MmAllocatePagesForMdlEx routine

The MmAllocatePagesForMdlEx routine allocates nonpaged, physical memory pages to an MDL.

Syntax


PMDL MmAllocatePagesForMdlEx(
  _In_  PHYSICAL_ADDRESS LowAddress,
  _In_  PHYSICAL_ADDRESS HighAddress,
  _In_  PHYSICAL_ADDRESS SkipBytes,
  _In_  SIZE_T TotalBytes,
  _In_  MEMORY_CACHING_TYPE CacheType,
  _In_  ULONG Flags
);

Parameters

LowAddress [in]

Specifies the physical address of the start of the first address range from which the allocated pages can come. If MmAllocatePagesForMdlEx cannot allocate the requested number of bytes in the first address range, it iterates through additional address ranges to get more pages. At each iteration, MmAllocatePagesForMdlEx adds the value of SkipBytes to the previous start address to obtain the start of the next address range.

HighAddress [in]

Specifies the physical address of the end of the first address range that the allocated pages can come from.

SkipBytes [in]

Specifies the number of bytes to skip from the start of the previous address range that the allocated pages can come from. SkipBytes must be an integer multiple of the virtual memory page size, in bytes.

TotalBytes [in]

Specifies the total number of bytes to allocate for the MDL.

CacheType [in]

Specifies a MEMORY_CACHING_TYPE value, which indicates the type of caching that is allowed for the requested memory.

Flags [in]

Specifies flags for this operation. Set this parameter to zero or to the bitwise OR of one or more of the following MM_ALLOCATE_XXX flag bits:

  • MM_DONT_ZERO_ALLOCATION

  • MM_ALLOCATE_FROM_LOCAL_NODE_ONLY

  • MM_ALLOCATE_FULLY_REQUIRED

  • MM_ALLOCATE_NO_WAIT

  • MM_ALLOCATE_PREFER_CONTIGUOUS

  • MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS

The last four items in the preceding list are supported only in Windows 7 and later versions of Windows.

Return value

MmAllocatePagesForMdlEx returns one of the following:

Return codeDescription
MDL pointer

A non-NULL return value is a pointer to an MDL that describes a set of physical pages in the specified address range. If the requested number of bytes is not available, the MDL describes as much physical memory as is available.

NULL

Indicates that no physical memory pages are available in the specified address ranges, or that there is not enough memory pool for the MDL itself.

 

Remarks

By default, the physical memory pages that MmAllocatePagesForMdlEx returns are not contiguous pages. Starting with Windows 7, callers can override the default behavior of this routine by setting the MM_ALLOCATE_PREFER_CONTIGUOUS or MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS flag bit in the Flags parameter.

MmAllocatePagesForMdlEx is designed for kernel-mode drivers that do not need corresponding virtual addresses (that is, they need physical pages and do not need them to be physically contiguous), and for kernel-mode drivers that can achieve substantial performance gains if physical memory for a device is allocated in a specific physical address range (for example, an AGP graphics card).

Depending on how much physical memory is currently available in the requested ranges, MmAllocatePagesForMdlEx might return an MDL that describes less memory than was requested. The routine also might return NULL if no memory was allocated. The caller should check the amount of memory that is actually allocated to the MDL.

The caller must use MmFreePagesFromMdl to release the memory pages that are described by an MDL that was created by MmAllocatePagesForMdlEx. After calling MmFreePagesFromMdl, the caller must also call ExFreePool to release the memory that is allocated for the MDL structure.

By default, MmAllocatePagesForMdlEx fills the pages that it allocates with zeros. The caller can specify the MM_DONT_ZERO_ALLOCATION flag to override this default and to possibly improve performance.

Note   Memory that MmAllocatePagesForMdlEx allocates is uninitialized if you specify the MM_DONT_ZERO_ALLOCATION flag. A kernel-mode driver must first zero this memory if the driver is going to make the memory visible to user-mode software (to avoid leaking potentially privileged contents). For more information about this flag, see MM_ALLOCATE_XXX.

The maximum amount of memory that MmAllocatePagesForMdlEx can allocate in a single call is (4 gigabytes - PAGE_SIZE). The routine can satisfy an allocation request for this amount only if enough pages are available.

MmAllocatePagesForMdlEx runs at IRQL <= APC_LEVEL. In Windows Server 2008 and later versions of Windows, callers of MmAllocatePagesForMdlEx are allowed to be at DISPATCH_LEVEL. However, you can improve driver performance by calling at APC_LEVEL or below.

Requirements

Version

Available in Windows Server 2003 with Service Pack 1 (SP1) and later versions of Windows. You should use this routine instead of MmAllocatePagesForMdl on these operating systems.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

See Remarks section.

DDI compliance rules

IrqlMmApcLte

See also

ExFreePool
MEMORY_CACHING_TYPE
MmAllocatePagesForMdl
MM_ALLOCATE_XXX
MmFreePagesFromMdl
MmMapLockedPages

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft