ExAllocatePoolWithTagPriority-Funktion (wdm.h)
Die ExAllocatePoolWithTagPriority-Routine weist Poolspeicher des angegebenen Typs zu.
Warnung
ExAllocatePoolWithTagPriority wurde in Windows 10 Version 2004 veraltet und durch ExAllocatePool3 ersetzt. Weitere Informationen finden Sie unter Aktualisieren veralteter ExAllocatePool-Aufrufe an ExAllocatePool2 und ExAllocatePool3.
Syntax
PVOID ExAllocatePoolWithTagPriority(
[in] __drv_strictTypeMatch(__drv_typeCond)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag,
[in] __drv_strictTypeMatch(__drv_typeExpr)EX_POOL_PRIORITY Priority
);
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 ändern, indem Sie bitweise diesen Wert mit dem POOL_RAISE_IF_ALLOCATION_FAILURE Flagringen. Dieses Flag bewirkt, dass eine Ausnahme ausgelöst wird, wenn die Anforderung nicht erfüllt werden kann.
Auf ähnliche Weise können Sie den PoolType-Wert ändern, indem Sie diesen Wert bitweise mit dem POOL_COLD_ALLOCATION-Flag als Hinweis an den Kernel ändern, um den Arbeitsspeicher 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 ein Hinweis und ab Windows XP verfügbar.
[in] NumberOfBytes
Die Anzahl der zu belegenden Bytes.
[in] Tag
Das Pooltag, das für den zugewiesenen Arbeitsspeicher verwendet werden soll. Weitere Informationen finden Sie im Tag-Parameter von ExAllocatePoolWithTag.
[in] Priority
Die Priorität dieser Anforderung. Legen Sie diesen Parameter auf einen der folgenden EX_POOL_PRIORITY Enumerationswerte fest.
| Prioritätswert | BESCHREIBUNG |
|---|---|
| LowPoolPriority | Gibt an, dass die Anforderung möglicherweise fehlschlägt, wenn die Ressourcen knapp sind. Treiberzuordnungen, die nach einem Zuordnungsfehler wiederherstellen können, verwenden diese Priorität. |
| NormalPoolPriority | Gibt an, dass das System die Anforderung möglicherweise fehlschlägt, wenn die Ressourcen sehr niedrig sind. Die meisten Treiber sollten diesen Wert verwenden. |
| HighPoolPriority | Gibt an, dass die Anforderung vom System nicht fehlschlagen darf, es sei denn, es sind keine vollständigen Ressourcen vorhanden. Treiber verwenden diesen Wert nur, wenn es wichtig ist, dass die Anforderung erfolgreich ist. |
Die EX_POOL_PRIORITY-Enumeration definiert die Varianten XxxSpecialPoolOverrun und XxxSpecialPoolUnderrun , um anzugeben, wie Arbeitsspeicher zugewiesen werden soll, wenn Driver Verifier (oder ein spezieller Pool) aktiviert ist. Wenn der Treiber XxxSpecialPoolUnderrun angibt, ordnet der Speicher-Manager Speicher aus einem speziellen Pool am Anfang einer physischen Seite zu. Wenn der Treiber XxxSpecialPoolOverrun angibt, weist der Speicher-Manager es am Ende einer physischen Seite zu.
Rückgabewert
ExAllocatePoolWithTagPriority gibt NULL zurück, wenn im freien Pool nicht genügend Arbeitsspeicher vorhanden ist, um die Anforderung zu erfüllen, es sei denn, es wird POOL_RAISE_IF_ALLOCATION_FAILURE angegeben. Andernfalls gibt die Routine einen Zeiger auf den zugewiesenen Arbeitsspeicher zurück.
Hinweise
Aufrufer von ExAllocatePoolWithTagPriority 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 mit IRQL <= APC_LEVEL ausgeführt wird, kann einen beliebigen POOL_TYPE-Wert angeben, aber auch der IRQL und die Umgebung müssen für die Bestimmung des Seitentyps berücksichtigt werden.
Wenn NumberOfBytes PAGE_SIZE oder höher ist, 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 unbedingt seitenbündig, sondern an 8-Byte-Grenzen in 32-Bit-Systemen und an 16-Byte-Grenzen in 64-Bit-Systemen ausgerichtet.
Legen Sie NumberOfBytes = 0 nicht fest. Vermeiden Sie Zuweisungen der Länge null, da sie Speicherplatz im 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.
Das System legt automatisch bestimmte Standardereignisobjekte fest, wenn die Anzahl 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 Standardereignisobjekte.
In einer NUMA-Multiprozessorarchitektur (Non-Uniform Memory Access) versucht ExAllocatePoolWithTagPriority , lokalen Arbeitsspeicher dem Prozessor zuzuweisen, der ExAllocatePoolWithTagPriority aufruft. Wenn kein lokaler Arbeitsspeicher verfügbar ist, weist ExAllocatePoolWithTagPriority den nächstgelegenen verfügbaren Arbeitsspeicher zu.
Der von ExAllocatePoolWithTagPriority zugewiesene Arbeitsspeicher ist nicht initialisiert. Ein Kernelmodustreiber muss diesen Arbeitsspeicher zuerst null, wenn er für Software im Benutzermodus sichtbar macht (um zu vermeiden, 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 | HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |