_RxAllocatePoolWithTag fonction

Article
02/12/2024

_RxAllocatePoolWithTag alloue de la mémoire à partir d’un pool avec une balise de quatre octets au début du bloc qui peut être utilisée pour intercepter les instances de stockage de mémoire.

Syntaxe

VOID* _RxAllocatePoolWithTag(
   ULONG Type,
   ULONG Size,
   ULONG Tag,
   PSZ   FileName,
   ULONG LineNumber
);

Paramètres

Type
Type du pool à allouer. Ce paramètre peut être l’une des valeurs d’énumération suivantes pour POOL_TYPE :

NonPagedPool
Mémoire système non pagéable accessible à partir de n’importe quel IRQL. La mémoire NonPagedPool est une ressource rare et les pilotes ne doivent l’allouer que si nécessaire. Le système peut uniquement allouer des mémoires tampons supérieures à PAGE_SIZE à partir de NonPagedPool dans plusieurs PAGE_SIZE. Les demandes pour les mémoires tampons supérieures à PAGE_SIZE, mais pas une PAGE_SIZE multiples, gaspillez de la mémoire non pagable.

PagedPool
Mémoire système paginable qui ne peut être allouée et accessible qu’au DISPATCH_LEVEL IRQL < .

Taille
Taille du bloc de mémoire, en octets, à allouer.

Tag
Balise de quatre octets à utiliser pour marquer la mémoire tampon allouée. Pour obtenir une description de l’utilisation des balises, consultez ExAllocatePoolWithTag. La valeur ASCII de chaque caractère de la balise doit être comprise entre 0 et 127.

FileName
Pointeur vers le nom du fichier source où l’allocation de mémoire s’est produite. Ce paramètre n’est pas utilisé actuellement.

LineNumber
Numéro de ligne dans le fichier source où l’allocation de mémoire s’est produite. Ce paramètre n’est pas utilisé actuellement.

Valeur retournée

RxAllocatePoolWithTag 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

Il est recommandé d’appeler la macro RxAllocatePoolWithTag au lieu d’utiliser cette routine directement. Sur les builds de vente au détail, cette macro est définie pour appeler ExAllocatePoolWithTag. Sur les builds vérifiées, cette macro est définie pour appeler _RxAllocatePoolWithTag.

La routine _RxAllocatePoolWithTag appelle ExAllocatePoolWithTagPriority avec la priorité (importance de la requête) définie sur LowPoolPriority. Le système peut échouer la demande pour LowPoolPriority lorsqu’il s’exécute à faible niveau de ressources. Un pilote doit être prêt à récupérer après un échec d’allocation lors de l’utilisation de cette routine.

Lorsque le système alloue une mémoire tampon à partir de la mémoire du pool de PAGE_SIZE ou supérieure, il aligne la mémoire tampon sur une limite de page. Les demandes de mémoire inférieures à PAGE_SIZE ne sont pas nécessairement alignées sur les limites de page, mais s’alignent toujours sur une seule page et sont alignées sur une limite de 8 octets. Toute allocation réussie qui demande un bloc supérieur à PAGE_SIZE qui n’est pas un multiple de PAGE_SIZE gaspille tous les octets inutilisés sur la dernière page allouée.

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. La valeur de Tag est normalement affichée dans l’ordre inverse. Par exemple, si un appelant passe « Fred » en tant que balise, il apparaît sous la forme « derF » si la mémoire est vidée ou lors du suivi de l’utilisation de la mémoire dans le débogueur.

La mémoire allouée avec _RxAllocatePoolWithTag doit être libérée en appelant _RxFreePool.

Les appelants de _RxAllocatePoolWithTag doivent s’exécuter à IRQL <= DISPATCH_LEVEL. Un appelant qui s’exécute à DISPATCH_LEVEL doit spécifier une valeur NonPagedPool pour le paramètre Type . Un appelant qui s’exécute dans IRQL <= APC_LEVEL peut spécifier n’importe quelle valeur POOL_TYPE pour le paramètre Type .