ExAllocatePoolWithTag 函式 (wdm.h)

發行項
02/27/2024

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

警告

ExAllocatePoolWithTag 在 Windows 10 2004 版中已被取代，且已由 ExAllocatePool2 取代。如需詳細資訊，請參閱更新對 ExAllocatePool2 和 ExAllocatePool3 的已淘汰 ExAllocatePool 呼叫。

語法

PVOID ExAllocatePoolWithTag(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes,
  [in] ULONG                                          Tag
);

參數

[in] PoolType

要配置的集區內存類型。如需可用集區內存類型的描述，請參閱 POOL_TYPE。

您可以使用 POOL_RAISE_IF_ALLOCATION_FAILURE 旗標，以位 ORing 此值來修改 PoolType 值。如果無法滿足要求，此旗標就會引發例外狀況。不建議使用POOL_RAISE_IF_ALLOCATION_FAILURE旗標，因為它成本很高。

同樣地，您可以使用 POOL_COLD_ALLOCATION 旗標位 ORing 此值來修改 PoolType 值，作為核心的提示，以從可能快速分頁的頁面配置記憶體。若要盡可能減少駐留集區內存的數量，您不應該經常參考這些配置。 POOL_COLD_ALLOCATION旗標只是諮詢。

[in] NumberOfBytes

要配置的位元組數目。

[in] Tag

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

傳回值

如果可用集區中的記憶體不足，ExAllocatePoolWithTag 會傳回 NULL，以滿足要求。否則，例程會傳回所配置記憶體的指標。

備註

此例程用於記憶體的一般集區配置。

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

要求非分頁集區之 NumberOfBytes< PAGE_SIZE的成功配置，可讓呼叫端確切地提供要求的記憶體位元組數目。如果 NumberOfBytes> 的配置要求PAGE_SIZE成功， 而 NumberOfBytes 不是PAGE_SIZE的確切倍數，則配置中的最後一頁包含不是呼叫端配置一部分的位元組。可能的話，集區配置器會使用這些位元組。若要避免損毀屬於其他核心模式元件的數據，驅動程式必須只存取明確配置的記憶體位址。

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

Tag 的值會以反向 (小端) 順序來儲存，有時會顯示。例如，如果呼叫端傳遞『Fred』做為標籤，則會在集區傾印和調試程式中的集區使用量追蹤中顯示為「derF」，並在登錄和工具中顯示0x64657246。

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

當集區數量 (分頁或非分頁) 高或低時，系統會自動設定特定標準事件物件。驅動程式可以等候這些事件調整其集區使用量。如需詳細資訊，請參閱標準事件物件。

ExAllocatePoolWithTag 的呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。在 DISPATCH_LEVEL 執行的呼叫端必須指定 PoolType 的 NonPagedXxx 值。在 IRQL <= APC_LEVEL執行的呼叫端可以指定任何 POOL_TYPE 值，但也必須考慮 IRQL 和環境來判斷頁面類型。

請勿設定 NumberOfBytes = 0。避免零長度配置，因為它們會浪費集區標頭空間，而且在許多情況下，表示呼叫程式代碼中的潛在驗證問題。基於這個理由，驅動程式驗證器會標示這類配置可能的錯誤。

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

ExAllocatePoolWithTag 配置的記憶體未初始化。如果核心模式驅動程式要讓使用者模式軟體看見 (，以避免) 外泄潛在特殊許可權的內容，則核心模式驅動程式必須先將這個記憶體零。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (请参阅一节)
DDI 合規性規則	CheckDeviceObjectFlags (wdm) 、 HwStorPortProhibitedDIs (storport ) 、 IrqlExAllocatePool (wdm ) 、 IrqlExFree1 (wdm) 、 PowerDownAllocate (wdm) 、 PowerUpFail (wdm) 、 SpNoWait (storport ) 、 StorPortStartIo (storport ) 、 UnsafeAllocatePool (kmdf) 、 UnsafeAllocatePool (wdm)