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 |
|---|---|
|
Un paramètre non valide a été détecté. |
|
La mémoire était insuffisante pour construire un nouvel objet d’activation DMA. |
|
La taille de la structure WDF_DMA_ENABLER_CONFIG est incorrecte. |
|
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) |