Partager via


WdfCommonBufferCreateWithConfig, fonction (wdfcommonbuffer.h)

[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 :

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)

Voir aussi

EvtDriverDeviceAdd

WDF_COMMON_BUFFER_CONFIG

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreate

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate