ExAllocatePoolWithTag-Funktion (wdm.h)
Die ExAllocatePoolWithTag Routine weist den Poolspeicher des angegebenen Typs zu und gibt einen Zeiger auf den zugewiesenen Block zurück.
Warnung
ExAllocatePoolWithTag ist in Windows 10, Version 2004, veraltet und wurde durch ExAllocatePool2ersetzt. Weitere Informationen finden Sie unter Aktualisieren veralteter ExAllocatePool-Aufrufe an ExAllocatePool2 und ExAllocatePool3.
Syntax
PVOID ExAllocatePoolWithTag(
[in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag
);
Parameter
[in] PoolType
Der Typ des zuzuweisenden Poolspeichers. Eine Beschreibung der verfügbaren Poolspeichertypen finden Sie unter POOL_TYPE.
Sie können den PoolType-wert durch Bitweise-ORing diesen Wert mit dem POOL_RAISE_IF_ALLOCATION_FAILURE Flag ändern. Dieses Flag bewirkt, dass eine Ausnahme ausgelöst wird, wenn die Anforderung nicht erfüllt werden kann. Die Verwendung der POOL_RAISE_IF_ALLOCATION_FAILURE Kennzeichnung wird nicht empfohlen, da sie teuer ist.
Ebenso können Sie den PoolType-wert durch Bitweise-ORing diesen Wert mit dem POOL_COLD_ALLOCATION Flag als Hinweis auf den Kernel ändern, um den Speicher von Seiten zuzuweisen, die wahrscheinlich schnell ausgelagert werden. Um den Speicher des residenten Pools so weit wie möglich zu reduzieren, sollten Sie nicht häufig auf diese Zuordnungen verweisen. Das POOL_COLD_ALLOCATION Flag ist nur eine Empfehlung.
[in] NumberOfBytes
Die Anzahl der zuzuordnenden Bytes.
[in] Tag
Das Pooltag, das für den zugewiesenen Speicher verwendet werden soll. Geben Sie das Pooltag als Nicht-Null-Zeichenliteral von ein bis vier Zeichen an, die durch einfache Anführungszeichen (z. B. "Tag1") getrennt sind. Die Zeichenfolge wird in der Regel in umgekehrter Reihenfolge angegeben (z. B. "1gaT"). Jedes ASCII-Zeichen im Tag muss ein Wert im Bereich 0x20 (Leerzeichen) sein, um 0x7E (Tilde) zu 0x7E. Jeder Zuordnungscodepfad sollte ein eindeutiges Pooltag verwenden, um Debuggern und Prüfern bei der Identifizierung des Codepfads zu helfen.
Rückgabewert
ExAllocatePoolWithTag gibt NULL- zurück, wenn im freien Pool nicht genügend Arbeitsspeicher vorhanden ist, um die Anforderung zu erfüllen. Andernfalls gibt die Routine einen Zeiger auf den zugewiesenen Speicher zurück.
Bemerkungen
Diese Routine wird für die allgemeine Poolzuordnung des Arbeitsspeichers verwendet.
Wenn NumberOfBytes- PAGE_SIZE oder höher ist, wird ein Seitenausrichtungspuffer zugewiesen. Speicherzuordnungen von PAGE_SIZE oder weniger werden innerhalb einer Seite zugewiesen und überschreiten keine Seitengrenzen. Speicherzuordnungen von weniger als PAGE_SIZE sind nicht notwendigerweise seitenbündig ausgerichtet, werden aber in 32-Bit-Systemen und 16-Byte-Begrenzungen in 64-Bit-Systemen ausgerichtet.
Eine erfolgreiche Zuordnung, die NumberOfBytes-< PAGE_SIZE des nichtpageten Pools anfordert, gibt dem Anrufer genau die Anzahl der angeforderten Bytes an Arbeitsspeicher. Wenn eine Zuordnungsanforderung für NumberOfBytes> PAGE_SIZE erfolgreich ist und NumberOfBytes- kein genaues Vielfaches von PAGE_SIZE ist, enthält die letzte Seite in der Zuordnung Bytes, die nicht Teil der Zuordnung des Anrufers sind. Wenn möglich, verwendet der Pool-Allocator diese Bytes. Um beschädigte Daten zu vermeiden, die zu anderen Kernelmoduskomponenten gehören, müssen Treiber nur auf Speicheradressen zugreifen, die sie explizit zugewiesen haben.
Das System ordnet das Pooltag dem zugeordneten Speicher zu. Programmiertools, z. B. WinDbg, können das Pooltag anzeigen, das jedem zugeordneten Puffer zugeordnet ist. Gflags, ein Tool, das in Debugtools für Windowsenthalten ist, aktiviert ein Systemfeature, das die Zuordnung von speziellen Pool- für ein bestimmtes Pooltag anfordert. Poolmon-, das im WDK enthalten ist, verfolgt den Speicher nach Pooltag.
Der Wert Tag- wird gespeichert und manchmal in umgekehrter Reihenfolge (little-endian) angezeigt. Wenn ein Aufrufer beispielsweise "Fred" als Tagübergibt, wird er als "derF" in einem Poolabbild und in der Poolnutzungsnachverfolgung im Debugger angezeigt, und wie 0x64657246 in der Registrierung und im Tool angezeigt wird.
Der zugeordnete Puffer kann entweder mit ExFreePool oder ExFreePoolWithTagfreigegeben werden.
Das System legt automatisch bestimmte Standardereignisobjekte fest, wenn die Menge des Pools (ausgelagert oder nicht ausgelagert) hoch oder niedrig ist. Treiber können warten, bis diese Ereignisse ihre Poolnutzung optimieren. Weitere Informationen finden Sie unter Standard-Ereignisobjekte.
Aufrufer von ExAllocatePoolWithTag- müssen bei IRQL-<= DISPATCH_LEVEL ausgeführt werden. Ein Aufrufer, der bei DISPATCH_LEVEL ausgeführt wird, muss einen NonPaged-Xxx- wert für PoolType-angeben. Ein Aufrufer, der bei IRQL <= APC_LEVEL ausgeführt wird, kann einen beliebigen POOL_TYPE Wert angeben, aber die IRQL und Umgebung müssen auch zum Bestimmen des Seitentyps berücksichtigt werden.
Legen Sie NumberOfBytes- = 0 nicht fest. Vermeiden Sie Zuweisungen der Länge Null, da sie Platz für den Poolkopf verschwenden und in vielen Fällen ein potenzielles Überprüfungsproblem im aufrufenden Code angeben. Aus diesem Grund Driver Verifier solche Zuordnungen als mögliche Fehler kennzeichnen.
In einer nicht uniform memory access (NUMA)-Multiprozessorarchitektur versucht ExAllocatePoolWithTag Speicher zuzuweisen, der lokal für den Prozessor ist, der ExAllocatePoolWithTagaufruft. Wenn kein lokaler Speicher verfügbar ist, weist ExAllocatePoolWithTag den nächstgelegenen verfügbaren Speicher zu.
Speicher, der ExAllocatePoolWithTag zugewiesen wird, wird nicht initialisiert. Ein Kernelmodustreiber muss zuerst diesen Speicher null sein, wenn er für Software im Benutzermodus sichtbar macht (um zu vermeiden, dass potenziell privilegierte Inhalte verloren gehen).
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | IRQL-<= DISPATCH_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |