Partager via

WdfCommonBufferCreateWithConfig, fonction (wdfcommonbuffer.h)

[S’applique uniquement à KMDF]

La méthode WdfCommonBufferCreateWithConfig crée une mémoire tampon que le pilote et un appareil d’accès direct à la mémoire (DMA) peuvent accéder simultanément, et la méthode spécifie également des informations de configuration de 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 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.

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

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

Retourner le code Description
STATUS_INVALID_PARAMETER
 Le pilote a fourni un paramètre non valide.
STATUS_INSUFFICIENT_RESOURCES
 L’infrastructure n’a pas pu allouer d’objet de mémoire tampon commun, ou le système n’a pas pu allouer de mémoire tampon.
 

Une vérification de bogue 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 la 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 qui a une exigence d’alignement différente de celle qui WdfDeviceSetAlignmentRequirement spécifiée.

Une fois que votre pilote appelle WdfCommonBufferCreateWithConfig, le pilote doit :

Un pilote appelle généralement WdfCommonBufferCreateWithConfig à partir de son EvtDriverDeviceAdd fonction de rappel.

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.

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

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;
}

Exigences

Exigence Valeur
plateforme cible Universel
version minimale de KMDF 1.1
d’en-tête wdfcommonbuffer.h (include WdfCommonBuffer.h)
bibliothèque Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
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

  • Last updated on