ExAllocatePoolWithTag 関数 (wdm.h)
ExAllocatePoolWithTag ルーチンは、指定した型のプール メモリを割り当て、割り当てられたブロックへのポインターを返します。
警告
ExAllocatePoolWithTag は、バージョン 2004 Windows 10で非推奨となり、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」を参照してください。
PoolType 値は、POOL_RAISE_IF_ALLOCATION_FAILURE フラグを使用してビットごとの ORing を使用して変更できます。 このフラグを指定すると、要求を満たすことができない場合に例外が発生します。 POOL_RAISE_IF_ALLOCATION_FAILURE フラグの使用は、コストがかかるためお勧めしません。
同様に、 この 値をビットごとの ORing で変更し、POOL_COLD_ALLOCATION フラグをカーネルのヒントとして使用して、ページアウトされる可能性が高いページからメモリを割り当てることができます。 常駐プール メモリの量をできるだけ減らすには、これらの割り当てを頻繁に参照しないでください。 POOL_COLD_ALLOCATION フラグは、アドバイザリのみです。
[in] NumberOfBytes
割り当てるバイト数。
[in] Tag
割り当てられたメモリに使用するプール タグ。 プール タグを、単一引用符で区切られた 1 から 4 文字の 0 以外の文字リテラルとして指定します (例: 'Tag1')。 文字列は通常、逆の順序で指定されます (例: '1gaT')。 タグ内の各 ASCII 文字は、0x7E (チルダ) 0x20 (スペース) の範囲内の値である必要があります。 各割り当てコード パスでは、デバッガーと検証者がコード パスを識別するのに役立つ一意のプール タグを使用する必要があります。
戻り値
要求を満たすために空きプールにメモリが不足している場合、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 用デバッグ ツールに含まれるツールで、特定のプール タグに対する 特別なプール からの割り当てを要求するシステム機能を有効にします。 WDK に含まれる Poolmon は、プール タグによってメモリを追跡します。
Tag の値は、逆 (リトル エンディアン) の順序で格納され、表示される場合があります。 たとえば、呼び出し元が 'Fred' を タグとして渡した場合、プール ダンプとデバッガーのプール使用状況の追跡では "derF" として表示され、レジストリとツールの0x64657246として表示されます。
割り当てられたバッファーは、ExFreePool または ExFreePoolWithTag を使用して解放できます。
プールの量 (ページまたは非ページ) が高いか低い場合、システムは特定の標準イベント オブジェクトを自動的に設定します。 ドライバーは、これらのイベントがプールの使用状況を調整するのを待つことができます。 詳細については、「 標準イベント オブジェクト」を参照してください。
ExAllocatePoolWithTag の呼び出し元は、IRQL <= DISPATCH_LEVELで実行する必要があります。 DISPATCH_LEVELで実行する呼び出し元は、PoolType に NonPagedXxx 値を指定する必要があります。 IRQL <= APC_LEVEL で実行する呼び出し元は、任意 のPOOL_TYPE 値を指定できますが、IRQL と環境もページの種類を決定するために考慮する必要があります。
NumberOfBytes = 0 を設定しないでください。 長さ 0 の割り当てを避けます。プール ヘッダー領域が無駄になり、多くの場合、呼び出し元のコードで検証の問題が発生する可能性があることを示しています。 このため、 ドライバー検証ツールは 、このような割り当てを可能なエラーとしてフラグを設定します。
非一様メモリ アクセス (NUMA) マルチプロセッサ アーキテクチャでは、 ExAllocatePoolWithTag は 、ExAllocatePoolWithTag を呼び出しているプロセッサにローカルなメモリの割り当てを試みます。 使用可能なローカル メモリがない場合、 ExAllocatePoolWithTag は最も近い使用可能なメモリを割り当てます。
ExAllocatePoolWithTag が割り当てるメモリは初期化されていません。 カーネル モード ドライバーは、このメモリをユーザー モード ソフトウェアに表示する場合は、まずこのメモリをゼロにする必要があります (特権のある可能性のあるコンテンツがリークされないようにするため)。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |