ExAllocatePoolWithTag-Funktion (wdm.h)

  • Artikel

Die ExAllocatePoolWithTag-Routine weist Poolspeicher des angegebenen Typs zu und gibt einen Zeiger auf den zugeordneten Block zurück.

Warnung

ExAllocatePoolWithTag wurde in Windows 10 Version 2004 veraltet und durch ExAllocatePool2 ersetzt. Weitere Informationen finden Sie unter Aktualisieren veralteter ExAllocatePool-Aufrufe von 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 zuzuordnenden Poolarbeitsspeichers. Eine Beschreibung der verfügbaren Speichertypen des Pools finden Sie unter POOL_TYPE.

Sie können den PoolType-Wert ändern, indem Sie bitweise -ORingen Sie diesen Wert mit dem flag POOL_RAISE_IF_ALLOCATION_FAILURE. Dieses Flag bewirkt, dass eine Ausnahme ausgelöst wird, wenn die Anforderung nicht erfüllt werden kann. Die Verwendung des POOL_RAISE_IF_ALLOCATION_FAILURE-Flags wird nicht empfohlen, da es teuer ist.

Ebenso können Sie den PoolType-Wert ändern, indem Sie bitweise diesen Wert mit dem flag POOL_COLD_ALLOCATION als Hinweis an 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 flag POOL_COLD_ALLOCATION ist nur eine Empfehlung.

[in] NumberOfBytes

Die Anzahl der zu belegenden Bytes.

[in] Tag

Das Pooltag, das für den zugeordneten Arbeitsspeicher verwendet werden soll. Geben Sie das Pooltag als Zeichenliteral ungleich 0 von 0 bis vier Zeichen an, die durch einfache Anführungszeichen getrennt sind (z. B. "Tag1"). 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 erhalten. Jeder Zuordnungscodepfad sollte ein eindeutiges Pooltag verwenden, um Debuggern und Prüfern beim Identifizieren 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 zugeordneten Arbeitsspeicher zurück.

Hinweise

Diese Routine wird für die allgemeine Poolbelegung von Arbeitsspeicher verwendet.

Wenn NumberOfBytes PAGE_SIZE oder höher ist, wird ein seitenorientierter Puffer zugeordnet. Speicherbelegungen von PAGE_SIZE oder weniger werden innerhalb einer Seite zugeordnet und überschreiten keine Seitengrenzen. Speicherbelegungen von weniger als PAGE_SIZE sind nicht notwendigerweise seitenbündig ausgerichtet, sondern an 8-Byte-Grenzen in 32-Bit-Systemen und an 16-Byte-Grenzen in 64-Bit-Systemen ausgerichtet.

Eine erfolgreiche Zuordnung, die numberOfBytes< PAGE_SIZE des nicht auslagerungsfreien Pools anfordert, gibt dem Aufrufer genau die Anzahl der angeforderten Bytes Arbeitsspeicher. Wenn eine Zuordnungsanforderung für NumberOfBytes> PAGE_SIZE erfolgreich ist und NumberOfBytes kein exaktes Vielfaches von PAGE_SIZE ist, enthält die letzte Seite in der Zuordnung Bytes, die nicht Teil der Zuordnung des Aufrufers sind. Wenn möglich, verwendet die Poolzuweisung diese Bytes. Um zu vermeiden, dass Daten beschädigt werden, 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 Arbeitsspeicher zu. Programmiertools wie 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 Arbeitsspeicher nach Pooltag.

Der Wert von Tag wird in umgekehrter Reihenfolge (Little-Endian) gespeichert und manchmal angezeigt. Wenn ein Aufrufer beispielsweise "Fred" als Tag übergibt, wird es 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 ExFreePoolWithTag freigegeben werden.

Das System legt automatisch bestimmte Standardereignisobjekte fest, wenn die Poolmenge (ausgelagert oder nicht ausgelagert) hoch oder niedrig ist. Treiber können darauf warten, dass diese Ereignisse ihre Poolnutzung optimieren. Weitere Informationen finden Sie unter Standardereignisobjekte.

Aufrufer von ExAllocatePoolWithTag müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Ein Aufrufer, der bei DISPATCH_LEVEL ausgeführt wird, muss einen NonPagedXxx-Wert für PoolType angeben. Ein Aufrufer, der unter IRQL <= APC_LEVEL ausgeführt wird, kann einen beliebigen POOL_TYPE-Wert angeben, aber auch die IRQL und die Umgebung müssen bei der Bestimmung des Seitentyps berücksichtigt werden.

Legen Sie NumberOfBytes = 0 nicht fest. Vermeiden Sie Zuweisungen der Länge Null, da sie Speicherplatz für Den Poolheader verschwenden und in vielen Fällen auf ein potenzielles Validierungsproblem im aufrufenden Code hinweisen. Aus diesem Grund kennzeichnet driver verifier solche Zuordnungen als mögliche Fehler.

In einer NUMA-Multiprozessorarchitektur (Non-Uniform Memory Access) versucht ExAllocatePoolWithTag , lokalen Arbeitsspeicher dem Prozessor zuzuweisen, der ExAllocatePoolWithTag aufruft. Wenn kein lokaler Arbeitsspeicher verfügbar ist, belegt ExAllocatePoolWithTag den nächstgelegenen verfügbaren Arbeitsspeicher.

Arbeitsspeicher, den ExAllocatePoolWithTag zuordnet, wird nicht initialisiert. Ein Kernelmodustreiber muss diesen Arbeitsspeicher zuerst null, wenn er für Software im Benutzermodus sichtbar wird (um zu verhindern, dass potenziell privilegierte Inhalte verloren gehen).

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")
DDI-Complianceregeln CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

Weitere Informationen

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE