Fonction ExInitializeNPagedLookasideList (wdm.h)

Article
03/08/2023

La routine ExInitializeNPagedLookasideList initialise une liste de recherche pour les entrées non paginées de la taille spécifiée.

Syntaxe

void ExInitializeNPagedLookasideList(
  [out]          PNPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION     Allocate,
  [in, optional] PFREE_FUNCTION         Free,
  [in]           ULONG                  Flags,
  [in]           SIZE_T                 Size,
  [in]           ULONG                  Tag,
  [in]           USHORT                 Depth
);

Paramètres

[out] Lookaside

Pointeur vers la structure NPAGED_LOOKASIDE_LIST à initialiser. L’appelant doit utiliser l’espace système non paginé pour la structure. Sur les plateformes 64 bits, cette structure doit être alignée sur 16 octets.

[in, optional] Allocate

Pointeur vers une fonction fournie par l’appelant pour l’allocation d’une entrée lorsque la liste de recherche est vide, ou vers NULL. Si la valeur n’est pas NULL, le pointeur est vers une fonction avec le prototype :

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // NonPagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Si le paramètre Allocate a la valeur NULL, les appels suivants à ExAllocateFromNPagedLookasideList allouent automatiquement des entrées chaque fois que la liste de recherche est vide.

[in, optional] Free

Pointeur vers une fonction fournie par l’appelant pour libérer une entrée chaque fois que la liste de recherche est complète, ou vers NULL. Si la valeur n’est pas NULL, le pointeur est vers une fonction avec le prototype :

VOID XxxFree(
  __in PVOID  Buffer
);

Si le paramètre Free a la valeur NULL, les appels suivants à ExFreeToNPagedLookasideList libèrent automatiquement l’entrée donnée dans le pool non paginé chaque fois que la liste est complète, c’est-à-dire qu’elle contient actuellement le nombre maximal d’entrées déterminé par le système.

[in] Flags

À compter de Windows 8, ce paramètre spécifie une valeur d’indicateur facultative pour modifier le comportement par défaut de la routine ExInitializeNPagedLookasideList. Les bits d’indicateur compatibles incluent les éléments suivants.

Bit d’indicateur	Signification	Valeur
POOL_RAISE_IF_ALLOCATION_FAILURE	Si l’allocation échoue, déclenchez une exception.	16
POOL_NX_ALLOCATION	Allouez de la mémoire non exécutable.	512

Avant Windows 8, ce paramètre n’est pas utilisé et doit être égal à zéro.

[in] Size

Spécifie la taille, en octets, pour chaque entrée non pagée à allouer ultérieurement. Ce paramètre ne doit pas être inférieur à la taille minimale requise, LOOKASIDE_MINIMUM_BLOCK_SIZE, définie dans le fichier d’en-tête Wdm.h.

[in] Tag

Spécifie la balise de pool à utiliser lors de l’allocation d’entrées de liste de choix. Pour plus d’informations sur les balises de pool, consultez le paramètre Tagd’ExAllocatePoolWithTag.

[in] Depth

Réservé. Doit être zéro.

Valeur de retour

None

Remarques

Après avoir appelé ExInitializeNPagedLookasideList, les blocs de mémoire de la taille spécifiée par l’appelant peuvent être alloués et libérés à partir de la liste de recherche avec des appels à ExAllocateFromNPagedLookasideList et ExFreeToNPagedLookasideList, respectivement. Ces entrées allouées dynamiquement et libérées peuvent être n’importe quelle structure de données ou mémoire tampon de taille fixe que l’appelant utilise pendant l’exécution du système, en particulier si l’appelant ne peut pas déterminer le nombre d’entrées qui seront utilisées à un moment donné. La disposition et le contenu de chaque entrée de taille fixe sont déterminés par l’appelant.

ExInitializeNPagedLookasideList initialise l’état système pour suivre l’utilisation de la liste de lookaside donnée, comme suit :

