WdfDmaEnablerCreate, fonction (wdfdmaenabler.h)

[S’applique à KMDF uniquement]

La méthode WdfDmaEnablerCreate crée un objet enabler DMA.

Syntaxe

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

Paramètres

[in] Device

Handle pour un objet d’appareil d’infrastructure.

[in] Config

Pointeur vers une structure WDF_DMA_ENABLER_CONFIG . Les pilotes doivent initialiser cette structure en appelant WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui spécifie les attributs d’objet pour le nouvel objet d’activation DMA. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Handle d’un nouvel objet d’activation DMA.

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante pour construire un nouvel objet d’activation DMA.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_DMA_ENABLER_CONFIG est incorrecte.
STATUS_NOT_SUPPORTED	Le pilote a demandé DMA version 3 sur un système d’exploitation antérieur à Windows 8.

 

Pour obtenir la liste des autres valeurs de retour que la méthode WdfDmaEnablerCreate peut retourner, consultez Erreurs de création d’objets framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

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

Remarques

Les pilotes basés sur l’infrastructure doivent appeler WdfDmaEnablerCreate avant de créer des transactions DMA pour un appareil.

Avant qu’un pilote appelle WdfDmaEnablerCreate, il doit appeler WdfDeviceSetAlignmentRequirement.

L’objet d’appareil framework que le paramètre Device de WdfDmaEnablerCreate spécifie devient toujours l’objet parent pour le nouvel objet d’activation DMA. Si le pilote spécifie un autre parent dans le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES , l’infrastructure ignore cette valeur. L’infrastructure supprime l’objet enabler DMA lorsqu’il supprime l’objet parent.

Lorsqu’il est appelé avec un paramètre Config qui demande un profil DMA en mode système, WdfDmaEnablerCreate crée un enabler DMA partiellement initialisé. Le pilote doit ensuite appeler WdfDmaEnablerConfigureSystemProfile pour configurer les paramètres DMA pour les canaux sous-jacents.

Pour plus d’informations sur les objets d’activation DMA et WdfDmaEnablerCreate, consultez Activation des transactions DMA.

Exemples

L’exemple de code suivant provient de l’exemple de pilote PLX9x5x . Cet exemple définit les exigences d’un appareil pour l’alignement de la mémoire tampon, initialise une structure WDF_DMA_ENABLER_CONFIG et appelle WdfDmaEnablerCreate.

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfdmaenabler.h (inclure Wdf.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

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement