WdfLookasideListCreate, fonction (wdfmemory.h)

Article
02/27/2024

[S’applique uniquement à KMDF]

La méthode WdfLookasideListCreate crée un objet lookaside-list, à partir duquel le pilote peut obtenir des objets de mémoire.

Syntaxe

NTSTATUS WdfLookasideListCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES LookasideAttributes,
  [in]           size_t                 BufferSize,
  [in]           POOL_TYPE              PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES MemoryAttributes,
  [in, optional] ULONG                  PoolTag,
  [out]          WDFLOOKASIDE           *Lookaside
);

Paramètres

[in, optional] LookasideAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour le nouvel objet lookaside-list. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in] BufferSize

Taille différente de zéro, en octets, de la mémoire tampon que l’infrastructure allouera pour chaque objet de mémoire.

[in] PoolType

Valeur de type POOL_TYPE qui spécifie le type de mémoire à allouer.

[in, optional] MemoryAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour chaque objet mémoire que le pilote obtient à partir de la liste de recherche. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in, optional] PoolTag

Balise de pool définie par le pilote pour la mémoire tampon de chaque objet mémoire. Les débogueurs affichent cette balise. Les pilotes spécifient généralement une chaîne de caractères de quatre caractères maximum, délimitée par des guillemets simples, dans l’ordre inverse (par exemple, « dcba »). La valeur ASCII de chaque caractère de la balise doit être comprise entre 0 et 127. Le débogage de votre pilote est plus facile si chaque balise de pool est unique.

Si PoolTag est égal à zéro, l’infrastructure fournit une balise de pool par défaut qui utilise les quatre premiers caractères du nom de service en mode noyau de votre pilote. Si le nom du service commence par « WDF » (le nom ne respecte pas la casse et n’inclut pas les guillemets), les quatre caractères suivants sont utilisés. Si moins de quatre caractères sont disponibles, « FxDr » est utilisé.

Pour KMDF versions 1.5 et ultérieures, votre pilote peut utiliser le membre DriverPoolTag de la structure WDF_DRIVER_CONFIG pour spécifier une balise de pool par défaut.

[out] Lookaside

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet lookaside-list.

Valeur retournée

WdfLookasideListCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfLookasideListCreate peut retourner, consultez Erreurs de création d’objet Framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Remarques

Une fois que votre pilote a appelé WdfLookasideListCreate pour créer un objet lookaside-list, le pilote peut appeler WdfMemoryCreateFromLookaside pour obtenir une mémoire tampon à partir de la liste de lookaside.

Par défaut, le parent du nouvel objet lookaside-list est l’objet de pilote d’infrastructure créé par la méthode WdfDriverCreate . Vous pouvez utiliser le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES pour spécifier un autre parent. Le framework supprime l’objet lookaside-list lorsqu’il supprime l’objet parent. Si votre pilote ne modifie pas le parent par défaut, il doit supprimer l’objet lookaside-list lorsqu’il a terminé d’utiliser l’objet ; sinon, l’objet lookaside-list reste jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.

Si votre pilote fournit une structure WDF_OBJECT_ATTRIBUTES pour les paramètres LookasideAttributes et MemoryAttributes , et si les deux structures spécifient un objet d’appareil comme objet parent, les handles de l’objet d’appareil doivent être identiques.

Pour plus d’informations sur les objets de mémoire du framework et les listes de recherche, consultez Utilisation de mémoire tampons.

Si votre pilote spécifie PagedPool pour le paramètre PoolType , la méthode WdfLookasideListCreate doit être appelée à l’adresse IRQL <= APC_LEVEL. Sinon, la méthode peut être appelée à l’adresse IRQL <= DISPATCH_LEVEL.

Exemples

Pour obtenir un exemple de code qui utilise WdfLookasideListCreate, consultez WdfMemoryCreateFromLookaside.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfmemory.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	Consultez la section Notes.
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WDF_OBJECT_ATTRIBUTES

WdfDriverCréer

WdfMemoryCreateFromLookaside

Partager via