Share via

ExAllocatePoolWithTagPriority 関数 (wdm.h)

  • [アーティクル]

ExAllocatePoolWithTagPriority ルーチンは、指定された型のプール メモリを割り当てます。

警告

ExAllocatePoolWithTagPriority は、バージョン 2004 Windows 10で非推奨となり、ExAllocatePool3 に置き換えられました。 詳細については、「 ExAllocatePool2 および ExAllocatePool3 への非推奨の ExAllocatePool 呼び出しの更新」を参照してください。

構文

PVOID ExAllocatePoolWithTagPriority(
  [in] __drv_strictTypeMatch(__drv_typeCond)POOL_TYPE        PoolType,
  [in] SIZE_T                                                NumberOfBytes,
  [in] ULONG                                                 Tag,
  [in] __drv_strictTypeMatch(__drv_typeExpr)EX_POOL_PRIORITY Priority
);

パラメーター

[in] PoolType

割り当てるプール メモリの種類。 使用可能なプール メモリの種類の詳細については、「 POOL_TYPE」を参照してください。

PoolType 値は、POOL_RAISE_IF_ALLOCATION_FAILURE フラグを使用してビットごとの ORing を使用して変更できます。 このフラグを指定すると、要求を満たすことができない場合に例外が発生します。

同様に、 この 値をビットごとの ORing で変更し、POOL_COLD_ALLOCATION フラグをカーネルのヒントとして使用して、ページアウトされる可能性が高いページからメモリを割り当てることができます。 常駐プール メモリの量をできるだけ減らすには、これらの割り当てを頻繁に参照しないでください。 POOL_COLD_ALLOCATION フラグはアドバイザリのみで、Windows XP 以降で使用できます。

[in] NumberOfBytes

割り当てるバイト数。

[in] Tag

割り当てられたメモリに使用するプール タグ。 詳細については、ExAllocatePoolWithTag の Tag パラメーターを参照してください。

[in] Priority

この要求の優先順位。 このパラメーターを、次のいずれかのEX_POOL_PRIORITY列挙値 に 設定します。

優先順位の値 説明
LowPoolPriority リソースが不足しているときにシステムが要求を失敗する可能性があることを指定します。 割り当てエラーから復旧できるドライバーの割り当てでは、この優先順位が使用されます。
NormalPoolPriority リソースが非常に少ない場合に、システムが要求を失敗する可能性があることを指定します。 ほとんどのドライバーでは、この値を使用する必要があります。
HighPoolPriority リソースが完全に不足していない限り、システムが要求を失敗しないように指定します。 ドライバーは、要求が成功することが非常に重要な場合にのみ、この値を使用します。

EX_POOL_PRIORITY列挙では、XxxSpecialPoolOverrun および XxxSpecialPoolUnderrun バリアントを定義して、ドライバー検証ツール (または特別なプール) を有効にしたときのメモリの割り当て方法を指定します。 ドライバーが XxxSpecialPoolUnderrun を指定した場合、 メモリ マネージャー が 特別なプールからメモリを割り当てるときに、物理ページの先頭に割り当てます。 ドライバーで XxxSpecialPoolOverrun が指定されている場合、メモリ マネージャーは物理ページの末尾に割り当てます。

戻り値

ExAllocatePoolWithTagPriority は、POOL_RAISE_IF_ALLOCATION_FAILUREが指定されていない限り、要求を満たすために空きプールに十分なメモリがない場合に NULL を 返します。 それ以外の場合、ルーチンは割り当てられたメモリへのポインターを返します。

注釈

ExAllocatePoolWithTagPriority の呼び出し元は、IRQL <= DISPATCH_LEVELで実行する必要があります。 DISPATCH_LEVELで実行する呼び出し元は、PoolType に NonPagedXxx 値を指定する必要があります。 IRQL <= APC_LEVEL で実行する呼び出し元は、任意 のPOOL_TYPE 値を指定できますが、IRQL と環境もページの種類を決定するために考慮する必要があります。

NumberOfBytes がPAGE_SIZE以上の場合は、ページアラインバッファーが割り当てられます。 PAGE_SIZE以下のメモリ割り当てはページ内で割り当てられ、ページ境界を越えるものではありません。 PAGE_SIZE未満のメモリ割り当ては、必ずしもページアラインされるとは限りませんが、32 ビット システムでは 8 バイト境界、64 ビット システムでは 16 バイト境界にアラインされます。

NumberOfBytes = 0 を設定しないでください。 長さ 0 の割り当てを避けます。プール ヘッダー領域が無駄になり、多くの場合、呼び出し元のコードで検証の問題が発生する可能性があることを示しています。 このため、 ドライバー検証ツールは 、このような割り当てを可能なエラーとしてフラグを設定します。

プールの量 (ページまたは非ページ) が高いか低い場合、システムは特定の標準イベント オブジェクトを自動的に設定します。 ドライバーは、これらのイベントがプールの使用状況を調整するのを待つことができます。 詳細については、「 標準イベント オブジェクト」を参照してください。

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

ExAllocatePoolWithTagPriority によって割り当てられるメモリは初期化されていません。 カーネル モード ドライバーは、このメモリをユーザー モード ソフトウェアに表示する場合は、まずこのメモリをゼロにする必要があります (特権のある可能性のあるコンテンツがリークされないようにするため)。

要件

要件 値
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

こちらもご覧ください

ExAllocatePoolWithTag

ExFreePool

POOL_TYPE