PGET_SCATTER_GATHER_LIST_EX fonction de rappel (wdm.h)

La routine GetScatterGatherListEx alloue les ressources requises pour un transfert DMA, génère une liste de points/regroupements et appelle la routine AdapterListControl fournie par le pilote pour lancer le transfert DMA.

Note N’appelez pas cette routine pour un appareil DMA système.
 

Syntaxe

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Paramètres

[in] DmaAdapter

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

[in] DeviceObject

Pointeur vers une structure DEVICE_OBJECT . Cette structure est l’objet d’appareil physique (PDO) qui représente l’appareil cible pour l’opération DMA demandée.

[in] DmaTransferContext

Pointeur vers un contexte de transfert DMA initialisé. Ce contexte a été initialisé par un appel précédent à la routine InitializeDmaTransferContext . Ce contexte doit être unique dans toutes les demandes d’allocation d’adaptateur. Pour annuler une demande d’allocation en attente, l’appelant doit fournir le contexte de transfert DMA pour la requête à la routine CancelAdapterChannel .

[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 Length . Pour plus d’informations sur les chaînes MDL, consultez Utilisation de MDLs.

[in] Offset

Décalage de départ pour le transfert DMA de nuages/collecte. Ce paramètre est un décalage d’octet 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 se trouvent dans la plage 0 à 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 dans la plage 1 à N-Offset.

[in] Flags

Indicateurs d’allocation de canal d’adaptateur. L’indicateur suivant est pris en charge.

Indicateur Signification
DMA_SYNCHRONOUS_CALLBACK
La routine GetScatterGatherListEx est appelée de façon synchrone. Si cet indicateur est défini et que les ressources DMA requises ne sont pas immédiatement disponibles, l’appel échoue et retourne STATUS_INSUFFICIENT_RESOURCES.
 

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, le paramètre ExecutionRoutine est facultatif et peut être NULL. Si cet indicateur n’est pas défini, ExecutionRoutine doit être un pointeur valide non NULL . Pour plus d’informations sur cet indicateur, consultez la section Remarques.

[in, optional] ExecutionRoutine

Pointeur vers la routine AdapterListControl fournie par le pilote qui lance le transfert DMA pour le pilote. Le gestionnaire d’E/S appelle la routine AdapterListControl une fois que les ressources requises sont allouées pour l’objet adaptateur. Une fois la routine AdapterListControl retournée, le gestionnaire d’E/S libère automatiquement l’objet adaptateur et les ressources allouées pour cet objet.

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, le paramètre ExecutionRoutine est facultatif et peut être NULL. Si ce paramètre est NULL, l’appelant peut utiliser les ressources allouées par GetScatterGatherListEx pour effectuer le transfert DMA après que GetScatterGatherListEx retourne. Pour plus d'informations, consultez la section Notes.

[in, optional] Context

Contexte de contrôle d’adaptateur déterminé par le pilote. Ce contexte est passé à la routine AdapterListControl en tant que paramètre de contexte .

[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 de la mémoire à l’appareil. 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.

[in, optional] DmaCompletionRoutine

Non utilisé. Défini sur NULL.

[in, optional] CompletionContext

Non utilisé. Défini sur NULL.

[out, optional] ScatterGatherList

Pointeur vers une variable dans laquelle la routine écrit un pointeur dans la liste de nuages/regroupements alloués. Ce paramètre pointe vers une structure SCATTER_GATHER_LIST . La routine alloue cette structure et le tableau SCATTER_GATHER_ELEMENT auquel il pointe.

Le paramètre ScatterGatherList est facultatif et peut être NULL si le paramètre ExecutionRoutine n’est pas NULL.

Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini et que le paramètre ExecutionRoutine est NULL, ScatterGatherList doit être un pointeur valide non NULL . Si ExecutionRoutine n’est pas NULL, ScatterGatherList est facultatif et peut être NULL si le pilote appelant ne nécessite pas la liste de nuages/regroupements. L’appel GetScatterGatherListEx échoue si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini et ScatterGatherList et ExecutionRoutine sont à la fois NULL, ou si l’indicateur DMA_SYNCHRONOUS_CALLBACK n’est pas défini et ExecutionRoutine est NULL.

Valeur de retour

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

Code de retour Description
STATUS_INVALID_PARAMETERS
La routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant.
STATUS_INSUFFICIENT_RESOURCES
La routine n’a pas pu allouer les ressources requises pour le transfert DMA.

Remarques

GetScatterGatherListEx 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 GetScatterGatherListEx uniquement pour les adaptateurs bus-master. N’utilisez pas cette routine pour un adaptateur DMA système.

Le pilote d’un appareil maître de bus peut utiliser GetScatterGatherListEx pour combiner les opérations effectuées par les routines AllAdapterChannelEx et MapTransferEx dans un seul appel. GetScatterGatherListEx effectue les opérations suivantes :

  1. Alloue les ressources requises pour le transfert DMA.
  2. Génère une liste de points/regroupements en fonction des valeurs des paramètres Mdl, Offset et Length .
  3. Appelle la routine AdapterListControl fournie par le pilote et fournit la liste de nuages/regroupements à cette routine en tant que paramètre.
Les ressources allouées sont automatiquement publiées une fois la routine AdapterListControl retournée. Si GetScatterGatherListEx est appelé de façon synchrone (autrement dit, si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini), la routine AdapterListControl peut être omise. Dans ce cas, l’appelant utilise les ressources allouées pour lancer le transfert DMA après que GetScatterGatherListEx retourne. L’appelant doit libérer explicitement ces ressources.

Par défaut, GetScatterGatherListEx retourne de façon asynchrone, sans attendre que l’allocation de ressources demandée soit terminée. Après ce retour, l’appelant peut, si nécessaire, annuler la demande d’allocation en attente en appelant la routine CancelAdapterChannel .

Si le pilote appelant définit l’indicateur DMA_SYNCHRONOUS_CALLBACK , la routine GetScatterGatherListEx se comporte comme suit :

  • Si les ressources demandées ne sont pas immédiatement disponibles, GetScatterGatherListEx n’attend pas les ressources, ne génère pas de liste de nuages/regroupements et n’appelle pas la routine AdapterListControl . Au lieu de cela, GetScatterGatherListEx échoue et retourne STATUS_INSUFFICIENT_RESOURCES.
  • Le pilote n’est pas nécessaire pour fournir une routine AdapterListControl si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini.
  • Si le pilote fournit une routine AdapterListControl , l’indicateur DMA_SYNCHRONOUS_CALLBACK indique que cette routine doit être appelée dans le contexte du thread appelant, avant que GetScatterGatherListEx ne retourne.
  • Si le pilote ne fournit pas de routine AdapterListControl , le pilote peut utiliser les ressources allouées et la liste de points/regroupements une fois GetScatterGatherListEx retourné. Dans ce cas, le pilote doit fournir un pointeur ScatterGatherList non NULL valide. De plus, une fois le pilote lancé le transfert DMA, le pilote doit appeler la routine FreeAdapterObject pour libérer les ressources allouées par GetScatterGatherListEx pour l’objet adaptateur.
GetScatterGatherListEx est une version étendue de la routine GetScatterGatherList . Les fonctionnalités suivantes sont disponibles uniquement dans la version étendue :

GetScatterGatherListEx est similaire à la routine BuildScatterGatherListEx , sauf que GetScatterGatherListEx alloue automatiquement la mémoire tampon pour la liste de nuages/regroupements.

Spécifications

   
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

Voir aussi

AdapterListControl

AllocateAdapterChannelEx

BuildScatterGatherListEx

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DmaCompletionRoutine

FreeAdapterChannel

GetScatterGatherList

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx

SCATTER_GATHER_LIST