ExAllocatePoolWithTag 函式 (wdm.h)

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

語法

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

規格需求

另請參閱

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE