ExAllocatePool2 関数 (wdm.h)

  • [アーティクル]

ExAllocatePool2 ルーチンは、指定した型のプール メモリを割り当て、割り当てられたブロックへのポインターを返します。

構文

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

パラメーター

Flags

必要な属性と省略可能な属性と共にプール メモリの種類を指定するULONG64型指定された値。 ビットごとの OR を使用して、複数のフラグ値を組み合わせることができます。 使用可能な値については 、「POOL_FLAGS 」を参照してください。

NumberOfBytes

割り当てる 0 以外のバイト数を指定します。

Tag

割り当てられたメモリに使用するプール タグ。 プール タグを、単一引用符で区切られた 1 ~ 4 文字の 0 以外の文字リテラルとして指定します (例: Tag1)。 文字列は通常、逆の順序で指定されます (例: 1gaT)。 タグ内の各 ASCII 文字は、0x7E (チルダ) に0x20 (スペース) の範囲内の値である必要があります。 各割り当てコード パスでは、デバッガーと検証者がコード パスを識別するのに役立つ一意のプール タグを使用する必要があります。

戻り値

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 用デバッグ ツールに含まれているツールで、特定のプール タグの特別なプールからの割り当てを要求するシステム機能を有効にします。 WDK に含まれている Poolmon は、プール タグによってメモリを追跡します。

Tag の値は、逆 (リトル エンディアン) 順に格納され、表示される場合があります。 たとえば、呼び出し元がタグとして渡 Fred された場合、呼び出し元はプール ダンプとデバッガーのプール使用状況の追跡のように表示 derF され、レジストリやツールの表示と同様 0x64657246 に表示されます。

割り当てられたバッファーは、ExFreePool または ExFreePoolWithTag を使用して解放できます。

ExAllocatePool2 の呼び出し元は、IRQL <= DISPATCH_LEVELで実行されている必要があります。 DISPATCH_LEVEL でを実行する呼び出し元は、フラグのPOOL_FLAG_NON_PAGEDまたはPOOL_FLAG_NON_PAGED_EXECUTABLEを指定する必要があります。 IRQL <= APC_LEVEL で実行されている呼び出し元は 、POOL_FLAG_PAGEDを指定できますが、DISPATCH_LEVELで実行されているコードからメモリにアクセスする場合は、ページングされていないメモリを割り当てる必要があります。

非均一メモリ アクセス (NUMA) マルチプロセッサ アーキテクチャでは、ExAllocatePool2 は、ExAllocatePool2 を呼び出しているプロセッサにローカルなメモリの割り当てを試みます。 使用可能なローカル メモリがない場合、 ExAllocatePool2 は使用可能な最も近いメモリを割り当てます。

ExAllocatePool2 が割り当てるメモリは 0 初期化されます。 カーネル モード ドライバーは、機密情報の開示を避けるために、信頼されていない場所 (ユーザー モード、ネットワーク上など) にコピーされる割り当てのゼロ化をオプトアウトしないでください。

要件

要件 値
サポートされている最小のクライアント Windows 10 バージョン 2004
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 HwStorPortProhibitedDDIs、SpNoWait、StorPortStartIo

こちらもご覧ください

ExAllocatePool3