MmAllocatePagesForMdlEx 函式 (wdm.h)

  • 發行項

MmAllocatePagesForMdlEx 例程會將非分頁的實體記憶體分頁配置給 MDL。

使用此例程，而不是 MmAllocatePagesForMdl。

語法

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

參數

[in] LowAddress

指定第一個位址範圍的開始實體位址，而配置的頁面可以來自該範圍。 如果 MmAllocatePagesForMdlEx 無法在第一個位址範圍中配置要求的位元組數目，它會逐一查看其他位址範圍以取得更多頁面。 在每個反覆專案中， MmAllocatePagesForMdlEx 會將 SkipBytes 的值新增至先前的起始位址，以取得下一個位址範圍的開始。

[in] HighAddress

指定配置之頁面可以來自之第一個位址範圍結尾的實體位址。

[in] SkipBytes

指定要從前一個位址範圍的開頭略過的位元組數目，這些位址範圍是配置的頁面可以來自該位址範圍。 SkipBytes 必須是虛擬記憶體頁面大小的整數倍數，以位元組為單位。

[in] TotalBytes

指定要配置給 MDL 的位元組總數。

[in] CacheType

指定 MEMORY_CACHING_TYPE 值，這個值表示要求記憶體允許的快取類型。

[in] Flags

指定此作業的旗標。 將此參數設定為零或下列其中一或多個 MM_ALLOCATE_XXX 旗標位的位 OR：

上述清單中的最後四個專案僅支援 Windows 7 和更新版本的 Windows。

值 意義
MM_DONT_ZERO_ALLOCATION 0x00000001 請勿以零填滿已配置的頁面。 根據預設，MmAllocatePagesForMdlEx 會將配置的頁面零。 藉由略過這項作業，您可以改善 MmAllocatePagesForMdlEx 呼叫的效能。 不過，除非您從未將配置的頁面公開給使用者模式程式，否則您一律會覆寫頁面的原始內容，才能將配置的頁面公開給使用者模式程式，否則您不得使用此旗標。
MM_ALLOCATE_FROM_LOCAL_NODE_ONLY 0x00000002 只從理想的節點配置頁面。 此旗標僅適用於具有非統一記憶體存取 (NUMA) 架構的多處理器系統。 從 Windows Vista 開始，此旗標表示所有頁面都必須從目前線程的理想節點配置。 不會從其他節點配置任何頁面。 在 Windows Vista 之前的 Windows 版本中，此旗標表示所有頁面都必須從本機節點配置;也就是說，從目前處理器所屬的節點。 如需 NUMA 多處理器系統的詳細資訊，請參閱 NUMA 支援 。
MM_ALLOCATE_FULLY_REQUIRED 0x00000004 需要完整配置。 從 Windows 7 開始，如果無法配置所有要求的頁面，此旗標需要 MmAllocatePagesForMdlEx 傳回 NULL。 只有在例程成功取得整個要求的配置時，才會傳回非NULL 值。 此旗標可讓記憶體管理員在呼叫端需要完整配置的情況下更有效率地執行配置。
MM_ALLOCATE_NO_WAIT 0x00000008 請勿等候。 從 Windows 7 開始，此旗標表示 MmAllocatePagesForMdlEx 呼叫不得封鎖呼叫線程。 一般而言，呼叫端是在 IRQL < DISPATCH_LEVEL 執行的核心模式驅動程式，但無法允許封鎖其執行。 例如，驅動程式可能會協助分頁或電源管理作業。 不論是否已設定此旗標，MmAllocatePagesForMdlEx 永遠不會封鎖在 IRQL = DISPATCH_LEVEL執行的呼叫端。
MM_ALLOCATE_PREFER_CONTIGUOUS 0x00000010 配置會以最小化系統記憶體片段的方式執行。 從 Windows 7 開始，此旗標表示呼叫端想要避免分散物理記憶體，讓其他呼叫端能夠使用更連續的記憶體。 配置的頁面不保證 (，而且通常不會) 實際連續，即使有大量的連續記憶體也一樣。 需要連續記憶體的呼叫端應該指定MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS，而不是MM_ALLOCATE_PREFER_CONTIGUOUS。
MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS 0x00000020 需要連續記憶體。 從 Windows 7 開始，此旗標表示要求的頁面必須配置為連續的物理記憶體區塊。 如果 SkipBytes 參數為零，MmAllocatePagesForMdlEx 會成功並傳回單一連續區塊，否則會失敗並傳回 NULL。 它永遠不會傳回部分配置。 對於 SkipBytes = 0，配置的頁面符合 LowAddress 和 HighAddress 參數所指定的位址範圍需求，但頁面不受特殊對齊限制。 如果 SkipBytes 為非零值，SkipBytes 必須是兩個乘冪，而且必須大於或等於 PAGE_SIZE，TotalBytes 參數值必須是 SkipBytes 的倍數。 在此情況下，傳回的 MDL 可以包含多個連續頁面區塊。 也就是說，每個區塊在內部是連續的，但區塊不一定彼此連續。 連續頁面的每個區塊保證完全相同，而且在SkipBytes界限上對齊。 如果 SkipBytes 不是零，但部分配置中的每個連續區塊保證為 SkipBytes long，就會發生部分配置。
MM_ALLOCATE_FAST_LARGE_PAGES 0x00000040 從 Windows 8 開始，此旗標會指定必須從操作系統的大型頁面快取滿足配置。 如果快取是空的，配置就會失敗。  如果未指定 MM_ALLOCATE_FAST_LARGE_PAGES，MmAllocatePagesForMdlEx 會使用快取的大型頁面。 如果快取耗盡， MmAllocatePagesForMdlEx 會嘗試建構其他大型頁面，這可能需要很長的時間。 MM_ALLOCATE_FAST_LARGE_PAGES必須與 MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS 旗標搭配使用。 SkipBytes 參數必須設定為大型頁面大小的倍數。
MM_ALLOCATE_AND_HOT_REMOVE 0x00000100 從 Windows 10 開始，此旗標會使配置的頁面從 Windows 管理的實體記憶體集區中移除。 MM_ALLOCATE_AND_HOT_REMOVE無法與MM_ALLOCATE_FULLY_REQUIRED一起指定。 如果指定MM_ALLOCATE_AND_HOT_REMOVE，呼叫端必須在 IRQL = PASSIVE_LEVEL執行。

傳回值

MmAllocatePagesForMdlEx 會傳回下列其中一項：

傳回碼 Description
MDL 指標 非 NULL 傳回值是 MDL 的指標，可描述指定位址範圍中的一組實體頁面。 如果要求的位元組數目無法使用，MDL 會描述可用的物理記憶體數量。
NULL 表示指定的位址範圍中沒有可用的物理記憶體分頁，或 MDL 本身沒有足夠的記憶體集區。

備註

根據預設， MmAllocatePagesForMdlEx 傳回的實體記憶體頁面不是連續的頁面。 從 Windows 7 開始，呼叫端可以在 Flags 參數中設定MM_ALLOCATE_PREFER_CONTIGUOUS或MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS旗標位，來覆寫此例程的預設行為。

MmAllocatePagesForMdlEx 是專為不需要對應虛擬位址的內核模式驅動程式所設計， (也就是說，它們需要實體頁面，而且不需要實體連續) ，以及如果裝置的實體記憶體配置在特定實體位址範圍中，可以達到大幅效能提升的核心模式驅動程式 (，例如， AGP 圖形) 。

根據要求範圍中目前可用的物理內存量而定， MmAllocatePagesForMdlEx 可能會傳回描述記憶體少於要求的 MDL。 如果未配置任何記憶體，例程也可能傳回 NULL 。 呼叫端應該檢查實際配置給 MDL 的記憶體數量。

呼叫端必須使用 MmFreePagesFromMdl 釋放 由 MmAllocatePagesForMdlEx 所建立之 MDL 所描述的記憶體頁面。 呼叫 MmFreePagesFromMdl 之後，呼叫端也必須呼叫 ExFreePool ，以釋放為 MDL 結構配置的記憶體。

根據預設， MmAllocatePagesForMdlEx 會填滿配置零的頁面。 呼叫端可以指定MM_DONT_ZERO_ALLOCATION旗標來覆寫此預設值，並可能改善效能。

如果您指定MM_DONT_ZERO_ALLOCATION旗標， MmAllocatePagesForMdlEx 配置的記憶體不會初始化。 如果驅動程式要讓使用者模式軟體看到記憶體，則核心模式驅動程序必須先將這個記憶體零 (，以避免) 洩漏潛在的特殊許可權內容。 如需此旗標的詳細資訊，請參閱 MM_ALLOCATE_XXX。

MmAllocatePagesForMdlEx 可以在單一呼叫中配置的記憶體數量上限為 (4 GB - PAGE_SIZE) 。 只有在有足夠的頁面可用時，例程才能滿足此數量的配置要求。

MmAllocatePagesForMdlEx 會在 IRQL <= APC_LEVEL執行。 允許 mmAllocatePagesForMdlEx 的呼叫端位於 DISPATCH_LEVEL。 不過，您可以藉由在 APC_LEVEL 或以下呼叫 來改善驅動程式效能。

規格需求

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

另請參閱

ExFreePool

MEMORY_CACHING_TYPE

MmAllocatePagesForMdl

MmFreePagesFromMdl

MmMapLockedPages