PMAP_TRANSFER_EX fonction de rappel (wdm.h)
La routine MapTransferEx configure des registres de carte pour mapper les adresses physiques dans une liste de points/regroupements aux adresses logiques requises pour effectuer un transfert DMA.
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
)
{...}
[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 une chaîne MDL qui décrit la mise en page physique d’une collection de mémoires tampons verrouillées en 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 Longueur. Pour plus d’informations sur les chaînes MDL, consultez Utilisation de MDLs.
[in] MapRegisterBase
Handle pour les registres cartographiques alloués pour l’objet adaptateur. L’appelant a obtenu précédemment ce handle à partir de la routine AllocateAdapterChannelEx.
[in] Offset
Décalage d’octets à partir du 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 MDL de la chaîne MDL décrivent un total de N octets de mémoire, les valeurs valides de offset sont comprises entre 0 et N-1. Pour plus d’informations, consultez Remarques.
[in] DeviceOffset
Décalage d’octets du registre de données de l’appareil cible ou FIFO à 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 bus-master, 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 de *Length à retour de MapTransferEx indique le nombre d’octets mappés. Si le nombre de registres de carte et la taille de mémoire tampon de nuage de points/collecte sont suffisants pour mapper la longueur entière demandée par l’appelant, les valeurs d’entrée et de sortie de *Longueur sont identiques. Si les MDL de la chaîne MDL décrivent un total de N octets de mémoire, les valeurs valides de *Longueur se trouvent dans la plage 0 à N –Offset.
[in] WriteToDevice
Direction du transfert DMA. Définissez ce paramètre sur TRUE pour une opération d’écriture, qui transfère les 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 les données de l’appareil en mémoire.
[out, optional] ScatterGatherBuffer
Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la routine écrit la liste de nuages de points/collecte 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 maître de 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 Remarques.
[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 stockées par le système d’exploitation dans cette mémoire tampon. Pour déterminer la taille de mémoire tampon requise, appelez la routine GetDmaTransferInfo ou CalculateScatterGatherList routine. Si ScatterGatherBuffer est NULL, définissez ScatterGatherBufferLength sur zéro.
[in, optional] DmaCompletionRoutine
Pointeur vers un appelant fourni DmaCompletionRoutine routine à appeler lorsque le transfert DMA se termine. 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 être NULL. Pour un adaptateur maître de 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 est NULL, définissez completionContext sur NULL.
MapTransferEx 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 |
|---|---|
|
La routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant. |
|
La mémoire tampon fournie par l’appelant dans ScatterGatherBuffer est trop petite pour contenir la liste de nuages de points/regroupements. |
|
La routine n’a pas pu allouer de ressources requises pour le transfert DMA. |
|
Ce transfert a été annulé. |
MapTransferEx 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.
Pour un transfert qui utilise un contrôleur DMA système, l’appelant peut, en tant qu’option, fournir une DmaCompletionRoutine routine de rappel 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 cartographiques pouvant être configurés par MapTransferEx ne peut pas dépasser le maximum que le pilote obtenu à partir de IoGetDmaAdapter.
Les paramètres Mdl, Offsetet 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 suffire pour mapper l’ensemble de la mémoire dans cette mémoire tampon, ou la mémoire tampon de nuages de points/collecte vers laquelle pointe ScatterGatherBuffer peut ne pas être suffisamment volumineux pour décrire l’intégralité de la mémoire tampon. MapTransferEx écrit une valeur de sortie dans *Length pour indiquer au pilote la quantité de mémoire tampon pour le transfert DMA demandé mappé par la routine. La routine écrit une liste de nuages 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 de retourner. Si l’appelant spécifie un DmaCompletionRoutine, la valeur de sortielongueur mise à jour est toujours écrite avant l’exécution du DmaCompletionRoutine. Pour plus d’informations, consultez Plusieurs appels à 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 n’octets. Si Offset = N, où N₁ < 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 allouée en interne pour contenir la liste de points/collecter. La mémoire tampon par défaut est garantie d’ê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 nuages/de collecte de nombreux éléments, de nombreux appels à MapTransferEx peuvent être nécessaires pour effectuer le transfert. Si le matériel du contrôleur DMA prend en charge les transferts de nuages/collectes, l’utilisation de la mémoire tampon par défaut peut dégrader les performances.
Si ScatterGatherBuffer n’est pas NULL et ScatterGatherBufferSize spécifie une taille trop petite pour contenir une liste de nuages de points/regroupements 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 pouvez traiter tous les fragments de mémoire tampon dans 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 nuages de points/regroupements dans 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 dans une liste de nuages de points/regroupements dans 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’intégralité de la liste de nuages 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 un ou plusieurs MDL, mais un appel MapTransfer ne peut mapper qu’un seul fragment de mémoire tampon contiguë physiquement dans la mémoire décrite par un MDL.
- Pour un transfert DMA système, MapTransferEx permet à l’appelant de fournir un DmaCompletionRoutine routine de rappel pour recevoir une notification une fois le transfert terminé, mais MapTransfer ne fournit pas de moyen d’avertir l’appelant lorsqu’un transfert DMA se termine.
Pour plus d’informations, consultez Using the MapTransferEx Routine.
| 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 |