MmAllocateNodePagesForMdlEx 関数 (wdm.h)

[アーティクル]
10/24/2023

MmAllocateNodePagesForMdlEx ルーチンは、理想的なノードから非ページ物理メモリを割り当て、このメモリを記述する MDL 構造体を割り当てます。

構文

PMDL MmAllocateNodePagesForMdlEx(
  [in] PHYSICAL_ADDRESS    LowAddress,
  [in] PHYSICAL_ADDRESS    HighAddress,
  [in] PHYSICAL_ADDRESS    SkipBytes,
  [in] SIZE_T              TotalBytes,
  [in] MEMORY_CACHING_TYPE CacheType,
  [in] ULONG               IdealNode,
  [in] ULONG               Flags
);

パラメーター

[in] LowAddress

割り当てられたページを取得できる最初のアドレス範囲の先頭の物理アドレス。 MmAllocateNodePagesForMdlEx が最初のアドレス範囲に要求されたバイト数を割り当てることができない場合、ルーチンは追加のアドレス範囲を反復処理してより多くのページを取得します。各イテレーションで、 MmAllocateNodePagesForMdlEx は、前の開始アドレスに SkipBytes の値を追加して、次のアドレス範囲の開始を計算します。

[in] HighAddress

割り当てられたページの取得元となる最初のアドレス範囲の末尾の物理アドレス。

[in] SkipBytes

割り当てられたページの取得元となる前のアドレス範囲の先頭からスキップするバイト数。 SkipBytes は、仮想メモリページサイズの整数倍数 (バイト単位) である必要があります。

[in] TotalBytes

MDL に割り当てる合計バイト数。

[in] CacheType

MEMORY_CACHING_TYPE値。要求されたメモリに対して許可されるキャッシュの種類を示します。

[in] IdealNode

理想的なノード番号。マルチプロセッサシステムに N 個のノードが含まれている場合、有効なノード番号の範囲は 0 ~ N-1 です。ドライバーは、KeQueryHighestNodeNumber ルーチンを呼び出して、最も高いノード番号を取得できます。単一プロセッサまたは NUMA 以外のマルチプロセッサシステムには、メモリの割り当て元となるノード 0 が 1 つだけ存在します。 NUMA マルチプロセッサシステムの場合、割り当ては可能であれば理想的なノードから行われます。割り当て要求を満たすために理想的なノードで十分なメモリが不足していて、呼び出し元がMM_ALLOCATE_FROM_LOCAL_NODE_ONLY フラグを設定していない場合、 MmAllocateNodePagesForMdlEx は他のノードからメモリを割り当てようとします。

[in] Flags

この操作のフラグ。このパラメーターを 0 に設定するか、次のフラグビットの 1 つ以上のビットごとの OR に設定します。

MM_DONT_ZERO_ALLOCATION
MM_ALLOCATE_FROM_LOCAL_NODE_ONLY
MM_ALLOCATE_FULLY_REQUIRED
MM_ALLOCATE_NO_WAIT
MM_ALLOCATE_PREFER_CONTIGUOUS
MM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKS
MM_ALLOCATE_AND_HOT_REMOVE

これらのフラグの詳細については、「 MM_ALLOCATE_XXX」を参照してください。

戻り値

MmAllocateNodePagesForMdlEx は、成功した場合に MDL 構造体へのポインターを返します。それ以外の場合、ルーチンがメモリの割り当てに失敗した場合、ルーチンは NULL を返します。

戻り値 NULL は、指定されたアドレス範囲で物理メモリページが使用できないか、MDL 構造体を割り当てるために十分なメモリプールがないことを示します。

ルーチンが要求されたメモリの一部 (すべてではない) を正常に割り当てた場合、MDL は、ルーチンが割り当てることができたのと同じ量の物理メモリを記述します。

注釈

非均一メモリアクセス (NUMA) マルチプロセッサシステムでは、呼び出し元は、メモリの割り当て元となる理想的なノードを指定できます。ノードは、メモリの領域への高速アクセスを共有するプロセッサのコレクションです。 NUMA 以外のマルチプロセッサまたは単一プロセッサシステムでは、 MmAllocateNodePagesForMdlEx は、すべてのメモリを 1 つのノードに属するものとして扱い、このノードからメモリを割り当てます。

既定では、 MmAllocateNodePagesForMdlEx が返す物理メモリページは連続したページではありません。呼び出し元は、 Flags パラメーターにMM_ALLOCATE_PREFER_CONTIGUOUSまたはMM_ALLOCATE_REQUIRE_CONTIGUOUS_CHUNKSフラグビットを設定することで、このルーチンの既定の動作をオーバーライドできます。

MmAllocateNodePagesForMdlEx は、割り当てられた物理メモリを仮想メモリにマップしません。必要に応じて、呼び出し元は MmMapLockedPagesSpecifyCache などのルーチンを呼び出して、MDL によって記述された物理メモリページをマップできます。

MmAllocateNodePagesForMdlEx は、対応する仮想アドレスを必要としないカーネルモードドライバー (つまり、物理ページを必要とせず、物理的に連続している必要はありません) と、デバイスの物理メモリが特定の物理アドレス範囲 (たとえば、AGP グラフィックスカード) に割り当てられている場合に大幅なパフォーマンス向上を実現できるカーネルモードドライバー用に設計されています。

要求された範囲で現在使用できる物理メモリの量に応じて、 MmAllocateNodePagesForMdlEx は、要求されたメモリよりも少ないメモリを記述する MDL を返す場合があります。また、メモリが割り当てられていない場合、ルーチンは NULL を 返す場合もあります。呼び出し元は、MDL で説明されているように、実際に割り当てられるメモリの量をチェックする必要があります。

呼び出し元は MmFreePagesFromMdl を使用して、 MmAllocateNodePagesForMdlEx によって作成された MDL によって記述されたメモリページを解放する必要があります。 MmFreePagesFromMdl を呼び出した後、呼び出し元は ExFreePool を呼び出して、MDL 構造体に割り当てられたメモリを解放する必要もあります。

既定では、 MmAllocateNodePagesForMdlEx は割り当てるページに 0 を設定します。呼び出し元は、MM_DONT_ZERO_ALLOCATION フラグを指定して、この既定値をオーバーライドし、パフォーマンスを向上させることができます。

MM_DONT_ZERO_ALLOCATION フラグを指定した場合、 MmAllocateNodePagesForMdlEx によって 割り当てられるメモリは初期化されません。ドライバーがユーザーモードソフトウェアにメモリを表示する場合 (特権の可能性のあるコンテンツのリークを回避するため) カーネルモードドライバーは、最初にこのメモリをゼロにする必要があります。このフラグの詳細については、「 MM_ALLOCATE_XXX」を参照してください。

MmAllocateNodePagesForMdlEx が 1 回の呼び出しで割り当てることができる最大メモリ量は (4 ギガバイト - PAGE_SIZE) です。ルーチンは、十分なページが使用可能な場合にのみ、この量の割り当て要求を満たすことができます。

MmAllocateNodePagesForMdlEx は IRQL <= APC_LEVELで実行されます。必要に応じて、ドライバーは 、DISPATCH_LEVELで MmAllocateNodePagesForMdlEx を呼び出すことができます。ただし、APC_LEVEL 以下でを呼び出すことで、ドライバーのパフォーマンスを向上させることができます。

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (「解説」セクションを参照)。