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 :
| 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) |