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.
| Code de retour | Description |
|---|---|
|
L’opération a réussi. |
|
La routine n’a pas pu allouer suffisamment de mémoire ou le nombre de registres de carte requis pour le transfert est supérieur à la valeur retournée par IoGetDmaAdapter. |
|
La mémoire tampon est trop petite pour le transfert demandé. |
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
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Windows 2000 et versions ultérieures de Windows. Non pris en charge dans Windows 98 ou Windows Me. |
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |
| Règles de conformité DDI | IrqlDispatch(storport),IrqlDispatch(storport), IrqlDispatch(wdm) |