PMAP_TRANSFER_EX fonction de rappel (wdm.h)

Article
02/29/2024

La routine MapTransferEx configure des registres de carte pour mapper les adresses physiques d’une liste de points/regroupements aux adresses logiques requises pour effectuer un transfert DMA.

Syntaxe

PMAP_TRANSFER_EX PmapTransferEx;

NTSTATUS PmapTransferEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PMDL Mdl,
  [in]            PVOID MapRegisterBase,
  [in]            ULONGLONG Offset,
  [in]            ULONG DeviceOffset,
  [in, out]       PULONG Length,
  [in]            BOOLEAN WriteToDevice,
  [out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
  [in]            ULONG ScatterGatherBufferLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext
)
{...}

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 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 une chaîne MDL qui décrit la mise en page physique d’une collection de mémoires tampons verrouillées dans la mémoire virtuelle. La liste de points/regroupements pour le transfert DMA utilise la région de cette mémoire spécifiée par les paramètres Offset et Length . Pour plus d’informations sur les chaînes MDL, consultez Utilisation de MDL.

[in] MapRegisterBase

Un handle dans les registres de carte qui sont alloués pour l’objet adaptateur. L’appelant a précédemment obtenu ce handle à partir de la routine AllocateAdapterChannelEx .

[in] Offset

Décalage d’octet par rapport au début de la mémoire décrite par la chaîne MDL. Ce décalage spécifie le début de la mémoire tampon de données d’E/S utilisée pour le transfert DMA. Si une liste de points/regroupements est fournie à l’appelant, ce décalage détermine l’adresse de départ du premier fragment de mémoire tampon de la liste. Si les dll MDL de la chaîne MDL décrivent un total de N octets de mémoire, les valeurs valides de Décalage sont comprises entre 0 et N–1. Pour plus d'informations, consultez la section Notes.

[in] DeviceOffset

Décalage d’octet du registre de données ou FIFO de l’appareil cible à partir de l’adresse de base de l’appareil. Ce paramètre s’applique aux appareils qui ont plusieurs FIFO accessibles par un contrôleur DMA système. Ce paramètre est utilisé uniquement pour les transferts DMA système. Pour les transferts master bus, définissez ce paramètre sur zéro.

[in, out] Length

Pointeur vers une variable qui contient la longueur, en octets, de la mémoire tampon de données d’E/S utilisée pour le transfert DMA. Lors de l’entrée, cette variable contient la longueur demandée par le pilote appelant. Avant de retourner, la routine écrit la longueur réelle de la mémoire tampon mappée dans cette variable. La valeur *Length lors du retour de MapTransferEx indique le nombre d’octets mappés. Si le nombre de registres de carte et la taille de la mémoire tampon de diffusion/de collecte sont suffisants pour mapper toute la longueur demandée par l’appelant, les valeurs d’entrée et de sortie de *Length sont identiques. Si les dll MDL de la chaîne MDL décrivent un total de N octets de mémoire, les valeurs valides de *Length sont comprises entre 0 et N-Offset.

[in] WriteToDevice

Direction du transfert DMA. Définissez ce paramètre sur TRUE pour une opération d’écriture, qui transfère des données à l’appareil à partir de la mémoire. Définissez ce paramètre sur FALSE pour une opération de lecture, qui transfère des données de l’appareil vers la mémoire.

[out, optional] ScatterGatherBuffer

Pointeur vers une mémoire tampon allouée à l’appelant dans laquelle la routine écrit la liste de points/regroupements pour le transfert DMA. Cette liste commence par une structure SCATTER_GATHER_LIST , qui est immédiatement suivie d’un tableau SCATTER_GATHER_ELEMENT . Pour un pilote qui utilise un périphérique DMA master bus, ScatterGatherBuffer est un paramètre obligatoire. Pour un pilote qui utilise un contrôleur DMA système, le paramètre ScatterGatherBuffer est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes.

[in] ScatterGatherBufferLength

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre ScatterGatherBuffer . La taille de la mémoire tampon allouée doit être suffisamment grande pour contenir la liste de points/regroupements, ainsi que les données internes que le système d’exploitation stocke dans cette mémoire tampon. Pour déterminer la taille de mémoire tampon requise, appelez la routine GetDmaTransferInfo ou CalculateScatterGatherList . Si ScatterGatherBuffer a la valeur NULL, définissez ScatterGatherBufferLength sur zéro.

[in, optional] DmaCompletionRoutine

Pointeur vers une routine DmaCompletionRoutine fournie par l’appelant à appeler une fois le transfert DMA terminé. Cette routine est appelée si l’appareil cible utilise un contrôleur DMA système qui génère une interruption d’achèvement DMA. La routine DmaCompletionRoutine est appelée à DISPATCH_LEVEL une fois le transfert DMA terminé. Pour un adaptateur DMA système, ce paramètre est facultatif et peut avoir la valeur NULL. Pour un adaptateur master bus, définissez ce paramètre sur NULL.

[in, optional] CompletionContext

Contexte déterminé par le pilote pour la routine DmaCompletionRoutine . Ce contexte est fourni en tant que paramètre CompletionContext à la routine DmaCompletionRoutine . Si le paramètre DmaCompletionRoutine a la valeur NULL, définissez CompletionContext surNULL.

Valeur retournée

MapTransferEx 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	La routine a échoué en raison de valeurs de paramètre non valides transmises par l’appelant.
STATUS_BUFFER_TOO_SMALL	La mémoire tampon fournie par l’appelant dans ScatterGatherBuffer est trop petite pour contenir la liste de points/regroupements.
STATUS_INSUFFICIENT_RESOURCES	La routine n’a pas pu allouer les ressources requises pour le transfert DMA.
STATUS_CANCELLED	Ce transfert a été annulé.

