Fonction ExAllocatePoolWithTag (wdm.h)

  • Article

La routine ExAllocatePoolWithTag alloue la mémoire du pool du type spécifié et retourne un pointeur vers le bloc alloué.

Avertissement

ExAllocatePoolWithTag a été déprécié dans Windows 10 version 2004 et a été remplacé par ExAllocatePool2. Pour plus d’informations, consultez Mise à jour des appels ExAllocatePool déconseillés vers ExAllocatePool2 et ExAllocatePool3.

Syntaxe

PVOID ExAllocatePoolWithTag(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes,
  [in] ULONG                                          Tag
);

Paramètres

[in] PoolType

Type de mémoire de pool à allouer. Pour obtenir une description des types de mémoire de pool disponibles, consultez POOL_TYPE.

Vous pouvez modifier la valeur PoolType en oRing cette valeur au niveau du bit avec l’indicateur POOL_RAISE_IF_ALLOCATION_FAILURE. Cet indicateur provoque le déclenchement d’une exception si la demande ne peut pas être satisfaite. L’utilisation de l’indicateur POOL_RAISE_IF_ALLOCATION_FAILURE n’est pas recommandée, car elle est coûteuse.

De même, vous pouvez modifier la valeur PoolType en oRing cette valeur au niveau du bit avec l’indicateur POOL_COLD_ALLOCATION comme indicateur au noyau pour allouer la mémoire des pages susceptibles d’être paginées rapidement. Pour réduire autant que possible la quantité de mémoire du pool résident, vous ne devez pas référencer ces allocations fréquemment. L’indicateur POOL_COLD_ALLOCATION est uniquement consultatif.

[in] NumberOfBytes

Nombre d'octets à allouer.

[in] 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 nul de 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

ExAllocatePoolWithTag retourne NULL si la mémoire dans le pool libre est insuffisante pour répondre à la demande. Sinon, la routine retourne un pointeur vers la mémoire allouée.

Remarques

Cette routine est utilisée pour l’allocation générale de mémoire du pool.

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 de la 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 les limites de 8 octets dans les systèmes 32 bits et sur les limites de 16 octets dans les systèmes 64 bits.

Une allocation réussie demandant NumberOfBytes< PAGE_SIZE de pool non paginé donne à l’appelant exactement le nombre d’octets de mémoire demandés. Si une demande d’allocation pour NumberOfBytes> PAGE_SIZE réussit et que NumberOfBytes n’est pas un multiple exact de PAGE_SIZE, la dernière page de l’allocation contient des octets qui ne font pas partie de l’allocation de l’appelant. Si possible, l’allocateur de pool utilise ces octets. Pour éviter d’endommager les données qui appartiennent à d’autres composants en mode noyau, les pilotes doivent accéder uniquement aux adresses de stockage qu’ils ont explicitement allouées.

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 une 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 (little-endian). Par exemple, si un appelant passe « Fred » en tant que balise, il apparaît sous la forme « derF » dans un vidage du pool et dans le suivi de l’utilisation du pool dans le débogueur, et en tant que 0x64657246 dans le Registre et dans les affichages d’outils.

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

Le système définit automatiquement certains objets d’événement standard lorsque la quantité de pool (paginée ou non paginée) est élevée ou faible. Les pilotes peuvent attendre que ces événements ajustent l’utilisation de leur pool. Pour plus d’informations, consultez Objets d’événements standard.

Les appelants d’ExAllocatePoolWithTag doivent s’exécuter sur IRQL <= DISPATCH_LEVEL. Un appelant qui s’exécute à DISPATCH_LEVEL doit spécifier une valeur Xxxnon paginé pour PoolType. Un appelant qui s’exécute sur IRQL <= APC_LEVEL peut spécifier n’importe quelle valeur POOL_TYPE, mais l’irQL et l’environnement doivent également être pris en compte pour déterminer le type de page.

Ne définissez pas NumberOfBytes = 0. Évitez les allocations de longueur nulle, car elles gaspillent l’espace d’en-tête du pool et, dans de nombreux cas, indiquent un problème de validation potentiel dans le code appelant. Pour cette raison, driver Verifier signale ces allocations comme erreurs possibles.

Dans une architecture multiprocesseur d’accès mémoire non uniforme (NUMA), ExAllocatePoolWithTag tente d’allouer de la mémoire locale au processeur qui appelle ExAllocatePoolWithTag. Si aucune mémoire locale n’est disponible, ExAllocatePoolWithTag alloue la mémoire disponible la plus proche.

La mémoire allouée par ExAllocatePoolWithTag n’est pas initialisée. Un pilote en mode noyau doit d’abord zéro cette mémoire s’il veut la rendre visible pour les logiciels en mode utilisateur (afin d’éviter la fuite de contenu potentiellement privilégié).

Configuration requise

Condition requise Valeur
Plateforme cible Universal
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 Notes)
Règles de conformité DDI CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

Voir aussi

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE