PBUILD_SCATTER_GATHER_LIST fonction de rappel (wdm.h)

Article
02/27/2024

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 :

Code de retour	Description
STATUS_SUCCESS	L’opération s’est terminée avec succès.
STATUS_INSUFFICIENT_RESOURCES	Le système n’a pas suffisamment de registres de carte disponibles pour le transfert.
STATUS_BUFFER_TOO_SMALL	La longueur spécifiée est trop grande pour tenir dans la mémoire tampon.

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

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows XP et les versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h)
IRQL	DISPATCH_LEVEL
Règles de conformité DDI	IrqlDispatch(wdm)