MmMapLockedPagesWithReservedMapping 函式 (wdm.h)

發行項
03/05/2024

MmMapLockedPagesWithReservedMapping 例程會對應所有或部分先前由 MmAllocateMappingAddress 例程保留的地址範圍。

語法

PVOID MmMapLockedPagesWithReservedMapping(
  [in] PVOID                                                    MappingAddress,
  [in] ULONG                                                    PoolTag,
  [in] PMDL                                                     MemoryDescriptorList,
  [in] __drv_strictTypeMatch(__drv_typeCond)MEMORY_CACHING_TYPE CacheType
);

參數

[in] MappingAddress

保留虛擬記憶體範圍的開頭指標。這必須是 MmAllocateMappingAddress 先前傳回的位址。

[in] PoolTag

指定保留記憶體緩衝區的集區標籤。這必須與呼叫保留緩衝區之 MmAllocateMappingAddress 的 PoolTag 參數中指定的值相同。

[in] MemoryDescriptorList

要對應的 MDL 指標。此 MDL 必須描述鎖定的實體頁面。鎖定的 MDL 可由 MmProbeAndLockPages 或 MmAllocatePagesForMdlEx 例程所建置。

[in] CacheType

指定要用來建立對應的 MEMORY_CACHING_TYPE 值。

傳回值

MmMapLockedPagesWithReservedMapping 會傳回對應記憶體開頭的指標，如果系統無法對應記憶體，則傳回 NULL 。只有當函式參數 (發生錯誤時，此例程才會傳回 NULL ，例如驅動程式的對應位址不足以跨越提供的 MDL) 。此函式旨在讓驅動程式即使在低資源案例中也能向前進行。

備註

呼叫端可以使用 MmMapLockedPagesWithReservedMapping 來對應 MmAllocateMappingAddress 所保留之虛擬記憶體範圍的子範圍，如下所示：

使用 IoAllocateMdl 來配置 MDL。傳回的 MDL 是使用要對應的虛擬記憶體範圍的指定起始位址和大小來建置。
使用 MmProbeAndLockPages 鎖定步驟 1 中取得之 MDL 所描述的實體頁面。
使用 MmMapLockedPagesWithReservedMapping 實際將虛擬記憶體對應至步驟 2 中鎖定的實體記憶體。請注意，此函式所傳回的虛擬位址確實包含 MDL 指定的位元移。不過，此函式所設定之 MDL 的 MappedSystemVa 欄位不包含位元組位移。
呼叫端不需要存取記憶體之後，它會使用 MmUnmapReservedMapping 取消對應記憶體。呼叫端可以視需要對應和取消對應記憶體緩衝區，而且必須先取消對應，才能使用 MmFreeMappingAddress 釋放對應範圍。

請注意， MappingAddress 參數會指定呼叫端先前保留的記憶體範圍的開頭，而不是要對應的記憶體子範圍開頭。呼叫端會在使用 IoAllocateMdl配置 MDL 時，指定緩衝區的起始位址和長度。緩衝區必須符合保留的記憶體範圍，但可以是嚴格的子集。

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

規格需求

需求	值
最低支援的用戶端	可在 Windows XP 和更新版本的 Windows 中使用。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport)