ExInitializePagedLookasideList-Funktion (wdm.h)

Artikel
03/08/2023

Die ExInitializePagedLookasideList-Routine initialisiert eine Lookaside-Liste für auslagerungsfähige Einträge der angegebenen Größe.

Syntax

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
);

Parameter

[out] Lookaside

Ein Zeiger auf die zu initialisierende PAGED_LOOKASIDE_LIST-Struktur. Der Aufrufer muss den nicht ausgelagerten Systembereich für die Struktur verwenden, obwohl die Einträge in dieser Lookaside-Liste aus dem ausgelagerten Speicher zugeordnet werden. Auf 64-Bit-Plattformen muss diese Struktur 16-Byte ausgerichtet sein.

[in, optional] Allocate

Ein Zeiger auf eine vom Aufrufer bereitgestellte Funktion zum Zuweisen eines Eintrags, wenn die Suchliste leer ist, oder auf NULL. Wenn nicht NULL, lautet der Zeiger auf eine Funktion mit dem Prototyp:

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

Wenn der Allocate-ParameterNULL ist, werden bei nachfolgenden Aufrufen von ExAllocateFromPagedLookasideList automatisch Einträge zugeordnet, wenn die Suchliste leer ist.

[in, optional] Free

Ein Zeiger auf eine vom Aufrufer bereitgestellte Funktion zum Freigeben eines Eintrags, wenn die Suchliste voll ist, oder auf NULL. Wenn nicht NULL, lautet der Zeiger auf eine Funktion mit dem Prototyp:

VOID XxxFree(
  __in PVOID  Buffer
);

Wenn der Free-ParameterNULL ist, geben nachfolgende Aufrufe von ExFreeToPagedLookasideList den angegebenen Eintrag automatisch wieder an den Auslagerungspool frei, wenn die Liste voll ist, d. h. derzeit die vom System festgelegte maximale Anzahl von Einträgen.

[in] Flags

Ab Windows 8 gibt dieser Parameter einen optionalen Flagwert an, um das Standardverhalten der ExInitializePagedLookasideList-Routine zu ändern. Kompatible Flagbits umfassen Folgendes.

Flag-Bit	Bedeutung
POOL_RAISE_IF_ALLOCATION_FAILURE	Wenn die Zuordnung fehlschlägt, lösen Sie eine Ausnahme aus.

Das Angeben des POOL_NX_ALLOCATION-Flags hat keine Auswirkung. Der gesamte ausgelagerte Arbeitsspeicher wird als NX zugeordnet.

Vor Windows 8 wird dieser Parameter nicht verwendet und muss null sein.

[in] Size

Gibt die Größe der einzelnen Einträge in der Suchliste in Byte an.

[in] Tag

Gibt das Pooltag an, das beim Zuweisen von Suchlisteneinträgen verwendet werden soll. Weitere Informationen zu Pooltags finden Sie im Tag-Parameter von ExAllocatePoolWithTag.

[in] Depth

Reserviert. Muss Null sein.

Rückgabewert

Keine

Bemerkungen

Nach dem Aufruf von ExInitializePagedLookasideList können Blöcke der vom Aufrufer angegebenen Größe von zugeordnet und der Lookaside-Liste mit Aufrufen von ExAllocateFromPagedLookasideList bzw . ExFreeToPagedLookasideList freigegeben werden. Bei solchen dynamisch zugeordneten und freigegebenen Einträgen kann es sich um eine beliebige Datenstruktur oder einen Puffer mit fester Größe handelt, die der Aufrufer während der Systemausführung verwendet, insbesondere wenn der Aufrufer nicht vordefinieren kann, wie viele solche Einträge zu einem bestimmten Zeitpunkt verwendet werden. Das Layout und der Inhalt jedes Eintrags mit fester Größe werden vom Aufrufer bestimmt.

ExInitializePagedLookasideList initialisiert den Systemzustand, um die Verwendung der angegebenen Lookaside-Liste wie folgt nachzuverfolgen:

