Функция MmAllocateNodePagesForMdlEx (wdm.h)

Статья
10/24/2023

Подпрограмма MmAllocateNodePagesForMdlEx выделяет непогашенную физическую память из идеального узла и выделяет структуру MDL для описания этой памяти.

Синтаксис

PMDL MmAllocateNodePagesForMdlEx(
  [in] PHYSICAL_ADDRESS    LowAddress,
  [in] PHYSICAL_ADDRESS    HighAddress,
  [in] PHYSICAL_ADDRESS    SkipBytes,
  [in] SIZE_T              TotalBytes,
  [in] MEMORY_CACHING_TYPE CacheType,
  [in] ULONG               IdealNode,
  [in] ULONG               Flags
);

Параметры

[in] LowAddress

Физический адрес начала первого диапазона адресов, из которого могут поступать выделенные страницы. Если MmAllocateNodePagesForMdlEx не может выделить запрошенное количество байтов в первом диапазоне адресов, подпрограмма выполняет итерацию по дополнительным диапазонам адресов, чтобы получить больше страниц. При каждой итерации MmAllocateNodePagesForMdlEx добавляет значение SkipBytes к предыдущему начального адреса, чтобы вычислить начало следующего диапазона адресов.

[in] HighAddress

Физический адрес конца первого диапазона адресов, из который могут поступать выделенные страницы.

[in] SkipBytes

Число байтов, которое следует пропустить с начала предыдущего диапазона адресов, из которых могут поступать выделенные страницы. SkipBytes должен быть целым числом, кратным размеру страницы виртуальной памяти, в байтах.

[in] TotalBytes

Общее количество байтов, выделяемых для MDL.

[in] CacheType

Значение MEMORY_CACHING_TYPE , указывающее тип кэширования, разрешенного для запрошенной памяти.

[in] IdealNode

Идеальный номер узла. Если многопроцессорная система содержит N узлов, допустимые номера узлов находятся в диапазоне от 0 до N-1. Драйвер может вызвать подпрограмму KeQueryHighestNodeNumber , чтобы получить наибольшее число узлов. Однопроцессорная или нечислочная многопроцессорная система имеет только один узел , узел 0, из которого выделяется память. Для многопроцессорной системы NUMA выделение производится из идеального узла, если это возможно. Если в идеальном узле недостаточно памяти для выполнения запроса на выделение, а вызывающий объект не устанавливает флаг MM_ALLOCATE_FROM_LOCAL_NODE_ONLY, MmAllocateNodePagesForMdlEx попытается выделить память от других узлов.

[in] Flags

Флаги для этой операции. Присвойте этому параметру значение ноль или побитовое ИЛИ одного или нескольких следующих битов флага:

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
MM_ALLOCATE_AND_HOT_REMOVE

Дополнительные сведения об этих флагах см. в разделе MM_ALLOCATE_XXX.

Возвращаемое значение

MmAllocateNodePagesForMdlEx возвращает указатель на структуру MDL в случае успешного выполнения. В противном случае, если подпрограмме не удается выделить память, она возвращает значение NULL.

Возвращаемое значение NULL указывает, что в указанных диапазонах адресов отсутствуют страницы физической памяти или что пула памяти недостаточно для выделения структуры MDL.

Если подпрограмма успешно выделяет некоторые, но не все, запрошенную память, MDL описывает столько физической памяти, сколько подпрограмме удалось выделить.

В многопроцессорной системе с неоднородным доступом к памяти (NUMA) вызывающий объект может указать идеальный узел для выделения памяти. Узел — это коллекция процессоров, которые совместно используют быстрый доступ к области памяти. В многопроцессорной или однопроцессорной системе, отличной от NUMA, MmAllocateNodePagesForMdlEx рассматривает всю память как принадлежащая одному узлу и выделяет память из этого узла.

По умолчанию страницы физической памяти, возвращаемые MmAllocateNodePagesForMdlEx , не являются смежными страницами. Вызывающие стороны могут переопределить поведение этой подпрограммы по умолчанию, задав MM_ALLOCATE_PREFER_CONTIGUOUS или MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS бит флага в параметре Flags .

MmAllocateNodePagesForMdlEx не сопоставляет выделенную физическую память с виртуальной памятью. При необходимости вызывающий объект может вызвать подпрограмму, например MmMapLockedPagesSpecifyCache , чтобы сопоставить страницы физической памяти, описанные в MDL.

MmAllocateNodePagesForMdlEx предназначен для драйверов в режиме ядра, которым не требуются соответствующие виртуальные адреса (т. е. им нужны физические страницы и они не должны быть физически смежными), а также для драйверов режима ядра, которые могут значительно повысить производительность, если физическая память устройства выделяется в определенном диапазоне физических адресов (например, карта графики AGP).

В зависимости от того, сколько физической памяти в настоящее время доступно в запрошенных диапазонах, MmAllocateNodePagesForMdlEx может вернуть MDL, описывающий меньше памяти, чем было запрошено. Подпрограмма также может возвращать значение NULL , если память не выделена. Вызывающий объект должен проверка фактически выделенный объем памяти, как описано в MDL.

Вызывающий объект должен использовать MmFreePagesFromMdl , чтобы освободить страницы памяти, описанные в MDL, созданном mmAllocateNodePagesForMdlEx. После вызова MmFreePagesFromMdl вызывающий объект также должен вызвать ExFreePool , чтобы освободить память, выделенную для структуры MDL.

По умолчанию MmAllocateNodePagesForMdlEx заполняет выделенные страницы нулями. Вызывающий объект может указать флаг MM_DONT_ZERO_ALLOCATION, чтобы переопределить это значение по умолчанию и, возможно, повысить производительность.

Память, выделенная MmAllocateNodePagesForMdlEx , не инициализируется, если указать флаг MM_DONT_ZERO_ALLOCATION. Драйвер режима ядра должен сначала обнулить эту память, если драйвер собирается сделать память видимой для программного обеспечения пользовательского режима (чтобы избежать утечки потенциально привилегированного содержимого). Дополнительные сведения об этом флаге см. в разделе MM_ALLOCATE_XXX.

Максимальный объем памяти, который mmAllocateNodePagesForMdlEx может выделить в одном вызове, составляет (4 гигабайта — PAGE_SIZE). Подпрограмма может удовлетворить запрос на выделение для этой суммы, только если доступно достаточно страниц.

MmAllocateNodePagesForMdlEx выполняется в IRQL <= APC_LEVEL. При необходимости драйвер может вызвать MmAllocateNodePagesForMdlEx по DISPATCH_LEVEL. Тем не менее вы можете повысить производительность драйвера, вызвав APC_LEVEL или ниже.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (см. раздел "Примечания"))