PGET_SCATTER_GATHER_LIST fonction de rappel (wdm.h)

La routine GetScatterGatherList prépare le système pour une opération de diffusion/collecte DMA pour le compte de l’objet d’appareil cible, par le biais du contrôleur DMA système ou d’une carte master bus.

Syntaxe

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice
)
{...}

Paramètres

[in] DmaAdapter

Pointeur vers la structure DMA_ADAPTER retournée par IoGetDmaAdapter qui représente l’adaptateur master bus ou le contrôleur DMA.

[in] DeviceObject

Pointeur vers l’objet d’appareil qui représente l’appareil cible pour l’opération DMA.

[in] Mdl

Pointeur vers le MDL qui décrit la mémoire tampon sur MdlAddress dans l’IRP actuel.

[in] CurrentVa

Pointeur vers l’adresse virtuelle actuelle dans la MDL pour que la mémoire tampon soit mappée pour une opération de transfert DMA.

[in] Length

Spécifie la longueur, en octets, à mapper.

[in] ExecutionRoutine

Pointeur vers une routine AdapterListControl fournie par le pilote, appelée à DISPATCH_LEVEL lorsque le contrôleur DMA système ou l’adaptateur master bus est disponible.

[in] Context

Pointeur vers le contexte déterminé par le pilote passé à la routine AdapterListControl du pilote lorsqu’il est appelé.

[in] WriteToDevice

Indique la direction du transfert DMA : TRUE pour un transfert de la mémoire tampon vers l’appareil, et FALSE dans le cas contraire.

Valeur retournée

Cette routine peut retourner l’une des valeurs NTSTATUS suivantes.

Remarques

La routine GetScatterGatherList alloue dynamiquement une mémoire tampon pour contenir la liste de points/regroupements. Pour connaître les valeurs NTSTATUS possibles si l’allocation de mémoire tampon échoue, consultez la valeur de retour.

GetScatterGatherList 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 à partir de l’adresse retournée dans une structure de DMA_OPERATIONS . Les pilotes obtiennent l’adresse de cette routine en appelant IoGetDmaAdapter.

Dès que le canal DMA approprié et les registres de carte nécessaires sont disponibles, GetScatterGatherList crée une liste de points/regroupements, initialise les registres de carte, puis appelle la routine AdapterListControl fournie par le pilote pour effectuer l’opération d’E/S.

GetScatterGatherList combine les actions des routines AllocateAdapterChannel et MapTransfer pour les pilotes qui effectuent des opérations de diffusion/collecte DMA. GetScatterGatherList détermine le nombre de registres de carte requis pour le transfert, alloue les registres de carte, mappe les mémoires tampons pour DMA et remplit la liste de points/regroupements. Il appelle ensuite la routine AdapterListControl fournie, en passant un pointeur vers la liste de points/regroupement dans ScatterGather. Le pilote doit conserver ce pointeur pour l’utiliser lors de l’appel de PutScatterGatherList. Notez que GetScatterGatherList n’a pas les restrictions de mise en file d’attente qui s’appliquent à AllocateAdapterChannel.

Dans sa routine AdapterListControl , le pilote doit effectuer les E/S. Au retour de la routine fournie par le pilote, GetScatterGatherList conserve les registres de carte, mais libère la structure de l’adaptateur DMA. Le pilote doit appeler PutScatterGatherList (qui vide les mémoires tampons) avant de pouvoir accéder aux données de la mémoire tampon.

Cette routine peut gérer les listes MDL chaînées, à condition que le nombre total de registres de carte requis par toutes les LISTES MDL chaînées ne dépasse pas le nombre de registres de carte disponibles.

Configuration requise

Voir aussi

AllocationAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST