PBUILD_SCATTER_GATHER_LIST fonction de rappel (wdm.h)

La routine BuildScatterGatherList prépare le système pour une opération DMA, à l’aide d’une mémoire tampon fournie par le pilote pour générer la liste de points/regroupements.

Syntaxe

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [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,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

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 spécifiée par le membre MdlAddress de 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, de la mémoire tampon à mapper.

[in] ExecutionRoutine

Pointeur vers une routine AdapterListControl fournie par le pilote, appelée irQL = 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é à ExecutionRoutine 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.

[in] ScatterGatherBuffer

Pointeur vers la mémoire tampon fournie par l’appelant que la routine remplit avec une structure SCATTER_GATHER_LIST .

[in] ScatterGatherLength

Spécifie la taille, en octets, de la mémoire tampon passée dans le paramètre ScatterGatherBuffer .

Valeur retournée

BuildScatterGatherList retourne l’une des valeurs suivantes :

Remarques

BuildScatterGatherList 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 de 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_VERSION2. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.

BuildScatterGatherList effectue la même opération que GetScatterGatherList, sauf qu’il utilise la mémoire tampon fournie dans le paramètre ScatterGatherBuffer pour contenir la liste de points/de collecte qu’il crée. En revanche, GetScatterGatherList alloue dynamiquement une mémoire tampon pour contenir la liste de points/regroupements. Si la mémoire disponible est insuffisante pour allouer la mémoire tampon, GetScatterGatherList peut échouer avec une erreur de STATUS_INSUFFICIENT_RESOURCES. Les pilotes qui doivent éviter ce scénario peuvent préallouer une mémoire tampon pour contenir la liste de points/regroupements et utiliser BuildScatterGatherList à la place.

Un pilote peut utiliser la routine CalculateScatterGatherList pour déterminer la taille de la mémoire tampon à allouer pour contenir la liste de points/regroupements.

Le pilote doit conserver le pointeur vers la liste de points/regroupements dans ScatterGatherBuffer pour l’utiliser lorsque le pilote appelle PutScatterGatherList. Le pilote doit appeler PutScatterGatherList (qui vide la liste) avant de pouvoir accéder aux données de la liste.

Configuration requise

Voir aussi

BuildMdlFromScatterGatherList

CalculateScatterGatherList

DEVICE_DESCRIPTION

DEVICE_OBJECT

DMA_ADAPTER

DMA_OPERATIONS

GetScatterGatherList

IoGetDmaAdapter

PutScatterGatherList

SCATTER_GATHER_LIST