mmMapLockedPagesSpecifyCache 函式 (wdm.h)

  • 發行項

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 必須描述鎖定的實體頁面。 MmProbeAndLockPages 或 MmAllocatePagesForMdlEx 例程可以建置鎖定的 MDL。 如需使用者空間的對應，可以使用 MmBuildMdlForNonPagedPool 例程所建置的 MDL。

[in] AccessMode

指定要對應 MDL： KernelMode 或 UserMode 的存取模式。 幾乎所有驅動程式都應該使用 KernelMode。

[in] CacheType

指定 MEMORY_CACHING_TYPE 值，指出用來對應 MDL 的快取屬性。 如需詳細資訊，請參閱接下來的＜備註＞一節。

[in, optional] RequestedAddress

如果 AccessMode UserMode = ，此參數會指定要將 MDL 對應至的起始使用者虛擬位址，或設定為 NULL 以允許系統選擇起始位址。 系統可能會四捨五入要求的位址以符合位址界限需求，因此呼叫端必須檢查傳回值。

[in] BugCheckOnFailure

指定因為低系統資源而無法對應 MDL 時，AccessModeKernelMode = 例程的行為。 如果 為 TRUE，系統就會發出錯誤檢查。 如果 為 FALSE，則例程會傳回 NULL。 驅動程式必須將此參數設定為 FALSE。

[in] Priority

MM_PAGE_PRIORITY值，指出當分頁表專案 (TE) 很罕見時，成功的重要性。 從 Windows 8 開始，指定的優先順序值可以是具有 MdlMappingNoWrite 或 MdlMappingNoExecute 旗標的位 ORed，以指定寫入或指令執行停用的記憶體。 如需 Priority 可能值的詳細資訊，請參閱 MmGetSystemAddressForMdlSafe。

傳回值

MmMapLockedPagesSpecifyCache 會傳回對應頁面的起始位址。 如果無法對應頁面， 且 BugCheckOnFailure 為 FALSE，例程會傳回 NULL。

備註

使用 MmUnmapLockedPages 來取消對應 MmMapLockedPagesSpecifyCache 所對應的實體頁面。

如果 AccessMode 是 KernelMode，如果 MmMapLockedPagesSpecifyCache 無法對應指定的頁面，則例程會傳回 NULL (如果 BugCheckOnFailure = FALSE) ，或操作系統在 BugCheckOnFailure = TRUE) 時發出錯誤檢查 (。

如果 AccessMode 是 UserMode，請注意下列詳細資料：

  • 如果無法對應指定的頁面，例程會引發例外狀況。 指定 UserMode 的呼叫端必須在 try/except 區塊中包裝對 MmMapLockedPagesSpecifyCache 的呼叫。 如需詳細資訊，請參閱 處理例外狀況。

  • 例程會傳回在驅動程序執行所在的進程內容中有效的用戶位址。 例如，如果64位驅動程式是在32位應用程式的內容中執行，則緩衝區會對應至應用程式32位位址範圍內的位址。

  • AccessMode 為 UserMode 時，一律會建立非可執行文件對應。 因此，在此案例中，不需要搭配 Priority 參數使用 MdlMappingNoExecute 旗標。 不過， MdlMappingNoWrite 旗標仍可與此案例中的 Priority 參數搭配使用，以要求只讀對應。

  • 使用 MdlMappingNoWrite 旗標搭配 Priority 參數所指定的對應，以及任何使用 MdlMappingNoWrite 旗標所指定之對應的非可執行保護，都不能由在使用者模式中執行的程式代碼變更。 例如，如果驅動程式將某些頁面對應至用戶進程，並指定 MdlMappingNoWrite 旗標，則系統會保證進程無法修改頁面。

只有當 MDL 所描述的頁面還沒有與其相關聯的快取類型時，例程才會使用 CacheType 參數。 不過，在幾乎所有情況下，頁面已經有相關聯的快取類型，而新的對應會使用此快取類型。 此規則的例外狀況是 MmAllocatePagesForMdl 所配置的頁面，這些頁面沒有相關聯的特定快取類型。 針對這類頁面， CacheType 參數會決定對應的快取類型。

驅動程式不得嘗試為 MDL 建立多個系統地址空間對應。 此外，由於 MmBuildMdlForNonPagedPool 例程所建置的 MDL 已經對應至系統地址空間，因此驅動程式不得嘗試使用 MmMapLockedPagesSpecifyCache 例程再次將這個 MDL 對應至系統地址空間 (，但允許建立使用者位址空間對應) 。 如果不知道鎖定的 MDL 是否已經有系統地址空間對應，驅動程式可以使用 MmGetSystemAddressForMdlSafe 宏，而不是 MmMapLockedPagesSpecifyCache。 如果 MDL 已經對應到系統地址空間， MmGetSystemAddressForMdlSafe 會傳回現有的系統地址空間對應，而不是建立新的對應。

警告

將核心記憶體對應至使用者位址空間的驅動程式，必須避免將潛在的機密核心數據公開給不受信任的進程。 未初始化的緩衝區，例如從集區配置的緩衝區，必須在對應之前明確填入零。 此外，從集區配置的使用者模式緩衝區大小必須是虛擬記憶體頁面大小的倍數，以防止緩衝區中的任何部分用於其他配置。 最後，緩衝區在仍對應至使用者位址空間時，不得釋回集區。

如果 AccessMode 是 UserMode，呼叫端必須在 IRQL <= APC_LEVEL執行。 如果 AccessMode 是 KernelMode，呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。

規格需求

需求 值
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL 請參閱一節。
DDI 合規性規則 HwStorPortProhibitedDIS (storport)

另請參閱

MmAllocatePagesForMdl

MmAllocatePagesForMdlEx

MmBuildMdlForNonPagedPool

MmGetSystemAddressForMdlSafe

MmProbeAndLockPages

MmUnmapLockedPages