WdfCommonBufferCreate, fonction (wdfcommonbuffer.h)

Article
03/01/2024

[S’applique à KMDF uniquement]

La méthode WdfCommonBufferCreate crée une mémoire tampon à laquelle le pilote et un appareil d’accès direct à la mémoire (DMA) peuvent accéder simultanément.

Syntaxe

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

Paramètres

[in] DmaEnabler

Handle pour un objet enabler DMA que le pilote a obtenu par un appel précédent à WdfDmaEnablerCreate.

[in] Length

Taille souhaitée, en octets, de la nouvelle mémoire tampon. La taille maximale autorisée de la mémoire tampon est (MAXULONG - PAGE_SIZE) octets.

[in, optional] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui spécifie des attributs d’objet pour l’objet de mémoire tampon commune. (Le membre ParentObject de la structure doit être NULL.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

Pointeur vers une variable de type WDFCOMMONBUFFER qui reçoit un handle vers un objet de mémoire tampon commun.

Valeur retournée

WdfCommonBufferCreate 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	Le pilote a fourni un paramètre non valide.
STATUS_INSUFFICIENT_RESOURCES	Le framework n’a pas pu allouer un objet de mémoire tampon commun ou le système n’a pas pu allouer de mémoire tampon.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfCommonBufferCreate alloue de la mémoire et la mappe afin que le pilote et un appareil puissent y accéder simultanément pour les opérations DMA. Une fois que votre pilote a appelé WdfCommonBufferCreate, le pilote doit :

Appelez WdfCommonBufferGetAlignedVirtualAddress pour obtenir l’adresse virtuelle de la mémoire tampon, que le pilote peut utiliser.
Appelez WdfCommonBufferGetAlignedLogicalAddress pour obtenir l’adresse logique de la mémoire tampon, que l’appareil peut utiliser.

Un pilote appelle généralement WdfCommonBufferCreate à partir de sa fonction de rappel EvtDriverDeviceAdd .

Avant que le pilote appelle WdfDmaEnablerCreate, il peut appeler WdfDeviceSetAlignmentRequirement pour définir une exigence d’alignement de la mémoire tampon. Si le pilote n’appelle pas WdfDeviceSetAlignmentRequirement, les mémoires tampons sont alignées sur les limites des mots. Si votre pilote crée plusieurs enablers DMA, chacun avec une exigence d’alignement de mémoire tampon différente, le pilote peut appeler WdfDeviceSetAlignmentRequirement avant chaque appel à WdfDmaEnablerCreate.

Pour créer une mémoire tampon commune qui a une exigence d’alignement différente de l’exigence d’alignement spécifiée par le pilote avec WdfDeviceSetAlignmentRequirement, le pilote peut appeler WdfCommonBufferCreateWithConfig au lieu de WdfCommonBufferCreate.

Le système d’exploitation détermine s’il faut activer la mémoire mise en cache dans la mémoire tampon commune qui doit être allouée. Cette décision est basée sur l’architecture du processeur et le bus d’appareil.

Sur les ordinateurs équipés de processeurs x86, x64 et Itanium, la mémoire mise en cache est activée. Sur les ordinateurs équipés de processeurs ARM ou ARM 64, le système d’exploitation n’active pas automatiquement la mémoire mise en cache pour tous les appareils. Le système s’appuie sur la méthode ACPI_CCA pour chaque appareil afin de déterminer si l’appareil est cohérent dans le cache.

L’objet d’activation DMA spécifié par le paramètre DmaEnabler de WdfCommonBufferCreate devient l’objet parent du nouvel objet de mémoire tampon commune. Le pilote ne peut pas modifier ce parent, et le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES doit avoir la valeur NULL. Le framework supprime chaque objet de mémoire tampon commun lorsqu’il supprime l’objet d’activation DMA parent. Vous pouvez également supprimer explicitement l’objet de mémoire tampon commune en appelant WdfObjectDelete.

Pour plus d’informations sur les mémoires tampons courantes, consultez Utilisation de mémoires tampons communes.

Exemples

L’exemple de code suivant montre comment obtenir une mémoire tampon commune. L’exemple stocke des informations sur la mémoire tampon commune dans l’espace contextuel défini par le pilote identifié par le pointeur DevExt .

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfcommonbuffer.h (inclure WdfCommonBuffer.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)