ExAllocatePool2-Funktion (wdm.h)
Die ExAllocatePool2 Routine weist den Poolspeicher des angegebenen Typs zu und gibt einen Zeiger auf den zugewiesenen Block zurück.
Syntax
DECLSPEC_RESTRICT PVOID ExAllocatePool2(
POOL_FLAGS Flags,
SIZE_T NumberOfBytes,
ULONG Tag
);
Parameter
Flags
Ein ULONG64 typisierter Wert, der den Typ des Poolspeichers zusammen mit erforderlichen und optionalen Attributen angibt. Mehrere Kennzeichenwerte können mit Bitweise ODER kombiniert werden. Mögliche Werte finden Sie unter POOL_FLAGS.
NumberOfBytes
Gibt eine Nicht-Null-Anzahl von Bytes an, die zugewiesen werden sollen.
Tag
Das Pooltag, das für den zugewiesenen Speicher verwendet werden soll. Geben Sie das Pooltag als Nicht-Null-Zeichenliteral von 1 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
ExAllocatePool2 gibt einen Zeiger auf den zugewiesenen Speicher zurück.
Die folgenden Bedingungen führen dazu, dass die Funktion STANDARDMÄßIG NULL zurückgibt. Wenn POOL_FLAG_RAISE_ON_FAILURE angegeben ist, löst die Funktion eine Ausnahme aus.
- Nicht genügend Arbeitsspeicher
- Tag- auf 0 oder ungültige POOL_FLAGS festgelegt ist, werden angegeben.
Bemerkungen
Wenn Sie einen Treiber erstellen, der auf Windows-Versionen vor Windows 10, Version 2004 ausgerichtet ist, verwenden Sie ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZerooder ExAllocatePoolQuotaUninitialized.
Diese Routine weist die folgenden Unterschiede von den früheren Zuordnungsroutinen auf (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):
Der Arbeitsspeicher ist null initialisiert, es sei denn, POOL_FLAG_UNINITIALIZED ist angegeben.
Rückgabeverhalten im Falle einer nicht erfolgreichen Zuordnung. ExAllocatePoolWithQuotaTag löst standardmäßig eine Ausnahme aus.
Tags mit dem Wert 0 sind ungültig.
Wenn Sie ExAllocatePoolWithQuotaTag durch ExAllocatePool2ersetzen, müssen Sie das POOL_FLAG_USE_QUOTA-Flag angeben. Weitere Informationen zu Poolkennzeichnungen finden Sie unter POOL_FLAGS.
Wenn NumberOfBytes-PAGE_SIZE oder höher ist, wird ein seitenbündiges Puffer zugewiesen. Speicherzuweisungen 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.
Treiber dürfen nur bis zu den NumberOfBytes-, die sie explizit zugewiesen haben, verwenden. Der Zugriff auf den Arbeitsspeicher außerhalb dieses Bereichs kann den Pool beschädigen und dazu führen, dass das System abstürzt.
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 Windows enthalten ist, aktiviert ein Systemfeature, das die Zuordnung von einem speziellen Pool für ein bestimmtes Pooltag anfordert. Poolmon, das im WDK enthalten ist, verfolgt den Speicher nach Pooltag nach.
Der Wert von Tag wird gespeichert und manchmal in umgekehrter Reihenfolge (little-endian) angezeigt. Wenn ein Aufrufer z. B. Fred als Tag übergibt, wird er als derF in einem Poolabbild und in der Poolnutzungsnachverfolgung im Debugger und als 0x64657246 in der Registrierung und im Tool angezeigt.
Der zugeordnete Puffer kann entweder mit ExFreePool oder ExFreePoolWithTagfreigegeben werden.
Aufrufer von ExAllocatePool2- müssen unter IRQL-<= DISPATCH_LEVEL ausgeführt werden. Ein Aufrufer, der bei DISPATCH_LEVEL ausgeführt wird, muss POOL_FLAG_NON_PAGED oder POOL_FLAG_NON_PAGED_EXECUTABLE für Flagsangeben. Ein Aufrufer, der bei IRQL <= APC_LEVEL ausgeführt wird, kann POOL_FLAG_PAGEDangeben. Wenn auf den Speicher jedoch über code zugegriffen wird, der bei DISPATCH_LEVEL ausgeführt wird, müssen Sie trotzdem nicht ausgelagerten Speicher zuweisen.
In einer nicht uniform memory access (NUMA)-Multiprozessorarchitektur ExAllocatePool2 versucht, dem Prozessor, der ExAllocatePool2aufruft, Speicher lokal zuzuweisen. Wenn kein lokaler Speicher verfügbar ist, weist ExAllocatePool2 den nächstgelegenen verfügbaren Speicher zu.
Speicher, der ExAllocatePool2 zugewiesen wird, ist null initialisiert. Kernelmodustreiber sollten keine Nullen für Zuordnungen deaktivieren, die an einen nicht vertrauenswürdigen Speicherort kopiert werden (Benutzermodus, über das Netzwerk usw.), um vertrauliche Informationen nicht offenzulegen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 10, Version 2004 |
| 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 | HwStorPortProhibitedDIs, SpNoWait, StorPortStartIo |