Fonction ExAllocatePool2 (wdm.h)

  • Article

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 de type ULONG64 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 OR au niveau du bit. Consultez POOL_FLAGS pour connaître les valeurs possibles.

NumberOfBytes

Spécifie un nombre d’octets autre que zéro à allouer.

Tag

Balise de pool à utiliser pour la mémoire allouée. Spécifiez la balise de pool sous la forme d’un littéral de caractères non nuls 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 retournée

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 lève une exception.

  • Mémoire insuffisante
  • La balise est définie sur 0 ou POOL_FLAGS non valides sont spécifiées

Remarques

Si vous créez un pilote qui cible les versions de Windows antérieures à Windows 10 version 2004, utilisez ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero ou ExAllocatePoolQuotaUninitialized.

Cette routine présente les différences suivantes par rapport aux routines d’allocation précédentes (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority) :

  1. La mémoire est zéro initialisée, sauf si POOL_FLAG_UNINITIALIZED est spécifié.

  2. Comportement de retour en cas d’échec de l’allocation. ExAllocatePoolWithQuotaTag lève une exception par défaut.

  3. Les balises ayant la valeur 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 la page est allouée. Les allocations de mémoire de PAGE_SIZE ou moins sont allouées au sein d’une page et ne dépassent pas les limites des pages. Les allocations de mémoire inférieures à ne sont pas nécessairement alignées sur les pages, mais sont alignées sur les limites de 8 octets PAGE_SIZE dans les systèmes 32 bits et sur les limites de 16 octets dans les systèmes 64 bits.

Les pilotes peuvent uniquement utiliser jusqu’au nombre d’octets qu’ils ont explicitement alloués. 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 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 particulière. Poolmon, qui est inclus dans le WDK, effectue le suivi de la mémoire par balise de pool.

La valeur de Tag est stockée, et parfois affichée, dans l’ordre inverse (petit-endien). 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 les affichages de l’outil.

La mémoire tampon allouée peut être libérée avec ExFreePool ou ExFreePoolWithTag.

Les appelants d’ExAllocatePool2 doivent s’exécuter sur IRQL <= DISPATCH_LEVEL. Un appelant qui s’exécute à DISPATCH_LEVEL doit spécifier POOL_FLAG_NON_PAGED ou POOL_FLAG_NON_PAGED_EXECUTABLE pour les indicateurs. Un appelant qui s’exécute dans 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 allouée par ExAllocatePool2 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.) afin d’éviter de divulguer des informations sensibles.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 10, version 2004
Plateforme cible Universal
En-tête wdm.h (inclure 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

Voir aussi

ExAllocatePool3