ExInitializeNPagedLookasideList 関数 (wdm.h)

[アーティクル]
03/08/2023

ExInitializeNPagedLookasideList ルーチンは、指定したサイズの非ページエントリのルックアサイドリストを初期化します。

構文

void ExInitializeNPagedLookasideList(
  [out]          PNPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION     Allocate,
  [in, optional] PFREE_FUNCTION         Free,
  [in]           ULONG                  Flags,
  [in]           SIZE_T                 Size,
  [in]           ULONG                  Tag,
  [in]           USHORT                 Depth
);

パラメーター

[out] Lookaside

初期化する NPAGED_LOOKASIDE_LIST 構造体へのポインター。呼び出し元は、構造体に非ページ・システム・スペースを使用する必要があります。 64 ビットプラットフォームでは、この構造体は 16 バイトアラインされている必要があります。

[in, optional] Allocate

ルックアサイドリストが空の場合にエントリを割り当てる呼び出し元が指定した関数へのポインター、または NULL へのポインター。 NULL 以外の場合、ポインターはプロトタイプを持つ関数に対します。

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // NonPagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Allocate パラメーターが NULL の場合、その後 ExAllocateFromNPagedLookasideList を呼び出すと、ルックアサイドリストが空の場合は常にエントリが自動的に割り当てられます。

[in, optional] Free

ルックアサイドリストがいっぱいになったときにエントリを解放するための呼び出し元が指定した関数へのポインター、または NULL へのポインター。 NULL 以外の場合、ポインターはプロトタイプを持つ関数に対します。

VOID XxxFree(
  __in PVOID  Buffer
);

Free パラメーターが NULL の場合、その後 ExFreeToNPagedLookasideList を呼び出すと、リストがいっぱいになると、指定されたエントリが非ページプールに自動的に解放されます。つまり、現在、システムによって決定されたエントリの最大数が保持されています。

[in] Flags

Windows 8以降、このパラメーターは省略可能なフラグ値を指定して、ExInitializeNPagedLookasideList ルーチンの既定の動作を変更します。互換性のあるフラグビットには、次のものが含まれます。

フラグビット	説明	[値]
POOL_RAISE_IF_ALLOCATION_FAILURE	割り当てが失敗した場合は、例外を発生させます。	16
POOL_NX_ALLOCATION	実行可能でないメモリを割り当てます。	512

Windows 8する前に、このパラメーターは使用されず、0 である必要があります。

[in] Size

後続に割り当てる非ページエントリのサイズをバイト単位で指定します。このパラメーターは、Wdm.h ヘッダーファイルで定義されている必要な最小サイズ (LOOKASIDE_MINIMUM_BLOCK_SIZE) より小さくすることはできません。

[in] Tag

ルックアサイドリストエントリを割り当てるときに使用するプールタグを指定します。プールタグの詳細については、ExAllocatePoolWithTag の Tag パラメーターを参照してください。

[in] Depth

予約済み。ゼロを指定してください。

戻り値

なし

解説

ExInitializeNPagedLookasideList を呼び出した後、呼び出し元が指定した Size のメモリブロックをそれぞれ ExAllocateFromNPagedLookasideList と ExFreeToNPagedLookasideList の呼び出しでルックアサイドリストに割り当て、解放できます。このような動的に割り当てられたエントリと解放されたエントリは、システムの実行中に呼び出し元が使用する任意のデータ構造または固定サイズのバッファーにすることができます。特に、呼び出し元が特定の時点で使用されるエントリの数を事前に決定できない場合です。固定サイズの各エントリのレイアウトと内容は、呼び出し元によって決定されます。

ExInitializeNPagedLookasideList は、次のように、指定されたルックアサイドリストの使用状況を追跡するためにシステム状態を初期化します。

エントリに対して保持するカウンターを 0 で初期化します。
呼び出し元が指定した XxxAllocate ルーチンと XxxFree ルーチンのエントリポイント (存在する場合) を格納するか、これらのエントリポイントをそれぞれ ExAllocatePoolWithTag および ExFreePool に設定します。
システムスピンロックを初期化して、必要に応じてマルチプロセッサセーフな方法でルックアサイドリストからの割り当てを制御し、そのリストを解放します。
呼び出し元が指定したエントリ のサイズ とリストタグを格納 します。
ルックアサイドリストに保持するエントリの数に対してシステムによって決定された制限 (最小と最大) を設定します。この制限は、システム全体のエントリの需要が予想よりも高いか低い場合に、後で調整できます。
システムによって決定されるフラグを設定します。このフラグは、エントリの割り当て元となるメモリの種類を制御します。

システムは、現在使用中のすべてのルックアサイドリストのセットを保持します。システムの実行中にルックアサイドリストエントリと使用可能な非ページメモリに対する需要が異なるため、システムは、各非ページルックアサイドリストに保持されるエントリの数の制限を動的に調整します。

ドライバーは、アンロードする前に作成したルックアサイドリストを常に明示的に解放する必要があります。それ以外の場合は、重大なプログラミングエラーです。リストを解放するには、 ExDeleteNPagedLookasideList を使用します。

ExInitializeNPagedLookasideList は、呼び出し元が指定した場所に不透明なリストヘッドを設定しますが、リストエントリのメモリは事前に割り当てされません。その後、 ExAllocateFromNPagedLookasideList の呼び出しが発生すると、初期エントリが動的に割り当てられ、 ExFreeToNPagedLookasideList への相互呼び出しが行われると、これらの初期エントリはルックアサイドリストに保持されます。エントリは、システムによって決定された最大値に達するまで、指定されたルックアサイドリストで収集されます。その後、解放されると、追加のエントリが非ページプールに返されます。リストが空になった場合、割り当て要求は、リストの初期化時に指定された XxxAllocate 関数または ExAllocatePoolWithTag によって満たされます。

ExInitializeNPagedLookasideList の Allocate パラメーターと Free パラメーターに NULL ポインターを渡す方が、ルックアサイドリストのユーザーが固定サイズエントリの割り当てと解放以外の処理を行わない場合は、より効率的です。ただし、ルックアサイドリストを使用するコンポーネントは、これらの関数を提供して、呼び出し元によって決定される追加の処理を実行できます。たとえば、割り当ておよび解放されるエントリの数に関する状態を維持することで、独自の動的メモリ使用量を追跡するなどです。

ExInitializeNPagedLookasideList の呼び出し元が XxxAllocate 関数を提供する場合、そのルーチンは ExAllocatePoolWithTag を呼び出すときに、指定された入力パラメーターを使用してルックアサイドリストのエントリを割り当てる必要があります。

同様のルーチンである Windows Vista 以降、 ExInitializeLookasideListEx は、 LOOKASIDE_LIST_EX 構造体によって記述されるルックアサイドリストを初期化します。 NPAGED_LOOKASIDE_LIST構造体を使用するルックアサイドリストの XxxAllocate ルーチンと XxxFree ルーチンとは異なり、LOOKASIDE_LIST_EX構造体を使用するルックアサイドリストの割り当ておよび割り当て解除ルーチンは、入力パラメーターとしてコンテキストポインターを受け取ります。これらのルーチンは、このコンテキストを使用して、ルックアサイドリストのプライベートデータを格納できます。ドライバーが Windows Vista 以降のバージョンの Windows でのみ実行することを目的としている場合は、ExInitializeNPagedLookasideList の代わりに ExInitializeLookasideListEx を使用することを検討してください。詳細については、「Lookaside Listsの使用」を参照してください。

ExInitializeNPagedLookasideList の呼び出し元は IRQL <= DISPATCH_LEVELで実行できますが、通常は IRQL = PASSIVE_LEVELで実行されます。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (「解説」セクションを参照)