PGET_DMA_TRANSFER_INFO fonction de rappel (wdm.h)

Article
02/07/2025

La routine GetDmaTransferInfo calcule les exigences d’allocation d’un transfert DMA de nuages de points/collecte.

Syntaxe

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

Paramètres

[in] DmaAdapter

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

[in] Mdl

Pointeur vers la chaîne MDL qui décrit les pages de mémoire à transférer. Pour plus d’informations, consultez la section Remarques.

[in] Offset

Décalage de départ pour le transfert DMA de nuages de points/collecte. Ce paramètre est un décalage d’octets à partir du début de la mémoire tampon dans le premier MDL de la chaîne MDL. Si les MDL de la chaîne MDL spécifient un total de N octets d’espace tampon, les valeurs valides de offset sont comprises entre 0 et N-1.

[in] Length

Longueur, en octets, du transfert DMA. Si la chaîne MDL spécifie un total de N octets d’espace tampon, les valeurs valides de Longueur se trouvent dans la plage 1 à N –Offset.

[in] WriteOnly

Indique si le transfert est une opération en écriture seule (autrement dit, un transfert vers l’appareil à partir de la mémoire). Si writeOnly a la valeur TRUE, les informations retournées sur le transfert peuvent ne pas être valides pour une transaction de lecture. Ce paramètre peut indiquer que des opérations de contrôle de cache supplémentaires sont requises aux limites de la mémoire tampon pour appliquer la cohérence du cache.

[in, out] TransferInfo

Pointeur vers une structure DMA_TRANSFER_INFO allouée par l’appelant. L’appelant doit définir le membre Version de la structure sur DMA_TRANSFER_INFO_VERSION1 avant d’appeler GetDmaTransferInfo.

Valeur de retour

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

Retourner le code	Description
STATUS_NOT_SUPPORTED	La routine ne prend pas en charge la version spécifiée de la structureXXX DMA_TRANSFER_INFO_.

Remarques

GetDmaTransferInfo 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. Pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter avec le membre version du paramètre DeviceDes cription défini sur DEVICE_DESCRIPTION_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

Utilisez GetDmaTransferInfo pour calculer la taille de la mémoire tampon de nuages de points/collecte à allouer pour les routines BuildScatterGatherListEx et MapTransferEx.

GetDmaTransferInfo remplace la routine CalculateScatterGatherList et est plus pratique à utiliser avec BuildScatterGatherListEx.

Les paramètres Mdl, Offsetet Length spécifient ensemble une collection de régions de mémoire physique à utiliser comme mémoire tampon pour un transfert DMA de nuages de points/collecte. Chaque région de mémoire physique est généralement une page ou une partie d’une page. GetDmaTransferInfo détermine les exigences d’allocation pour ce transfert. Ces exigences sont les suivantes :

Nombre d’éléments dans la liste de nuages de points/regroupements. Chaque élément est une structure SCATTER_GATHER_ELEMENT qui décrit un bloc de mémoire physiquement contigu.
Quantité de mémoire à allouer pour contenir la liste de points/regroupements spécifiée. (Cette allocation de mémoire inclut l’espace requis pour la liste de nuages de points/regroupements qui décrit la mémoire tampon d’E/S, mais pas pour la mémoire tampon d’E/S elle-même.)
Nombre de registres cartographiques requis pour traduire les adresses physiques dans la liste de nuages de points/collecte en adresses logiques.

Pour plus d’informations sur les informations de transfert DMA fournies par la version 1 de la structurexxx DMA_TRANSFER_INFO_, consultez DMA_TRANSFER_INFO_V1.

Un MDL décrit les pages de mémoire physique qui sous-tendent un bloc de mémoire virtuelle verrouillé et contigu. En règle générale, ces pages de mémoire physique sont non contiguës. Une chaîne MDL est une collection ordonnée de DLL qui décrit la mémoire qui peut être utilisée pour mettre en mémoire tampon les données d’E/S. En règle générale, les régions de mémoire virtuelle décrites par les DLL dans la chaîne sont non contiguës. Pour plus d’informations sur les chaînes MDL et MDL, consultez Utilisation de MDLs.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible à partir de Windows 8.
plateforme cible	Bureau
d’en-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL