WdfCommonBufferCreateWithConfig, fonction (wdfcommonbuffer.h)

Article
02/26/2024

[S’applique à KMDF uniquement]

La méthode WdfCommonBufferCreateWithConfig crée une mémoire tampon à laquelle le pilote et un périphérique d’accès direct à la mémoire (DMA) peuvent accéder simultanément, et la méthode spécifie également les informations de configuration de la mémoire tampon.

Syntaxe

NTSTATUS WdfCommonBufferCreateWithConfig(
  [in]           WDFDMAENABLER             DmaEnabler,
  [in]           size_t                    Length,
  [in]           PWDF_COMMON_BUFFER_CONFIG Config,
  [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.

[in] Config

Pointeur vers une structure WDF_COMMON_BUFFER_CONFIG qui contient des informations de configuration sur la mémoire tampon.

[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

WdfCommonBufferCreateWithConfig 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 WdfCommonBufferCreateWithConfig 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.

En outre, WdfCommonBufferCreateWithConfig permet à votre pilote de spécifier une exigence d’alignement de mémoire tampon pour la mémoire tampon. L’exigence d’alignement de la mémoire tampon remplace l’exigence d’alignement de la mémoire tampon spécifiée par le pilote lorsqu’il a appelé WdfDeviceSetAlignmentRequirement. Votre pilote peut utiliser WdfCommonBufferCreateWithConfig au lieu de WdfCommonBufferCreate, si vous souhaitez que le pilote crée une mémoire tampon dont l’exigence d’alignement est différente de celle spécifiée par WdfDeviceSetAlignmentRequirement .

Une fois que votre pilote a appelé WdfCommonBufferCreateWithConfig, 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 WdfCommonBufferCreateWithConfig à partir de sa fonction de rappel EvtDriverDeviceAdd .

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.

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

Exemples

L’exemple de code suivant initialise une structure WDF_COMMON_BUFFER_CONFIG , puis crée une mémoire tampon de 10 octets alignée sur une limite de 32 octets.

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1,1
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)