ExInitializePagedLo一sideList 函式 (wdm.h)

發行項
02/27/2024

ExInitializePagedLo一sideList 例程會針對指定大小的可分頁專案初始化 lookaside 清單。

語法

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結構的指標。呼叫端必須針對結構使用非分頁系統空間，即使此 lookaside 清單中的專案會從可分頁記憶體配置。在64位平臺上，此結構必須對齊16位元組。

[in, optional] Allocate

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

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

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

[in, optional] Free

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

VOID XxxFree(
  __in PVOID  Buffer
);

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

[in] Flags

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

旗標位	意義
POOL_RAISE_IF_ALLOCATION_FAILURE	如果配置失敗，請引發例外狀況。

指定POOL_NX_ALLOCATION旗標沒有任何作用。所有可分頁記憶體都會配置為 NX。

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

[in] Size

指定 lookaside 列表中每個專案的大小，以位元組為單位。

[in] Tag

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

[in] Depth

保留的。必須為零。

傳回值

無

備註

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

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

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

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

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

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

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

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

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

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 IrqlExApcLte2 (wdm)