PGET_DMA_TRANSFER_INFO fonction de rappel (wdm.h)

Article
08/08/2023

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

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 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 .

[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 Notes.

[in] Offset

Décalage de départ pour le transfert DMA de nuages de points/regroupements. Ce paramètre est un décalage d’octets à partir du début de la mémoire tampon dans la première MDL de la chaîne MDL. Si les DLL de la chaîne MDL spécifient un total de N octets d’espace de mémoire 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 sont comprises entre 1 et N-Offset.

[in] WriteOnly

Indique si le transfert est une opération en écriture seule (autrement dit, un transfert de mémoire vers l’appareil). 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 nécessaires aux limites de la mémoire tampon pour appliquer la cohérence du cache.

[in, out] TransferInfo

Pointeur vers une structure de 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 retournée

GetDmaTransferInfo 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_NOT_SUPPORTED	La routine ne prend pas en charge la version spécifiée de la structure DMA_TRANSFER_INFO_XXX .

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. 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.

Utilisez GetDmaTransferInfo pour calculer la taille de la mémoire tampon de nuage de points/regroupements à allouer aux routines BuildScatterGatherListEx et MapTransferEx .

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

Les paramètres Mdl, Offset et Length spécifient ensemble une collection de régions de mémoire physique à utiliser comme mémoire tampon pour un transfert DMA de points/regroupements. 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 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 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 de la liste de points/regroupements en adresses logiques.

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

Une MDL décrit les pages de mémoire physique qui sous-tendent un bloc verrouillé et contigu de mémoire virtuelle. En règle générale, ces pages de mémoire physique ne sont pas contiguës. Une chaîne MDL est une collection ordonnée de MDL 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 ne sont pas contiguës. Pour plus d’informations sur les chaînes MDL et MDL, consultez Utilisation de MDL.

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