Zéro initialise les compteurs à conserver pour les entrées.
Stocke les points d’entrée des routines XxxAllocate et XxxFree fournies par l’appelant, le cas échéant, ou définit ces points d’entrée sur ExAllocatePoolWithTag et ExFreePool, respectivement.
Initialise un verrou de rotation système pour contrôler les allocations à partir de et libère la liste de recherche de manière sécurisée multiprocesseur si nécessaire.
Stocke l’étiquette tailleet liste d’entrée fournie par l’appelant.
Configure les limites déterminées par le système (minimale et maximale) sur le nombre d’entrées à tenir dans la liste de recherche, qui peuvent être ajustées ultérieurement si la demande d’entrées à l’échelle du système est supérieure ou inférieure à ce qui était prévu.
Configure les indicateurs déterminés par le système, qui contrôlent le type de mémoire à partir duquel les entrées seront allouées ultérieurement.

Le système gère un ensemble de toutes les listes de lookaside actuellement utilisées. Comme la demande pour les entrées de liste de recherche et la mémoire non pagée disponible varient pendant l’exécution du système, le système ajuste ses limites pour le nombre d’entrées à tenir dans chaque liste de recherche non paginé dynamiquement.

Les pilotes doivent toujours libérer explicitement toutes les listes de lookaside qu’ils créent avant le déchargement. Dans le cas contraire, il s’agit d’une erreur de programmation grave. Utilisez ExDeleteNPagedLookasideList pour libérer la liste.

ExInitializeNPagedLookasideList configure l’en-tête de liste opaque à l’emplacement fourni par l’appelant, mais ne préalloue aucune mémoire pour les entrées de liste. Par la suite, les entrées initiales sont allouées dynamiquement à mesure que des appels à ExAllocateFromNPagedLookasideList se produisent, et ces entrées initiales sont conservées dans la liste de recherche lorsque des appels réciproques à ExFreeToNPagedLookasideList se produisent. Les entrées sont collectées dans la liste de recherche donnée jusqu’à ce que le maximum déterminé par le système soit atteint, où toutes les entrées supplémentaires sont retournées au pool non paginé à mesure qu’elles sont libérées. Si la liste devient vide, les demandes d’allocation sont satisfaites par la fonction XxxAllocate spécifiée lors de l’initialisation de la liste ou par ExAllocatePoolWithTag.

Il est plus efficace de passer des pointeurs NULL pour les paramètres Allocate et Freed’ExInitializeNPagedLookasideList chaque fois que l’utilisateur d’une liste de lookaside ne fait rien de plus qu’allouer et libérer des entrées de taille fixe. Toutefois, tout composant qui utilise une liste de recherche peut fournir ces fonctions pour effectuer un traitement supplémentaire déterminé par l’appelant, comme le suivi de sa propre utilisation dynamique de la mémoire en conservant l’état du nombre d’entrées qu’il alloue et libère.

Si l’appelant d’ExInitializeNPagedLookasideList fournit une fonction XxxAllocate , cette routine doit allouer des entrées pour la liste de lookaside à l’aide des paramètres d’entrée donnés lorsqu’elle appelle ExAllocatePoolWithTag.

À partir de Windows Vista, une routine similaire, ExInitializeLookasideListEx, initialise une liste de lookaside qui est décrite par une structure LOOKASIDE_LIST_EX . Contrairement aux routines XxxAllocate et XxxFree pour une liste de lookaside qui utilise une structure de NPAGED_LOOKASIDE_LIST , les routines d’allocation et de désallocation d’une liste de lookaside qui utilise la structure LOOKASIDE_LIST_EX reçoivent un pointeur de contexte comme paramètre d’entrée. Ces routines peuvent utiliser ce contexte pour stocker des données privées pour la liste de recherche. Si votre pilote est destiné à s’exécuter uniquement dans Windows Vista et les versions ultérieures de Windows, envisagez d’utiliser ExInitializeLookasideListEx au lieu d’ExInitializeNPagedLookasideList. Pour plus d’informations, consultez Utilisation de lookaside Listes.

Les appelants d’ExInitializeNPagedLookasideList peuvent s’exécuter sur IRQL <= DISPATCH_LEVEL, mais ils s’exécutent généralement sur IRQL = PASSIVE_LEVEL.

Configuration requise

Condition requise	Valeur
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)