ExAllocatePool2, fonction (wdm.h)
La routine ExAllocatePool2 alloue la mémoire du pool du type spécifié et retourne un pointeur vers le bloc alloué.
Syntaxe
DECLSPEC_RESTRICT PVOID ExAllocatePool2(
POOL_FLAGS Flags,
SIZE_T NumberOfBytes,
ULONG Tag
);
Paramètres
Flags
Valeur ULONG64 typée spécifiant le type de mémoire du pool, ainsi que les attributs obligatoires et facultatifs. Plusieurs valeurs d’indicateur peuvent être combinées à l’aide de l’or au niveau du bit. Consultez POOL_FLAGS pour connaître les valeurs possibles.
NumberOfBytes
Spécifie un nombre non nul d’octets à allouer.
Tag
Balise de pool à utiliser pour la mémoire allouée. Spécifiez la balise de pool en tant que littéral de caractère différent de zéro d’un à quatre caractères délimités par des guillemets simples (par exemple, Tag1). La chaîne est généralement spécifiée dans l’ordre inverse (par exemple, 1gaT). Chaque caractère ASCII de la balise doit être une valeur dans la plage 0x20 (espace) à 0x7E (tilde). Chaque chemin de code d’allocation doit utiliser une balise de pool unique pour aider les débogueurs et les vérificateurs à identifier le chemin du code.
Valeur de retour
ExAllocatePool2 retourne un pointeur vers la mémoire allouée.
Les conditions suivantes entraînent le retour de la fonction NULL par défaut. Si POOL_FLAG_RAISE_ON_FAILURE est spécifié, la fonction déclenche une exception.
- Mémoire insuffisante
- balise est définie sur 0 ou une POOL_FLAGS non valide sont spécifiées
Remarques
Si vous créez un pilote qui cible des versions de Windows antérieures à Windows 10, version 2004, utilisez ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZeroou ExAllocatePoolQuotaUninitialized.
Cette routine présente les différences suivantes par rapport aux routines d’allocation antérieures (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority) :
La mémoire est zéro initialisée, sauf si POOL_FLAG_UNINITIALIZED est spécifiée.
Comportement de retour en cas d’allocation infructueuse. ExAllocatePoolWithQuotaTag déclenche une exception par défaut.
Les balises dont la valeur est 0 ne sont pas valides.
Lorsque vous remplacez ExAllocatePoolWithQuotaTag par ExAllocatePool2, vous devez spécifier l’indicateur POOL_FLAG_USE_QUOTA. Pour plus d’informations sur les indicateurs de pool, consultez POOL_FLAGS.
Si NumberOfBytes est PAGE_SIZE ou supérieur, une mémoire tampon alignée sur les pages est allouée. Les allocations de mémoire de PAGE_SIZE ou moins sont allouées dans une page et ne dépassent pas les limites de page. Les allocations de mémoire inférieures à PAGE_SIZE ne sont pas nécessairement alignées sur les pages, mais sont alignées sur des limites de 8 octets dans les systèmes 32 bits et sur des limites de 16 octets dans les systèmes 64 bits.
Les pilotes peuvent uniquement utiliser jusqu’au NumberOfBytes qu’ils ont alloué explicitement. L’accès à la mémoire en dehors de cette plage peut endommager le pool et provoquer le blocage du système.
Le système associe la balise de pool à la mémoire allouée. Les outils de programmation, tels que WinDbg, peuvent afficher la balise de pool associée à chaque mémoire tampon allouée. Gflags, un outil inclus dans Les outils de débogage pour Windows, active une fonctionnalité système qui demande l’allocation à partir d’un pool spécial pour une balise de pool spécifique. Poolmon, qui est inclus dans wdK, effectue le suivi de la mémoire par balise de pool.
La valeur de la balise est stockée, et parfois affichée, dans l’ordre inverse (little-endian). Par exemple, si un appelant passe Fred en tant que balise, il apparaît comme derF dans un vidage de pool et dans le suivi de l’utilisation du pool dans le débogueur, et comme 0x64657246 dans le Registre et dans l’outil s’affiche.
La mémoire tampon allouée peut être libérée avec ExFreePool ou ExFreePoolWithTag.
Les appelants de ExAllocatePool2 doivent s’exécuter à l'<IRQL = DISPATCH_LEVEL. Un appelant s’exécutant à DISPATCH_LEVEL doit spécifier POOL_FLAG_NON_PAGED ou POOL_FLAG_NON_PAGED_EXECUTABLE pour indicateurs. Un appelant en cours d’exécution au <IRQL = APC_LEVEL peut spécifier POOL_FLAG_PAGED, mais si la mémoire est accessible à partir du code exécuté à DISPATCH_LEVEL, vous devez toujours allouer de la mémoire non paginée.
Dans une architecture multiprocesseur d’accès à la mémoire non uniforme (NUMA), ExAllocatePool2 tente d’allouer de la mémoire locale au processeur qui appelle ExAllocatePool2. Si aucune mémoire locale n’est disponible, ExAllocatePool2 alloue la mémoire disponible la plus proche.
La mémoire qui ExAllocatePool2 alloue est zéro initialisée. Les pilotes en mode noyau ne doivent pas refuser la mise à zéro pour les allocations qui seront copiées vers un emplacement non approuvé (mode utilisateur, sur le réseau, etc.) pour éviter de divulguer des informations sensibles.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 10, version 2004 |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (voir la section Remarques) |
| règles de conformité DDI | HwStorPortProhibitedDDIs, SpNoWait, StorPortStartIo |