ExAllocatePool-Funktion (wdm.h)
Warnung
ExAllocatePool ist veraltet und wurde in Windows 10 Version 2004 veraltet. Es wurde durch ExAllocatePool2 ersetzt. Weitere Informationen finden Sie unter Aktualisieren veralteter ExAllocatePool-Aufrufe an ExAllocatePool2 und ExAllocatePool3.
Verwenden Sie beim Entwickeln von Treibern für Windows-Versionen vor Windows 10 Version 2004 ExAllocatePoolZero.
ExAllocatePool weist poolspeicher des angegebenen Typs zu und gibt einen Zeiger auf den zugeordneten Block zurück.
Syntax
PVOID ExAllocatePool(
[in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes
);
Parameter
[in] PoolType
Gibt den Typ des zuzuweisenden Poolspeichers an. Eine Beschreibung der verfügbaren Poolspeichertypen finden Sie unter POOL_TYPE.
Sie können PoolType ändern, indem Sie ein bitweises OR mit dem POOL_COLD_ALLOCATION-Flag als Hinweis an den Kernel verwenden, 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 Flag POOL_COLD_ALLOCATION ist nur ein Hinweis und für Windows XP und höhere Versionen des Windows-Betriebssystems verfügbar.
[in] NumberOfBytes
Legt die Anzahl der zuzuweisenden Bytes fest.
Rückgabewert
ExAllocatePool 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 zugewiesenen Arbeitsspeicher zurück.
Hinweise
Diese Routine wird für die allgemeine Poolzuordnung von Arbeitsspeicher verwendet.
Wenn NumberOfBytes PAGE_SIZE oder höher ist, wird ein seitenorientierter Puffer zugewiesen. Speicherzuordnungen von PAGE_SIZE oder weniger ü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.
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 der Poolzuordnungsgeber 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.
Wenn ExAllocatePoolNULL zurückgibt, sollte der Aufrufer den NTSTATUS-Wert STATUS_INSUFFICIENT_RESOURCES zurückgeben oder die Verarbeitung auf einen anderen Zeitpunkt verzögern.
Aufrufer von ExAllocatePool 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.
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.
Der von ExAllocatePool zugewiesene Arbeitsspeicher wird 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Veraltet. Diese Routine wird nur für vorhandene Binärdateien exportiert. Verwenden Sie stattdessen ExAllocatePoolWithTag. |
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h, Classpnp.h, Smcnt.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (siehe Abschnitt Hinweise) |
| DDI-Complianceregeln | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |