ALLOCATE_FUNCTION_EX fonction de rappel (wdm.h)

Article
02/29/2024

La routine LookasideListAllocateEx alloue le stockage pour une nouvelle entrée de liste de lookaside lorsqu’un client demande une entrée à partir d’une liste de 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 de liste de choix. L’appelant définit ce paramètre sur une valeur d’énumération POOL_TYPE valide, et éventuellement au niveau du bit OR cette valeur 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’appel ExInitializeLookasideListEx qui a initialisé la liste de 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 que celle 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 le or au niveau du bit de POOL_RAISE_IF_ALLOCATION_FAILURE et la valeur du paramètre PoolType qui a été passée à ExInitializeLookasideListEx. La routine LookasideListAllocateEx peut transmettre 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 le OR au niveau du bit de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE et la valeur PoolType qui a été passée à ExInitializeLookasideListEx. La routine LookasideListAllocateEx peut transmettre 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 de liste de choix. 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 lookaside. Cette structure a été précédemment initialisée par la routine ExInitializeLookasideListEx .

Valeur retournée

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

Remarques

Un pilote qui crée une liste de 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 de choix sont des mémoires tampons d’une taille uniforme, que le pilote spécifie lors de l’initialisation de la liste.

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

Un pilote appelle la routine ExAllocateFromLookasideListEx pour allouer une entrée à partir d’une liste de lookaside. Si la liste est vide (ne contient aucune entrée), ExAllocateFromLookasideListEx appelle LookasideListAllocateEx pour allouer dynamiquement le stockage à 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, Tag et Lookaside contiennent les mêmes valeurs que celles qui ont été passées en tant que paramètres d’entrée dans l’appel ExInitializeLookasideListEx qui a initialisé la liste de lookaside.

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

Pour plus d’informations sur les listes de lookaside, consultez Utilisation de lookaside Listes.

La routine LookasideListAllocateEx est appelée au même niveau 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 pagée, 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 fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de 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 lors de l’exécution des 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 la configuration requise pour les 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 Annotating Function Behavior.