ExAllocatePoolWithTagPriority-Funktion (wdm.h)
Die ExAllocatePoolWithTagPriority Routine weist den Poolspeicher des angegebenen Typs zu.
Warnung
ExAllocatePoolWithTagPriority ist in Windows 10, Version 2004, veraltet und wurde durch ExAllocatePool3ersetzt. 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 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.
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 empfehlungsspezifisch und ab Windows XP verfügbar.
[in] NumberOfBytes
Die Anzahl der zuzuordnenden Bytes.
[in] Tag
Das Pooltag, das für den zugewiesenen Speicher verwendet werden soll. Weitere Informationen finden Sie im parameter Tag 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 vom System möglicherweise fehlschlägt, wenn sie wenig Ressourcen verwendet. Treiberzuweisungen, die von einem Zuordnungsfehler wiederhergestellt werden können, verwenden diese Priorität. |
| NormalPoolPriority- | Gibt an, dass die Anforderung vom System möglicherweise fehlschlägt, wenn sie bei Ressourcen sehr niedrig ausgeführt wird. Die meisten Treiber sollten diesen Wert verwenden. |
| HighPoolPriority- | Gibt an, dass die Anforderung vom System nicht fehlschlägt, es sei denn, sie ist vollständig aus Ressourcen. Treiber verwenden diesen Wert nur, wenn es wichtig ist, dass die Anforderung erfolgreich ausgeführt werden kann. |
Die EX_POOL_PRIORITY Enumeration definiert XxxSpecialPoolOverrun und XxxSpecialPoolUnderrun Varianten, um anzugeben, wie Arbeitsspeicher zugewiesen werden soll, wenn Driver Verifier (oder spezial pool) aktiviert ist. Wenn der Treiber XxxSpecialPoolUnderrunangibt, weist der Speicher-Manager Speicher von speziellen Pool-zu, ordnet er ihn zu Beginn 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, POOL_RAISE_IF_ALLOCATION_FAILURE ist angegeben. Andernfalls gibt die Routine einen Zeiger auf den zugewiesenen Speicher zurück.
Bemerkungen
Aufrufer von ExAllocatePoolWithTagPriority- 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.
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.
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.
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.
ExAllocatePoolWithTagPriority versucht in einer Nicht-Uniform Memory Access-Architektur (NUMA) Speicher zuzuweisen, der ExAllocatePoolWithTagPriorityaufruft. Wenn kein lokaler Speicher verfügbar ist, weist ExAllocatePoolWithTagPriority den nächstgelegenen verfügbaren Speicher zu.
Speicher, der ExAllocatePoolWithTagPriority zugewiesen wird, ist 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 | HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |