Функция MapUserPhysicalPages (memoryapi.h)

Статья
08/24/2023

Сопоставляет ранее выделенные страницы физической памяти по указанному адресу в регионе расширений адресных окон (AWE).

Чтобы выполнить пакетное сопоставление и распакуть несколько регионов, используйте функцию MapUserPhysicalPagesScatter .

64-разрядная версия Windows в системах на основе Itanium: Из-за различий в размерах страниц MapUserPhysicalPages не поддерживается для 32-разрядных приложений.

Синтаксис

BOOL MapUserPhysicalPages(
  [in] PVOID      VirtualAddress,
  [in] ULONG_PTR  NumberOfPages,
  [in] PULONG_PTR PageArray
);

Параметры

[in] VirtualAddress

Указатель на начальный адрес области памяти для переназначения.

Значение lpAddress должно находиться в диапазоне адресов, возвращаемом функцией VirtualAlloc при выделении области Расширения адресного окна (AWE).

[in] NumberOfPages

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

Диапазон виртуальных адресов является непрерывным, начиная с lpAddress. Физические кадры задаются UserPfnArray.

Общее количество страниц не может расширяться от начального адреса за пределы конца диапазона, указанного в параметре AllocateUserPhysicalPages.

[in] PageArray

Указатель на массив физических номеров кадров страницы.

Эти кадры сопоставляются аргументом lpAddress при возврате из этой функции. Размер выделенной памяти должен быть не меньше , чем NumberOfPages , чем размер типа данных ULONG_PTR.

Не пытайтесь изменить этот буфер. Он содержит данные операционной системы, и повреждение может привести к катастрофическим последствиям. Сведения в буфере не являются полезными для приложения.

Если этот параметр имеет значение NULL, указанный диапазон адресов не сопоставляется. Кроме того, указанные физические страницы не освобождаются, и необходимо вызвать FreeUserPhysicalPages , чтобы освободить их.

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

Если функция выполняется успешно, возвращается значение TRUE.

Если функция завершается сбоем, возвращается значение FALSE , а сопоставление не выполняется — частичное или иным образом. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

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

Невозможно сопоставить страницы физической памяти за пределами диапазона, указанного в параметре AllocateUserPhysicalPages. Можно сопоставить несколько регионов одновременно, но они не могут перекрываться.

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

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

В многопроцессорной среде эта функция поддерживает согласованность буфера аппаратного преобразования. При возвращении из этой функции все потоки на всех процессорах гарантированно увидят правильное сопоставление.

Чтобы скомпилировать приложение, использующее эту функцию, определите макрос _WIN32_WINNT как 0x0500 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Примеры

Пример см. в разделе Пример AWE.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	memoryapi.h (включая Windows.h, Memoryapi.h)
Библиотека	onecore.lib
DLL	Kernel32.dll