WdfDmaTransactionAllocateResources, fonction (wdfdmatransaction.h)

Article
03/22/2025

[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 transactionnel spécifié. Le pilote peut initialiser et lancer la transaction plusieurs fois lors de la conservation 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 WDF_DMA_DIRECTION-typée 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 cartographiques que le pilote souhaite réserver. Si zéro, l’infrastructure dérive le nombre requis de registres cartographiques à partir de la transaction initialisée.

[in] EvtReserveDmaFunction

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

[in] EvtReserveDmaContext

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

Valeur de retour

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 d’inscription de carte dépasse le nombre affecté à l’enabler, ou le pilote précédemment appelé WdfDmaTransactionSetImmediateExecution et les ressources nécessaires pour la requête ne sont pas disponibles.
STATUS_INVALID_DEVICE_REQUEST	DMA version 3 ou ultérieure n’est pas activé, ou le pilote appelé cette méthode pour un enabler DMA de collecte de points.

Remarques

WdfDmaTransactionAllocateResources envoie une demande de registres cartographiques au moteur DMA système. Une fois la demande remplie, l’infrastructure appelle la fonction de rappel d’événements 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 requêtes d’E/S . Un pilote peut également appeler WdfDmaTransactionAllocateResources à partir de son EvtDriverDeviceAdd fonction de rappel, après avoir créé un objet d’enabler DMA.

Lorsqu’elle est appelée avec un enabler DMA de nuage de points/collecte, WdfDmaTransactionAllocateResources provoque une vérification des bogues du vérificateur.

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, ce qui évite le délai qui se produirait entre les transactions, car les registres cartographiques ont été libérés vers la hal, puis réaffectés.

Un pilote peut appeler WdfDmaTransactionAllocateResources dans les situations suivantes :

Le pilote reçoit un ensemble de canaux DMA dans son EvtDevicePrepareHardware fonction de rappel. Dans EvtDevicePrepareHardware, le pilote initialise une transaction DMA et appelle WdfDmaTransactionAllocateResources pour réserver l’enabler 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’enabler.

Avant d’appeler WdfDmaTransactionAllocateResources, le pilote doit déterminer le nombre de registres cartographiques 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](.. Macro /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 cartographiques qu’il n’a demandé lors de la création de l’enabler.

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.

Spécifications

Besoin	Valeur
plateforme cible	Universel
version minimale de KMDF	1.11
En-tête	wdfdmatransaction.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	<=DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf)