Fonction ExInitializePagedLookasideList (wdm.h)

Article
08/08/2023

La routine ExInitializePagedLookasideList initialise une liste de recherche pour les entrées paginables de la taille spécifiée.

Syntaxe

void ExInitializePagedLookasideList(
  [out]          PPAGED_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 PAGED_LOOKASIDE_LIST à initialiser. L’appelant doit utiliser l’espace système non paginé pour la structure, même si les entrées de cette liste de lookaside seront allouées à partir de la mémoire paginable. 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,           // PagedPool 
  __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 à ExAllocateFromPagedLookasideList 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 à ExFreeToPagedLookasideList libèrent automatiquement l’entrée donnée dans le pool paginé chaque fois que la liste est pleine, 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 ExInitializePagedLookasideList. Les bits d’indicateur compatibles incluent les éléments suivants.

Bit d’indicateur	Signification
POOL_RAISE_IF_ALLOCATION_FAILURE	Si l’allocation échoue, déclenchez une exception.

La spécification de l’indicateur POOL_NX_ALLOCATION n’a aucun effet. Toute la mémoire paginable est allouée en tant que NX.

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

[in] Size

Spécifie la taille en octets de chaque entrée de la liste de recherche.

[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é ExInitializePagedLookasideList, les blocs de la taille spécifiée par l’appelant peuvent être alloués à la liste de recherche et libérés dans la liste de recherche avec des appels à ExAllocateFromPagedLookasideList et ExFreeToPagedLookasideList, 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.

ExInitializePagedLookasideList 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 en cours d’utilisation. Étant donné que la demande d’entrées de liste de recherche et de mémoire paginée disponible varie pendant l’exécution du système, le système ajuste dynamiquement ses limites pour le nombre d’entrées à tenir dans chaque liste paginée.

Les pilotes doivent toujours utiliser explicitement 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 ExDeletePagedLookasideList pour libérer la liste.

ExInitializePagedLookasideList 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 à ExAllocateFromPagedLookasideList se produisent, et ces entrées initiales sont conservées dans la liste de lookaside lorsque des appels réciproques à ExFreeToPagedLookasideList 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 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’ExInitializePagedLookasideList 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’ExInitializePagedLookasideList fournit une fonction XxxAllocate , cette fonction doit allouer des entrées pour la liste de recherche à 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 recherche qui utilise une structure de PAGED_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’ExInitializePagedLookasideList. Pour plus d’informations, consultez Utilisation de lookaside Listes.

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	<= APC_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),IrqlExApcLte2(wdm)