ExInitializePagedLookasideList 関数 (wdm.h)

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

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

構文

void ExInitializePagedLookasideList(
  [out]          PPAGED_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

初期化する PAGED_LOOKASIDE_LIST 構造体へのポインター。呼び出し元は、このルックアサイドリスト内のエントリがページング可能なメモリから割り当てられる場合でも、構造体に非ページシステム領域を使用する必要があります。 64 ビットプラットフォームでは、この構造体は 16 バイトアラインされている必要があります。

[in, optional] Allocate

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

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

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

[in, optional] Free

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

VOID XxxFree(
  __in PVOID  Buffer
);

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

[in] Flags

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

フラグビット	意味
POOL_RAISE_IF_ALLOCATION_FAILURE	割り当てが失敗した場合は、例外を発生させます。

POOL_NX_ALLOCATION フラグを指定しても効果はありません。ページング可能なメモリはすべて NX として割り当てられます。

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

[in] Size

ルックアサイドリスト内の各エントリのサイズをバイト単位で指定します。

[in] Tag

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

[in] Depth

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

戻り値

なし

解説

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

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

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

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

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

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

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

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

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

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)