Remarques

MapTransferEx n’est pas une routine système qui peut être appelée directement par nom. Cette routine peut être appelée uniquement par un pointeur à partir 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.

Pour un transfert qui utilise un contrôleur DMA système, l’appelant peut, en option, fournir une routine de rappel DmaCompletionRoutine appelée à la fin du transfert. Le système d’exploitation planifie ce rappel en réponse à l’interruption d’achèvement DMA du contrôleur DMA système.

Le nombre de registres de carte qui peuvent être configurés par MapTransferEx ne peut pas dépasser le nombre maximal que le pilote a obtenu à partir d’IoGetDmaAdapter.

Les paramètres Mdl, Offset et Length décrivent la mémoire tampon de données d’E/S pour le transfert DMA demandé. Le nombre de registres de carte alloués peut ne pas être suffisant pour mapper toute la mémoire de cette mémoire tampon, ou la mémoire tampon de diffusion/collecte pointée par ScatterGatherBuffer peut ne pas être assez grande pour décrire la mémoire tampon entière. MapTransferEx écrit une valeur de sortie dans *Length pour indiquer au pilote quelle quantité de mémoire tampon pour le transfert DMA demandé a été mappée par la routine. La routine écrit une liste de points/regroupements dans la mémoire tampon pointée par ScatterGatherBuffer. Cette liste décrit les fragments de mémoire tampon qui ont été correctement mappés par la routine.

Si un appel à MapTransferEx réussit, MapTransferEx écrit la valeur de sortie *Length avant qu’elle ne retourne. Si l’appelant spécifie un DmaCompletionRoutine, la valeur de sortie *Length mise à jour est toujours écrite avant l’exécution de DmaCompletionRoutine . Pour plus d’informations, consultez Appels multiples à MapTransferEx.

Le paramètre Offset spécifie le décalage de départ dans la chaîne MDL qui décrit la mémoire dans la mémoire tampon de données d’E/S. Par exemple, supposons que la chaîne MDL contient deux MDL, MDL₁ et MDL₂, et que MDL₁ décrit N₁ octets de mémoire, et MDL₂ décrit les N octets. Si Offset = N, où N₁ < N < ₁ + N₂, la mémoire tampon ne contient aucune mémoire décrite par MDL₁ et commence à un décalage de N - N₁ octets dans la mémoire décrite par MDL₂.

Si le transfert utilise un contrôleur DMA système, l’appelant peut définir ScatterGatherBuffer = NULL, auquel cas MapTransferEx utilise une mémoire tampon par défaut allouée en interne pour contenir la liste de points/regroupements. La mémoire tampon par défaut est garantie pour être suffisamment grande pour contenir une liste de points/regroupements d’au moins un élément. Si la mémoire tampon par défaut est utilisée pour un transfert de points/regroupements de nombreux éléments, de nombreux appels à MapTransferEx peuvent être nécessaires pour terminer le transfert. Si le matériel du contrôleur DMA prend en charge les transferts de diffusion/collecte, l’utilisation de la mémoire tampon par défaut peut dégrader les performances.

Si ScatterGatherBuffer n’a pas la valeur NULL et que ScatterGatherBufferSize spécifie une taille trop petite pour contenir une liste de points/regroupement d’au moins un élément, MapTransferEx échoue et retourne STATUS_INVALID_PARAMETER.

MapTransferEx est une version étendue de la routine MapTransfer . La version étendue présente les avantages suivants :

MapTransferEx peut traiter tous les fragments de mémoire tampon d’une chaîne MDL en un seul appel, mais MapTransfer ne peut traiter qu’un seul fragment de mémoire tampon contiguë physiquement par appel.
MapTransferEx peut générer une liste de points/regroupements entière en un seul appel, mais MapTransfer ne peut générer qu’un seul élément de liste de points/regroupements par appel.
MapTransferEx peut mapper tous les fragments de mémoire tampon d’une liste de points/regroupements en un seul appel, mais MapTransfer ne peut mapper qu’un seul fragment de mémoire tampon contiguë physiquement par appel.
MapTransferEx nécessite uniquement le décalage de départ pour l’ensemble de la liste de points/regroupements, mais MapTransfer nécessite une adresse virtuelle de démarrage pour chaque fragment de mémoire tampon contiguë physiquement.
Un appel MapTransferEx peut mapper une mémoire tampon qui s’étend via une ou plusieurs MDL, mais un appel MapTransfer ne peut mapper qu’un seul fragment de mémoire tampon contiguë physiquement dans la mémoire qui est décrit par un MDL.
Pour un transfert DMA système, MapTransferEx permet à l’appelant de fournir une routine de rappel DmaCompletionRoutine pour recevoir une notification une fois le transfert terminé, mais MapTransfer ne permet pas d’avertir l’appelant lorsqu’un transfert DMA se termine.

Chaque appel réussi à MapTransferEx doit être suivi d’un appel correspondant à la routine FlushAdapterBuffersEx . L’appel FlushAdapterBuffersEx qui suit un appel MapTransferEx doit se produire avant l’appel MapTransferEx suivant. L’appel FlushAdapterBuffersEx est requis même si un appel à la routine CancelMappedTransfer réussit à annuler le transfert mappé demandé par l’appel MapTransferEx précédent.

Pour plus d’informations, consultez Utilisation de la routine MapTransferEx.

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 (inclure Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL