Fonction WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Article
08/08/2023

[S’applique uniquement à KMDF]

La méthode WdfDmaTransactionAllocateResources réserve un enabler DMA à paquet unique ou en mode système pour une utilisation exclusive (et répétée) avec l’objet de transaction spécifié. Le pilote peut initialiser et lancer la transaction plusieurs fois tout en conservant des ressources réservées.

Syntaxe

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Paramètres

[in] DmaTransaction

Handle de l’objet de transaction DMA pour lequel les ressources DMA doivent être réservées.

[in] DmaDirection

Valeur de type WDF_DMA_DIRECTION spécifiant le sens de transfert DMA pour lequel les ressources sont réservées. Si le pilote n’a pas spécifié de profil duplex, l’infrastructure ignore cette valeur.

[in] RequiredMapRegisters

Nombre d’inscriptions de carte que le conducteur souhaite réserver. Si zéro, l’infrastructure dérive le nombre requis de registres de carte de la transaction initialisée.

[in] EvtReserveDmaFunction

Pointeur vers la fonction de rappel d’événement EvtReserveDma du pilote.

[in] EvtReserveDmaContext

Pointeur vers une mémoire tampon contenant le contexte à fournir à la fonction de rappel d’événement EvtReserveDma du pilote.

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Le paramètre DmaDirection contient une valeur non valide.
STATUS_INSUFFICIENT_RESOURCES	Le nombre de demandes de registre de carte dépasse le nombre attribué à l’enabler, ou le pilote précédemment appelé WdfDmaTransactionSetImmediateExecution et les ressources nécessaires à la demande ne sont pas disponibles.
STATUS_INVALID_DEVICE_REQUEST	DMA version 3 ou ultérieure n’est pas activé, ou le pilote a appelé cette méthode pour un enabler DMA de collecte de points.

Remarques

WdfDmaTransactionAllocateResources envoie une demande de registres de carte au moteur DMA système. Une fois la demande remplie, l’infrastructure appelle la fonction de rappel d’événement EvtReserveDma du pilote. Pour plus d’informations sur la réservation de ressources, consultez Réserver des ressources DMA.

Les pilotes basés sur l’infrastructure appellent généralement WdfDmaTransactionAllocateResources à partir d’un gestionnaire de demandes d’E/S. Un pilote peut également appeler WdfDmaTransactionAllocateResources à partir de sa fonction de rappel EvtDriverDeviceAdd , après avoir créé un objet d’activation DMA.

Lorsqu’il est appelé avec un enabler DMA de diffusion/collecte, WdfDmaTransactionAllocateResources provoque un bogue de vérificateur case activée.

Le pilote doit créer la transaction spécifiée par DmaTransaction avant d’appeler WdfDmaTransactionAllocateResources. Après avoir appelé WdfDmaTransactionAllocateResources, le pilote initialise et lance la transaction. Le pilote peut réinitialiser et réinitialiser le même objet de transaction plusieurs fois, évitant ainsi le délai qui se produirait entre les transactions, car les registres de carte ont été libérés dans le HAL, puis réalloués.

Un pilote peut appeler WdfDmaTransactionAllocateResources dans les situations suivantes :

Le pilote reçoit un ensemble de canaux DMA dans sa fonction de rappel EvtDevicePrepareHardware . Dans EvtDevicePrepareHardware, le pilote initialise une transaction DMA et appelle WdfDmaTransactionAllocateResources pour réserver l’activation pour une utilisation exclusive avec cette transaction. Le pilote peut également appeler WdfDmaTransactionAllocateResources à partir d’un gestionnaire de requêtes , puis lancer la transaction plusieurs fois.
Le pilote doit effectuer une série de transactions sur l’enabler. Le pilote réserve l’enabler, initialise et lance plusieurs transactions à l’aide du même objet de transaction, puis libère l’activation.

Avant d’appeler WdfDmaTransactionAllocateResources, le pilote doit déterminer le nombre de registres de carte nécessaires pour toute transaction qu’il lancera à l’aide de cette réservation. Pour ce faire, le pilote peut appeler le [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. /wdm/nf-wdm-address_and_size_to_span_pages.md) ou WdfDmaTransactionGetTransferInfo.

Lors de l’appel de WdfDmaTransactionAllocateResources, le pilote ne doit pas demander plus de registres de carte qu’il n’en avait demandé lors de la création de l’activation.

Pour appeler WdfDmaTransactionAllocateResources de manière non bloquante, le pilote doit d’abord appeler WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources nécessite DMA version 3. Pour sélectionner DMA version 3, définissez le membre WdmDmaVersionOverride de WDF_DMA_ENABLER_CONFIG sur 3.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.11
En-tête	wdfdmatransaction.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf)