WdfCommonBufferCreate, fonction (wdfcommonbuffer.h)

[S’applique uniquement à KMDF]

La méthode WdfCommonBufferCreate crée une mémoire tampon de mémoire que 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 vers un objet d’activation DMA que le pilote 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 les attributs d’objet pour l’objet tampon commun. (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 typée WDFCOMMONBUFFER qui reçoit un handle vers un objet tampon commun.

Valeur de retour

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

Une vérification de bogue 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 appelle 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.

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 de mots. Si votre pilote crée plusieurs enablers DMA, chacun avec une exigence d’alignement de la 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 spécifié 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 à allouer. Cette décision est basée sur l’architecture du processeur et le bus d’appareil.

Sur les ordinateurs dotés de processeurs x86, x64 et Itanium, la mémoire mise en cache est activée. Sur les ordinateurs doté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 pour déterminer si l’appareil est cohérent avec le cache.

Objet d’activation DMA que le paramètre DmaEnabler de WdfCommonBufferCreate spécifie devient l’objet parent pour le nouvel objet de mémoire tampon commun. Le pilote ne peut pas modifier ce parent et le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES doit être NULL. L’infrastructure 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 commun en appelant WdfObjectDelete.

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

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 de contexte 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); 
}

Exigences

Voir aussi

EvtDriverDeviceAdd

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreateWithConfig

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate