ALLOCATE_FUNCTION_EX fonction de rappel (wdm.h)

Article
02/07/2025

La routine LookasideListAllocateEx alloue le stockage pour une nouvelle entrée de liste lookaside lorsqu’un client demande une entrée à partir d’une liste lookaside vide.

Syntaxe

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Paramètres

[in] PoolType

Spécifie le type de stockage à allouer pour la nouvelle entrée lookaside-list. L’appelant définit ce paramètre sur une valeur d’énumération POOL_TYPE valide, et éventuellement des OR au niveau du bit avec l’un des bits d’indicateur suivants :

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Pour plus d’informations sur l’indicateur POOL_RAISE_IF_ALLOCATION_FAILURE, consultez ExAllocatePoolWithTag. Pour plus d’informations sur l’indicateur POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, consultez ExAllocatePoolWithQuotaTag.

Si, dans l'ExInitializeLookasideListEx appel qui initialise la liste lookaside, le paramètre Flags est égal à zéro, le paramètre PoolType que la routine LookasideListAllocateEx reçoit est la même valeur de paramètre PoolType qui a été passée à ExInitializeLookasideListEx.

Si, dans l’appel ExInitializeLookasideListEx, Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, le paramètre PoolType que la routine LookasideListAllocateEx reçoit est la or au niveau du bit de POOL_RAISE_IF_ALLOCATION_FAILURE et la valeur de paramètre PoolType qui a été passée à ExInitializeLookasideListEx. La routine LookasideListAllocateEx peut passer sa valeur de paramètre PoolType, sans modification, à la routine ExAllocatePoolWithTag.

Si, dans l’appel ExInitializeLookasideListEx, Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, le paramètre PoolType que la routine LookasideListAllocateEx reçoit est l’OR au niveau du bit de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE et la valeur PoolType passée à ExInitializeLookasideListEx. La routine LookasideListAllocateEx peut passer sa valeur de paramètre PoolType, sans modification, à la routine ExAllocatePoolWithQuotaTag.

[in] NumberOfBytes

Spécifie la taille, en octets, de l’entrée lookaside-list à allouer.

[in] Tag

Spécifie la balise de pool de quatre octets à utiliser pour marquer le stockage alloué pour la nouvelle entrée lookaside-list. Pour plus d’informations sur les balises de pool, consultez la description du paramètre tag dans ExAllocatePoolWithTag.

[in, out] Lookaside

Pointeur vers une structure LOOKASIDE_LIST_EX qui décrit la liste de choix. Cette structure a été précédemment initialisée par la routine ExInitializeLookasideListEx.

Valeur de retour

LookasideListAllocateEx retourne un pointeur vers l’entrée lookaside-list allouée. Si la routine ne peut pas allouer d’entrée, elle retourne NULL.

Remarques

Un pilote qui crée une liste lookaside peut implémenter une routine LookasideListAllocateEx pour allouer dynamiquement des mémoires tampons pour la liste. Une mémoire tampon qui n’est pas utilisée est stockée en tant qu’entrée dans la liste. Toutes les entrées d’une liste lookaside sont des mémoires tampons d’une taille uniforme, que le pilote spécifie quand la liste est initialisée.

Le pilote fournit un pointeur vers une routine LookasideListAllocateEx personnalisée en tant que paramètre d’entrée dans l'ExInitializeLookasideListEx appel qui initialise la liste lookaside. Si le pilote définit ce paramètre sur NULL, la liste lookaside utilise plutôt une routine d’allocation par défaut.

Un pilote appelle la routine ExAllocateFromLookasideListEx pour allouer une entrée à partir d’une liste de choix. Si la liste est vide (ne contient aucune entrée), ExAllocateFromLookasideListEx appelle LookasideListAllocateEx pour allouer dynamiquement le stockage pour une nouvelle entrée. LookasideListAllocateEx retourne un pointeur vers l’entrée nouvellement allouée si l’allocation réussit. Sinon, elle retourne NULL .

Les paramètres PoolType, NumberOfBytes, Taget Lookaside contiennent les mêmes valeurs qui ont été passées en tant que paramètres d’entrée dans l’appel ExInitializeLookasideListEx qui a initialisé la liste lookaside.

La routine LookasideListAllocateEx peut utiliser le paramètre Lookaside pour accéder aux données de contexte privé que le pilote a associées à la liste lookaside. Pour plus d’informations, consultez l’exemple de code dans ExInitializeLookasideListEx.

Pour plus d’informations sur les listes lookaside, consultez Using Lookaside Lists.

La routine LookasideListAllocateEx est appelée au même IRQL que l’appel à ExAllocateFromLookasideListEx qui demande l’entrée. Pour un appel qui demande une entrée qui réside dans la mémoire paginée, l’appelant doit exécuter IRQL <= APC_LEVEL. Pour un appel qui demande une entrée qui réside dans la mémoire non paginé, l’appelant doit exécuter IRQL <= DISPATCH_LEVEL.

Exemples

Pour définir une routine de rappel LookasideListAllocateEx, vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel LookasideListAllocateEx nommée MyLookasideListAllocateEx, utilisez le type FREE_FUNCTION_EX comme indiqué dans cet exemple de code :

FREE_FUNCTION_EX MyLookasideListFreeEx;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

Le type de fonction FREE_FUNCTION_EX est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction FREE_FUNCTION_EX dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur les exigences relatives aux déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez annoter le comportement de la fonction.