ExInitializeNPagedLookasideList-Funktion (wdm.h)
Die ExInitializeNPagedLookasideList-Routine initialisiert eine Suchliste für nicht ausseitige Einträge der angegebenen Größe.
Syntax
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
);
Parameter
[out] Lookaside
Ein Zeiger auf die zu initialisierende NPAGED_LOOKASIDE_LIST Struktur. Der Aufrufer muss nicht ausseitigen Systemraum für die Struktur verwenden. 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 ist, ist der Zeiger auf eine Funktion mit dem Prototyp:
PVOID XxxAllocate(
__in POOL_TYPE PoolType, // NonPagedPool
__in SIZE_T NumberOfBytes, // value of Size
__in ULONG Tag // value of Tag
);
Wenn der Parameter AllocateNULL ist, weisen nachfolgende Aufrufe von ExAllocateFromNPagedLookasideList Automatisch Einträge zu, 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 ist, ist der Zeiger auf eine Funktion mit dem Prototyp:
VOID XxxFree(
__in PVOID Buffer
);
Wenn der Free-Parameter NULL ist, werden nachfolgende Aufrufe von ExFreeToNPagedLookasideList automatisch an den angegebenen Eintrag freigegeben, sobald die Liste voll ist, d. h. derzeit die vom System festgelegte maximale Anzahl von Einträgen enthalten.
[in] Flags
Ab Windows 8 gibt dieser Parameter einen optionalen Flagwert an, um das Standardverhalten der ExInitializeNPagedLookasideList-Routine zu ändern. Zu den kompatiblen Flagbits zählen die folgenden.
| Flagbit | Bedeutung | Wert |
|---|---|---|
| POOL_RAISE_IF_ALLOCATION_FAILURE | Wenn die Zuordnung fehlschlägt, lösen Sie eine Ausnahme aus. | 16 |
| POOL_NX_ALLOCATION | Ordnen Sie nicht ausführbaren Arbeitsspeicher zu. | 512 |
Vor Windows 8 wird dieser Parameter nicht verwendet und muss null sein.
[in] Size
Gibt die Größe in Bytes für jeden nicht ausserseitigen Eintrag an, der anschließend zugeordnet werden soll. Dieser Parameter darf nicht kleiner als die erforderliche Mindestgröße sein, LOOKASIDE_MINIMUM_BLOCK_SIZE, die in der Wdm.h-Headerdatei definiert ist.
[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 ExInitializeNPagedLookasideList können Speicherblöcke der vom Aufrufer angegebenen Größe zugeordnet und der Lookaside-Liste mit Aufrufen von ExAllocateFromNPagedLookasideList bzw . ExFreeToNPagedLookasideList zugeordnet und der Lookaside-Liste freigegeben werden. Solche dynamisch zugeordneten und freigegebenen Einträge können jede Datenstruktur oder einen Puffer mit fester Größe sein, die der Aufrufer während der Systemausführung verwendet, insbesondere, wenn der Aufrufer nicht vorher bestimmen 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.
ExInitializeNPagedLookasideList initialisiert den Systemstatus, 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 System-Spinsperre, um Zuordnungen von zu steuern, und gibt die Suchliste bei Bedarf multiprozessorsicher 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 fest, die in der Suchliste gespeichert werden sollen, 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 bestimmten Flags ein, die den Speichertyp steuern, aus dem die Einträge anschließend zugeordnet werden.
Das System verwaltet einen Satz aller derzeit verwendeten Suchlisten. Da die Nachfrage nach Suchlisteneinträgen und dem verfügbaren nicht auslagerten Arbeitsspeicher während der Systemausführung variiert, passt das System seine Grenzwerte für die Anzahl der Einträge, die in jeder nicht auslagerten Suchliste gespeichert werden sollen, dynamisch an.
Treiber müssen alle von ihnen erstellten Suchlisten immer explizit freigeben, bevor sie entladen werden. Andernfalls handelt es sich um einen schwerwiegenden Programmierfehler. Verwenden Sie ExDeleteNPagedLookasideList , um die Liste frei zu geben.
ExInitializeNPagedLookasideList richtet den undurchsichtigen Listenkopf am vom Aufrufer bereitgestellten Speicherort ein, visiert jedoch keinen Arbeitsspeicher für Listeneinträge. Anschließend werden die anfänglichen Einträge dynamisch zugeordnet, wenn Aufrufe von ExAllocateFromNPagedLookasideList auftreten, und diese anfänglichen Einträge werden in der Lookaside-Liste gespeichert, da reziproke Aufrufe von ExFreeToNPagedLookasideList 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 nicht ausserseitigen 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 "Zuordnung" und "Frei " von ExInitializeNPagedLookasideList zu übergeben, wenn der Benutzer einer Suchliste nichts anderes tut, als Einträge mit fester Größe zuzuweisen und freizugeben. Jede Komponente, die eine Suchliste verwendet, kann jedoch diese Funktionen bereitstellen, um zusätzliche vom Aufrufer bestimmte Verarbeitung durchzuführen, z. B. die Nachverfolgung ihrer eigenen dynamischen Speichernutzung, indem der Zustand über die Anzahl von Einträgen beibehalten wird, die zugewiesen und freigegeben werden.
Wenn der Aufrufer von ExInitializeNPagedLookasideList eine XxxAllocate-Funktion bereitstellt, muss diese Routine Einträge für die Suchliste mithilfe der angegebenen Eingabeparameter zuordnen, wenn ExAllocatePoolWithTag aufgerufen wird.
Ab Windows Vista initialisiert eine ähnliche Routine, ExInitializeLookasideListEx, eine Suchliste, die durch eine LOOKASIDE_LIST_EX-Struktur beschrieben wird. Im Gegensatz zu den XxxAllocation - und XxxFree-Routinen für eine Suchliste, die eine NPAGED_LOOKASIDE_LIST-Struktur verwendet, erhalten die Zuordnungs- und Deallocationroutinen 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 ExInitializeNPagedLookasideList verwenden. Weitere Informationen finden Sie unter Verwenden von Lookaside Listen.
Aufrufer von ExInitializeNPagedLookasideList können unter IRQL <= DISPATCH_LEVEL ausgeführt werden, werden jedoch in der Regel unter IRQL = PASSIVE_LEVEL ausgeführt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (siehe Abschnitt Hinweise) |
Weitere Informationen
ExAllocateFromNPagedLookasideList