ExAllocatePoolWithTagPriority, fonction (wdm.h)
La routine ExAllocatePoolWithTagPriority alloue la mémoire du pool du type spécifié.
Avertissement
ExAllocatePoolWithTagPriority a été déprécié dans Windows 10, version 2004 et a été remplacé par ExAllocatePool3. Pour plus d’informations, consultez Mise à jour des appels ExAllocatePool déconseillés à ExAllocatePool2 et ExAllocatePool3.
Syntaxe
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
);
Paramètres
[in] PoolType
Type de mémoire du pool à allouer. Pour obtenir une description des types de mémoire de pool disponibles, consultez POOL_TYPE.
Vous pouvez modifier la valeur PoolType en utilisant le bitwise-ORing cette valeur avec l’indicateur de POOL_RAISE_IF_ALLOCATION_FAILURE. Cet indicateur déclenche une exception si la demande ne peut pas être satisfaite.
De même, vous pouvez modifier la valeur PoolType en utilisant le bit-ORing cette valeur avec l’indicateur de POOL_COLD_ALLOCATION comme indicateur du noyau pour allouer la mémoire à partir de 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 et est disponible à partir de Windows XP.
[in] NumberOfBytes
Nombre d’octets à allouer.
[in] Tag
Balise de pool à utiliser pour la mémoire allouée. Pour plus d’informations, consultez le paramètre Tag de ExAllocatePoolWithTag.
[in] Priority
Priorité de cette demande. Définissez ce paramètre sur l’une des valeurs d’énumération EX_POOL_PRIORITY suivantes.
| Valeur de priorité | Description |
|---|---|
| LowPoolPriority | Spécifie que le système peut échouer la requête lorsqu’il s’exécute faiblement sur les ressources. Les allocations de pilotes qui peuvent récupérer à partir d’un échec d’allocation utilisent cette priorité. |
| NormalPoolPriority | Spécifie que le système peut échouer la requête lorsqu’il s’exécute très faiblement sur les ressources. La plupart des pilotes doivent utiliser cette valeur. |
| HighPoolPriority | Spécifie que le système ne doit pas échouer la requête, sauf s’il n’est pas complètement hors ressources. Les pilotes utilisent cette valeur uniquement lorsqu’il est critiquement important que la demande réussisse. |
L’énumération EX_POOL_PRIORITY définit XxxSpecialPoolOverrun et XxxSpecialPoolUnderrun variantes pour spécifier la façon dont la mémoire doit être allouée quand vérificateur de pilote (ou pool spécial) est activé. Si le pilote spécifie XxxSpecialPoolUnderrun, lorsque le gestionnaire de mémoire alloue de la mémoire à partir de pool spécial, il l’alloue au début d’une page physique. Si le pilote spécifie XxxSpecialPoolOverrun, le gestionnaire de mémoire l’alloue à la fin d’une page physique.
Valeur de retour
ExAllocatePoolWithTagPriority retourne NULL en cas d’insuffisance de mémoire dans le pool libre pour satisfaire la demande, sauf si POOL_RAISE_IF_ALLOCATION_FAILURE est spécifié. Sinon, la routine retourne un pointeur vers la mémoire allouée.
Remarques
Les appelants de exAllocatePoolWithTagPriority doivent s’exécuter au <IRQL = DISPATCH_LEVEL. Un appelant s’exécutant à DISPATCH_LEVEL doit spécifier une valeur NonPagedXxx pour PoolType. Un appelant s’exécutant au <IRQL = APC_LEVEL peut spécifier n’importe quelle valeur de POOL_TYPE, mais l’environnement et irQL doivent également être pris en compte pour déterminer le type de page.
Si nombre d’octets 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.
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, vérificateur de pilotes indicateurs tels que les erreurs possibles.
Le système définit automatiquement certains objets d’événements 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 standard Event Objects.
Dans une architecture multiprocesseur d’accès à la mémoire non uniforme (NUMA), ExAllocatePoolWithTagPriority tente d’allouer de la mémoire locale au processeur appelant ExAllocatePoolWithTagPriority. Si aucune mémoire locale n’est disponible, ExAllocatePoolWithTagPriority alloue la mémoire disponible la plus proche.
Mémoire qui ExAllocatePoolWithTagPriority alloue est non initialisée. Un pilote en mode noyau doit d’abord zéro cette mémoire s’il va le rendre visible par les logiciels en mode utilisateur (pour éviter la fuite de contenu potentiellement privilégié).
Exigences
| Exigence | Valeur |
|---|---|
| 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(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |