PINITIALIZE_DMA_TRANSFER_CONTEXT fonction de rappel (wdm.h)

Article
02/29/2024

La routine InitializeDmaTransferContext initialise un contexte de transfert DMA opaque qui est utilisé pour suivre les allocations en attente de ressources DMA.

Syntaxe

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers une structure DMA_ADAPTER . Cette structure est l’objet adaptateur qui représente le périphérique DMA master bus ou le canal DMA système du pilote. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter .

[out] DmaTransferContext

Pointeur vers une mémoire tampon allouée à l’appelant dans laquelle InitializeDmaTransferContext écrit les valeurs initiales pour le contexte de transfert DMA. Ce contexte est opaque pour l’appelant. L’appelant doit allouer une mémoire tampon suffisamment grande pour contenir le contexte de transfert DMA. La taille, en octets, de ce contexte est spécifiée par la constante DMA_TRANSFER_CONTEXT_SIZE_V1 dans le fichier d’en-tête Wdm.h.

Valeur retournée

InitializeDmaTransferContext retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes status suivants.

Code de retour	Description
STATUS_INVALID_PARAMETERS	Cette routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant.

Remarques

InitializeDmaTransferContext n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par le pointeur de l’adresse retournée dans une structure DMA_OPERATIONS. Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre Version du paramètre DeviceDescription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

Un contexte de transfert DMA initialisé doit être fourni en tant que paramètre à la routine AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx . Chacune de ces routines écrit des informations sur l’allocation de ressources DMA demandée dans le contexte de transfert DMA. Ces informations sont opaques pour l’appelant. Pour annuler une demande d’allocation en attente, l’appelant doit fournir le contexte de transfert DMA pour la demande à la routine CancelAdapterChannel .

Le contexte de transfert DMA fourni à AllocateAdapterChannelEx, GetScatterGatherListEx ou BuildScatterGatherListEx doit être unique dans toutes les demandes d’allocation d’adaptateur.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL