ExInitializeNPagedLo一sideList 函式 (wdm.h)

發行項
02/27/2024

ExInitializeNPagedLo一sideList 例程會初始化指定大小的非分頁項目外觀清單。

語法

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

當 lookaside 清單是空的或 NULL 時，用於配置專案之呼叫端提供的函式指標。如果為非 NULL，則指標是具有原型的函式：

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

如果 Allocate 參數為 NULL，則每當 lookaside 列表是空的時，對 ExAllocateFromNPagedLo可sideList 的後續呼叫會自動配置專案。

[in, optional] Free

每當 lookaside 列表已滿或 NULL 時，可釋放專案之呼叫端提供的函式指標。如果為非 NULL，則指標是具有原型的函式：

VOID XxxFree(
  __in PVOID  Buffer
);

如果 Free 參數為 NULL，則每當清單已滿時，對 ExFreeToNPagedLo一sideList 的後續呼叫會自動將指定的專案釋放回非分頁集區，也就是說，目前保存系統決定的專案數目上限。

[in] Flags

從 Windows 8 開始，此參數會指定選擇性旗標值，以修改 ExInitializeNPagedLo一sideList 例程的預設行為。相容的旗標位包括下列專案。

旗標位	意義	值
POOL_RAISE_IF_ALLOCATION_FAILURE	如果配置失敗，請引發例外狀況。	16
POOL_NX_ALLOCATION	配置非可執行記憶體。	512

在 Windows 8 之前，不會使用此參數，而且必須是零。

[in] Size

指定後續要配置之每個非分頁專案的大小，以位元組為單位。此參數不得小於 Wdm.h 頭檔中定義的所需最小大小LOOKASIDE_MINIMUM_BLOCK_SIZE。

[in] Tag

指定配置外觀清單專案時要使用的集區標籤。如需集區卷標的詳細資訊，請參閱 ExAllocatePoolWithTag 的 Tag 參數。

[in] Depth

保留的。必須為零。

傳回值

無

備註

呼叫 ExInitializeNPagedLo一sideList 之後，可以分別配置呼叫者指定 Size 的記憶體區塊，並釋放至 lookaside 清單，並分別呼叫 ExAllocateFromNPagedLo可sideList 和 ExFreeToNPagedLo一sideList。這類動態配置和釋放的專案可以是呼叫端在執行時使用的任何數據結構或固定大小緩衝區，特別是當呼叫端無法預先決定在任何指定時間使用多少這類專案時。每個固定大小專案的版面配置和內容都是呼叫端所決定。

ExInitializeNPagedLo一sideList 會初始化系統狀態，以追蹤指定 lookaside 列表的使用方式，如下所示：

零初始化要針對項目維護的計數器。
儲存呼叫端提供的 XxxAllocate 和 XxxFree 例程的進入點，如果有的話，或分別將這些進入點設定為 ExAllocatePoolWithTag 和 ExFreePool。
視需要，初始化系統微調鎖定，以多處理器安全的方式控制配置，並釋放至 lookaside 清單。
儲存呼叫端提供的專案 Size 和 list Tag。
設定系統決定的限制 (在 lookaside 清單中保留的項目數目下限和上限) ，如果專案的全系統需求高於或低於預期，則可以後續進行調整。
設定系統決定的旗標，控制後續將配置專案的記憶體類型。

系統會維護一組目前使用中的所有外觀清單。當查詢清單專案和可用的非分頁記憶體需求在系統執行時有所不同時，系統會調整其限制，以動態方式在每個非分頁的 lookaside 清單中保留的項目數目。

驅動程式在卸除之前，必須一律明確釋放它們建立的任何外觀清單。否則為嚴重的程式設計錯誤。使用 ExDeleteNPagedLo以sideList 釋放清單。

ExInitializeNPagedLo一sideList 會在呼叫端提供的位置設定不透明的清單前端，但預先配置清單項目沒有記憶體。接著，初始專案會以動態方式配置為 對 ExAllocateFromNPagedLo可sideList 的呼叫，而且這些初始專案會保留於 lookaside 列表中，做為 ExFreeToNPagedLomountsideList 的相互呼叫。專案會收集在指定的 lookaside 清單中，直到達到系統決定的最大值為止，其中任何其他專案會在釋放時傳回至非分頁集區。如果清單變成空白，則配置要求會由清單初始化或 ExAllocatePoolWithTag 所指定的 XxxAllocate 函式滿足。

每當 Lookaside 列表的使用者執行配置和釋放固定大小專案時，傳遞 ExInitializeNPagedLo可sideList 之 Allocate 和 Free 參數的 NULL 指標會更有效率。不過，任何使用 lookaside 清單的元件都可能會提供這些函式來執行其他呼叫端決定的處理，例如藉由維護其配置和釋放專案數目的狀態來追蹤自己的易失記憶體使用量。

如果 ExInitializeNPagedLo一sideList 的呼叫端提供 XxxAllocate 函式，該例程必須在呼叫 ExAllocatePoolWithTag 時，使用指定的輸入參數來配置 lookaside 列表的專案。

從 Windows Vista 開始，類似的例程 ExInitializeLo一層ListEx 會初始化 LOOKASIDE_LIST_EX 結構所描述的 lookaside 列表。不同於使用NPAGED_LOOKASIDE_LIST結構的 lookaside 清單的 XxxAllocate 和 XxxFree 例程，使用LOOKASIDE_LIST_EX結構之 lookaside 清單的配置和解除分配例程會接收內容指標做為輸入參數。這些例程可以使用此內容來儲存 lookaside 清單的私人數據。如果您的驅動程式只打算在 Windows Vista 和更新版本的 Windows 中執行，請考慮使用 ExInitializeLo可sideListEx ，而不是 ExInitializeNPagedLo一sideList。如需詳細資訊，請參閱使用 Lookaside 清單。

ExInitializeNPagedLo一sideList 的呼叫端可以在 IRQL = DISPATCH_LEVEL執行，但通常會在 IRQL <= PASSIVE_LEVEL執行。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (请参阅一节)