ExAllocatePool2-Funktion (wdm.h)

  • Artikel

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

Syntax

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

Parameter

Flags

Ein ULONG64 typisierten Wert, der den Typ des Poolspeichers zusammen mit den erforderlichen und optionalen Attributen angibt. Mehrere Flagwerte können bitweise oder kombiniert werden. Mögliche Werte finden Sie unter POOL_FLAGS .

NumberOfBytes

Gibt eine Ungleich null-Anzahl von Bytes an, die zugewiesen werden sollen.

Tag

Das Pooltag, das für den zugewiesenen Arbeitsspeicher verwendet werden soll. Geben Sie das Pooltag als Zeichenliteral ungleich 0 von 1 bis vier Zeichen an, Tag1die durch einzelne Anführungszeichen getrennt sind (z. B. ). Die Zeichenfolge wird normalerweise in umgekehrter Reihenfolge angegeben (z. B. 1gaT). Jedes ASCII-Zeichen im Tag muss ein Wert im Bereich 0x20 (Leerzeichen) bis 0x7E (Tilde) sein. Jeder Zuordnungscodepfad sollte ein eindeutiges Pooltag verwenden, um Debuggern und Prüfern beim Identifizieren des Codepfads zu helfen.

Rückgabewert

ExAllocatePool2 gibt einen Zeiger auf den zugewiesenen Arbeitsspeicher 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.

  • Der Arbeitsspeicher reicht nicht aus
  • Tag ist auf 0 festgelegt, oder ungültige POOL_FLAGS angegeben sind

Hinweise

Wenn Sie einen Treiber für Windows-Versionen vor Windows 10 Version 2004 erstellen, verwenden Sie ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero oder ExAllocatePoolQuotaUninitialized.

Diese Routine unterscheidet sich von den früheren Zuordnungsroutinen (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):

  1. Der Arbeitsspeicher wird null initialisiert, es sei denn , es wird POOL_FLAG_UNINITIALIZED angegeben.

  2. Gibt das Verhalten bei einer nicht erfolgreichen Zuordnung zurück. ExAllocatePoolWithQuotaTag löst standardmäßig eine Ausnahme aus.

  3. Tags mit dem Wert 0 sind ungültig.

Wenn Sie ExAllocatePoolWithQuotaTag durch ExAllocatePool2 ersetzen, müssen Sie das flag POOL_FLAG_USE_QUOTA angeben. Weitere Informationen zu Poolflags finden Sie unter POOL_FLAGS.

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

Treiber dürfen nur bis zu den NumberOfBytes verwenden, die sie explizit zugewiesen haben. Der Zugriff auf Arbeitsspeicher außerhalb dieses Bereichs kann den Pool beschädigen und zum Absturz des Systems führen.

Das System ordnet das Pooltag dem zugeordneten Arbeitsspeicher 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 Arbeitsspeicher nach Pooltag nach.

Der Wert von Tag wird in umgekehrter Reihenfolge (Little-Endian) gespeichert und manchmal angezeigt. Wenn ein Aufrufer beispielsweise als Tag übergibt Fred , wird es als derF in einem Poolabbild und in der Poolnutzungsnachverfolgung im Debugger und wie 0x64657246 in der Registrierung und in den Toolanzeigen angezeigt.

Der zugeordnete Puffer kann entweder mit ExFreePool oder ExFreePoolWithTag freigegeben 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 Flags angeben. Ein Aufrufer, der unter IRQL <= APC_LEVEL ausgeführt wird, kann POOL_FLAG_PAGED angeben. Wenn jedoch über Code, der unter DISPATCH_LEVEL ausgeführt wird, auf den Arbeitsspeicher zugegriffen wird, müssen Sie trotzdem nicht ausgelagerten Arbeitsspeicher zuordnen.

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

Der von ExAllocatePool2 zugewiesene Arbeitsspeicher ist null initialisiert. Kernelmodustreiber sollten keine Nullen für Zuordnungen deaktivieren, die an einen nicht vertrauenswürdigen Speicherort (Benutzermodus, über das Netzwerk usw.) kopiert werden, um die Offenlegung vertraulicher Informationen zu vermeiden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 10, Version 2004
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 HwStorPortProhibitedDDIs, SpNoWait, StorPortStartIo

Weitere Informationen

ExAllocatePool3