ExAllocatePool2 函式 (wdm.h)

  • 發行項

ExAllocatePool2 例程會配置指定類型的集區內存，並傳回已配置區塊的指標。

語法

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

參數

Flags

指定集區內存類型以及必要和選擇性屬性的ULONG64型別值。 您可以使用位 OR 結合多個旗標值。 如需可能的值 ，請參閱POOL_FLAGS 。

NumberOfBytes

指定要配置的位元組數目非零。

Tag

要用於已配置記憶體的集區標籤。 將集區標記指定為一到四個字元的非零字元常值， Tag1 以單引號分隔 (例如，) 。 字串通常會以反向順序指定 (，例如， 1gaT) 。 標記中的每個 ASCII 字元都必須是範圍0x20 (空格) 的值，才能0x7E (波浪) 。 每個配置程式代碼路徑都應該使用唯一的集區標籤，協助調試程式和驗證程式識別程式代碼路徑。

傳回值

ExAllocatePool2 會傳回已配置記憶體的指標。

下列條件會導致函式預設傳回NULL。 如果指定 POOL_FLAG_RAISE_ON_FAILURE ，函式會引發例外狀況。

  • 記憶體不足
  • 指定標籤 為 0 或無效POOL_FLAGS

備註

如果您要建置以 Windows 10 版本 2004 之前的 Windows 版本為目標的驅動程式，請使用 ExAllocatePoolZero、ExAllocatePoolUninitialized、ExAllocatePoolQuotaZero 或 ExAllocatePoolQuotaUninitialized。

此例程與先前的配置例程有下列差異， (ExAllocatePoolWithTag、 ExAllocatePoolWithQuotaTag、 ExAllocatePoolWithTagPriority) ：

  1. 除非指定 POOL_FLAG_UNINITIALIZED ，否則記憶體會以零初始化。

  2. 當配置失敗時，傳回行為。 ExAllocatePoolWithQuotaTag 預設會引發例外狀況。

  3. 值為 0 的標記無效。

將 ExAllocatePoolWithQuotaTag 取代為 ExAllocatePool2 時，您必須指定 POOL_FLAG_USE_QUOTA 旗標。 如需集區旗標的詳細資訊，請參閱 POOL_FLAGS。

如果 NumberOfBytes 是 PAGE_SIZE 或更新版本，則會配置頁面對齊的緩衝區。 或更少的記憶體配置 PAGE_SIZE 是在頁面內配置，而且不會跨越頁面界限。 小於 PAGE_SIZE 的記憶體配置不一定是頁面對齊，而是與 32 位系統中的 8 位元組界限對齊，以及 64 位系統中的 16 位元組界限。

驅動程式最多只能使用明確配置的 NumberOfBytes 。 存取超出此範圍的記憶體可能會損毀集區，並導致系統當機。

系統會將集區標籤與配置的記憶體產生關聯。 WinDbg 之類的程式設計工具可以顯示與每個配置緩衝區相關聯的集區標籤。 Gflags 是 Windows 偵錯工具中包含的工具，會開啟系統功能，要求從特殊集區配置特定集區標記。 Poolmon 包含在 WDK 中，會依集區標籤追蹤記憶體。

Tag 的值會以反向 (小到尾) 順序來儲存，有時會顯示。 例如，如果呼叫端以Tag的形式傳遞 Fred ，它會出現在 derF 集區傾印和調試程式的集區使用量追蹤中，如同 0x64657246 登錄和工具所示。

已配置的緩衝區可以使用 ExFreePool 或 ExFreePoolWithTag 釋放。

ExAllocatePool2 的呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。 在 DISPATCH_LEVEL 執行的呼叫端必須指定 flags的POOL_FLAG_NON_PAGED或POOL_FLAG_NON_PAGED_EXECUTABLE。 在 IRQL <= APC_LEVEL執行的呼叫端可以指定 POOL_FLAG_PAGED，但是如果記憶體將從執行DISPATCH_LEVEL的程式代碼存取，您仍必須配置非分頁記憶體。

在非統一記憶體存取 (NUMA) 多處理器架構中， ExAllocatePool2 會嘗試配置本機記憶體給呼叫 ExAllocatePool2 的處理器。 如果沒有可用的本機記憶體， ExAllocatePool2 會配置最接近的可用記憶體。

ExAllocatePool2 配置的記憶體會初始化為零。 核心模式驅動程式不應退出退出零，因為配置將會複製到不受信任的位置， (使用者模式、透過網路等 ) ，以避免揭露敏感性資訊。

規格需求

需求 值
最低支援的用戶端 Windows 10 (版本 2004)
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (请参阅一节)
DDI 合規性規則 HwStorPortProhibitedDIS、SpNoWait、StorPortStartIo

另請參閱

ExAllocatePool3