ExAllocatePoolWithTag 関数 (wdm.h)

[アーティクル]
02/27/2024

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 フラグはコストがかかるため、使用しないことをお勧めします。

同様に、この値を POOL_COLD_ALLOCATION フラグでカーネルにヒントとしてビット単位で ORing することで 、PoolType 値を変更して、ページアウトされる可能性が高いページからメモリを割り当てることができます。常駐プールのメモリ量をできるだけ減らすには、これらの割り当てを頻繁に参照しないでください。 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)