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

Статья
03/08/2023

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

Синтаксис

PVOID MmMapLockedPagesSpecifyCache(
  [in]           PMDL                                                                          MemoryDescriptorList,
  [in]           __drv_strictType(KPROCESSOR_MODE / enum _MODE,__drv_typeConst)KPROCESSOR_MODE AccessMode,
  [in]           __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE                      CacheType,
  [in, optional] PVOID                                                                         RequestedAddress,
  [in]           ULONG                                                                         BugCheckOnFailure,
  [in]           ULONG                                                                         Priority
);

Параметры

[in] MemoryDescriptorList

Указатель на MDL, который необходимо сопоставить. Этот MDL должен описывать физические страницы, которые заблокированы. Заблокированный MDL можно создать с помощью процедуры MmProbeAndLockPages или MmAllocatePagesForMdlEx . Для сопоставлений с пользовательским пространством можно использовать многомерные списки MDL, созданные подпрограммой MmBuildMdlForNonPagedPool .

[in] AccessMode

Указывает режим доступа, в котором сопоставляется MDL: KernelMode или UserMode. Почти все драйверы должны использовать KernelMode.

[in] CacheType

Задает значение MEMORY_CACHING_TYPE , указывающее атрибут кэша, используемый для сопоставления MDL. Дополнительные сведения см. в разделе "Примечания".

[in, optional] RequestedAddress

В AccessMode = UserMode этот параметр указывает виртуальный адрес начального пользователя для сопоставления MDL или значение NULL , чтобы позволить системе выбрать начальный адрес. Система может округлить запрошенный адрес в соответствии с требованиями к границам, поэтому вызывающие стороны должны проверка возвращаемое значение.

[in] BugCheckOnFailure

Указывает поведение подпрограммы для AccessModeKernelMode = , если MDL не удается сопоставить из-за нехватки системных ресурсов. Если задано значение TRUE, система выдает ошибку проверка. Если значение FALSE, подпрограмма возвращает ЗНАЧЕНИЕ NULL. Драйверы должны задать для этого параметра значение FALSE.

[in] Priority

Значение MM_PAGE_PRIORITY , указывающее важность успешного выполнения, если записей таблицы страниц (PTEs) недостаточно. Начиная с Windows 8, указанное значение приоритета может быть битово-ORed с флагами MdlMappingNoWrite или MdlMappingNoExecute для указания памяти, в которой отключаются операции записи или инструкции. Дополнительные сведения о возможных значениях параметра Priority см. в разделе MmGetSystemAddressForMdlSafe.

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

MmMapLockedPagesSpecifyCache возвращает начальный адрес сопоставленных страниц. Если не удается сопоставить страницы и bugCheckOnFailure имеет значение FALSE, подпрограмма возвращает значение NULL.

Если Параметр AccessMode имеет значение KernelMode и если MmMapLockedPagesSpecifyCache не может сопоставить указанные страницы, подпрограмма возвращает значение NULL (если BugCheckOnFailure = FALSE) или операционная система выдает ошибку проверка (если BugCheckOnFailure = TRUE).

Если AccessMode имеет значение UserMode, имейте в виду следующие сведения:

Если не удается сопоставить указанные страницы, подпрограмма создает исключение. Вызывающие операторы, указывающие UserMode, должны заключать вызов MmMapLockedPagesSpecifyCache в блок try/except . Дополнительные сведения см. в разделе Обработка исключений.
Подпрограмма возвращает адрес пользователя, допустимый в контексте процесса, в котором выполняется драйвер. Например, если 64-разрядный драйвер работает в контексте 32-разрядного приложения, буфер сопоставляется с адресом в 32-разрядном диапазоне адресов приложения.
Неисполняемое сопоставление всегда создается, если AccessMode имеет значение UserMode. Поэтому в этом сценарии не требуется использовать флаг MdlMappingNoExecute с параметром Priority . Однако флаг MdlMappingNoWrite по-прежнему можно использовать с параметром Priority в этом сценарии для запроса сопоставления только для чтения.
Неисполняемая защита сопоставления и любая защита от записи сопоставления, указанного с помощью флага MdlMappingNoWrite с параметром Priority , не могут быть изменены кодом, выполняющимся в пользовательском режиме. Например, если драйвер сопоставляет некоторые страницы с пользовательским процессом и задает флаг MdlMappingNoWrite , система гарантирует, что процесс не сможет изменить страницы.

Подпрограмма использует параметр CacheType только в том случае, если страницы, описанные в MDL, еще не имеют связанного типа кэша. Однако почти во всех случаях страницы уже имеют связанный тип кэша, и этот тип кэша используется в новом сопоставлении. Исключением из этого правила являются страницы, выделенные MmAllocatePagesForMdl, с которыми не связан определенный тип кэша. Для таких страниц параметр CacheType определяет тип кэша сопоставления.

Драйвер не должен пытаться создать несколько сопоставлений системных адресов и пространств для MDL. Кроме того, так как MDL, созданный подпрограммой MmBuildMdlForNonPagedPool , уже сопоставлен с системным адресным пространством, драйвер не должен пытаться снова сопоставить этот MDL с системным адресным пространством с помощью подпрограммы MmMapLockedPagesSpecifyCache (хотя создание сопоставлений пространств адресов и пользователей разрешено). Если неизвестно, имеет ли заблокированный MDL сопоставление системного адресного пространства, драйвер может использовать макрос MmGetSystemAddressForMdlSafe вместо MmMapLockedPagesSpecifyCache. Если MDL уже сопоставлен с системным адресным пространством, MmGetSystemAddressForMdlSafe вернет существующее сопоставление системного адресного пространства вместо создания нового сопоставления.

Предупреждение

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

Если AccessMode имеет значение UserMode, вызывающий объект должен выполняться в irQL <= APC_LEVEL. Если параметр AccessMode имеет значение KernelMode, вызывающий объект должен выполняться в irQL <= DISPATCH_LEVEL.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
Правила соответствия DDI	HwStorPortProhibitedDIs(storport)