Null initialisiert die Indikatoren, die für Einträge verwaltet werden sollen.
Speichert die Einstiegspunkte der vom Aufrufer bereitgestellten XxxAllocate - und XxxFree-Routinen , falls vorhanden, oder legt diese Einstiegspunkte auf ExAllocatePoolWithTag bzw . ExFreePool fest.
Initialisiert eine Systemdrehsperre, um Zuordnungen von zu steuern, und gibt die Suchliste bei Bedarf auf multiprozessorsichere Weise frei.
Speichert den vom Aufrufer bereitgestellten Eintrag Größe und Listentag.
Legt die vom System festgelegten Grenzwerte (Minimum und Maximum) für die Anzahl der Einträge in der Suchliste fest, die nachträglich angepasst werden können, wenn die systemweite Nachfrage nach Einträgen höher oder niedriger als erwartet ist.
Richtet die vom System festgelegten Flags ein, die den Typ des Arbeitsspeichers steuern, aus dem einträge anschließend zugeordnet werden.

Das System verwaltet einen Satz aller verwendeten Lookaside-Listen. Da die Nachfrage nach Suchlisteneinträgen und dem verfügbaren ausgelagerten Arbeitsspeicher während der Systemausführung variiert, passt das System seine Grenzwerte für die Anzahl der Einträge an, die in jeder ausgelagerten Lookaside-Liste gespeichert werden sollen, dynamisch an.

Treiber müssen immer explizit kostenlose Suchlisten verwenden, die sie vor dem Entladen erstellen. Andernfalls handelt es sich um einen schwerwiegenden Programmierfehler. Verwenden Sie ExDeletePagedLookasideList , um die Liste frei zu geben.

ExInitializePagedLookasideList richtet den undurchsichtigen Listenkopf am vom Aufrufer bereitgestellten Speicherort ein, weist jedoch keinen Arbeitsspeicher für Listeneinträge vor. Anschließend werden die anfänglichen Einträge dynamisch zugeordnet, wenn Aufrufe von ExAllocateFromPagedLookasideList auftreten, und diese anfänglichen Einträge werden in der Lookaside-Liste gespeichert, wenn wechselseitige Aufrufe von ExFreeToPagedLookasideList auftreten. Einträge werden in der angegebenen Lookaside-Liste gesammelt, bis das vom System festgelegte Maximum erreicht ist, wobei alle zusätzlichen Einträge an den ausgelagerten Pool zurückgegeben werden, während sie freigegeben werden. Wenn die Liste leer wird, werden Zuordnungsanforderungen durch die bei der Listeninitialisierung angegebene XxxAllocate-Funktion oder durch ExAllocatePoolWithTag erfüllt.

Es ist effizienter , NULL-Zeiger für die Parameter Allocate und Free von ExInitializePagedLookasideList zu übergeben, wenn der Benutzer einer Lookaside-Liste nichts anderes tut, als Einträge mit fester Größe zuzuordnen und freizugeben. Jede Komponente, die eine Lookaside-Liste verwendet, kann diese Funktionen jedoch bereitstellen, um zusätzliche vom Aufrufer bestimmte Verarbeitung durchzuführen, z. B. die Nachverfolgung ihrer eigenen dynamischen Speicherauslastung, indem der Zustand über die Anzahl der Einträge beibehalten wird, die zugewiesen und freigegeben werden.

Wenn der Aufrufer von ExInitializePagedLookasideList eine XxxAllocate-Funktion bereitstellt, muss diese Funktion Einträge für die Lookaside-Liste mithilfe der angegebenen Eingabeparameter zuordnen, wenn exAllocatePoolWithTag aufgerufen wird.

Ab Windows Vista initialisiert eine ähnliche Routine, ExInitializeLookasideListEx, eine Lookaside-Liste, die durch eine LOOKASIDE_LIST_EX-Struktur beschrieben wird. Im Gegensatz zu den XxxAllocate - und XxxFree-Routinen für eine Lookaside-Liste, die eine PAGED_LOOKASIDE_LIST-Struktur verwendet, erhalten die Zuordnungs- und Aufhebungsroutinen für eine Suchliste, die die LOOKASIDE_LIST_EX Struktur verwendet, einen Kontextzeiger als Eingabeparameter. Diese Routinen können diesen Kontext verwenden, um private Daten für die Suchliste zu speichern. Wenn Ihr Treiber nur in Windows Vista und höheren Versionen von Windows ausgeführt werden soll, sollten Sie exInitializeLookasideListEx anstelle von ExInitializePagedLookasideList verwenden. Weitere Informationen finden Sie unter Verwenden von Lookaside Listen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)