PBUILD_SCATTER_GATHER_LIST_EX fonction de rappel (wdm.h)
La routine BuildScatterGatherListEx alloue les ressources requises pour un transfert DMA, génère une liste de nuages de points/regroupements et appelle la routine AdapterListControl fournie par le pilote pour lancer le transfert DMA.
Prudence
N’appelez pas cette routine pour un appareil DMA système.
Syntaxe
PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;
NTSTATUS PbuildScatterGatherListEx(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID DmaTransferContext,
[in] PMDL Mdl,
[in] ULONGLONG Offset,
[in] ULONG Length,
[in] ULONG Flags,
[in, optional] PDRIVER_LIST_CONTROL ExecutionRoutine,
[in, optional] PVOID Context,
[in] BOOLEAN WriteToDevice,
[in] PVOID ScatterGatherBuffer,
[in] ULONG ScatterGatherLength,
[in, optional] PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
[in, optional] PVOID CompletionContext,
[out, optional] PVOID ScatterGatherList
)
{...}
Paramètres
[in] DmaAdapter
Pointeur vers une structure DMA_ADAPTER. Cette structure est l’objet d’adaptateur qui représente le périphérique DMA maître de bus du pilote ou le canal DMA système. L’appelant a obtenu ce pointeur à partir d’un appel précédent à la routine IoGetDmaAdapter.
[in] DeviceObject
Pointeur vers une structure DEVICE_OBJECT. Cette structure est l’objet d’appareil physique (PDO) qui représente l’appareil cible pour l’opération DMA demandée.
[in] DmaTransferContext
Pointeur vers un contexte de transfert DMA initialisé. Ce contexte a été initialisé par un appel précédent à la routine InitializeDmaTransferContext. Ce contexte doit être unique dans toutes les demandes d’allocation d’adaptateur. Pour annuler une demande d’allocation en attente, l’appelant doit fournir le contexte de transfert DMA de la demande à la routine CancelAdapterChannel.
[in] Mdl
Pointeur vers une chaîne MDL qui décrit la mise en page physique d’une collection de mémoires tampons verrouillées en mémoire virtuelle. La liste de points/regroupements pour le transfert DMA utilise la région de cette mémoire spécifiée par les paramètres offset et Longueur. Pour plus d’informations sur les chaînes MDL, consultez Utilisation de MDLs.
[in] Offset
Décalage de départ pour le transfert DMA de nuages de points/collecte. Ce paramètre est un décalage d’octets à partir du début de la mémoire tampon dans le premier MDL de la chaîne MDL. Si les MDL de la chaîne MDL spécifient un total de N octets d’espace tampon, les valeurs valides de offset sont comprises entre 0 et N-1.
[in] Length
Taille, en octets, du transfert DMA. Si la chaîne MDL spécifie un total de N octets d’espace tampon, les valeurs valides de Longueur se trouvent dans la plage 1 à N –Offset.
[in] Flags
Indicateurs d’allocation de canal d’adaptateur. L’indicateur suivant est pris en charge :
| Drapeau | Signification |
|---|---|
| DMA_SYNCHRONOUS_CALLBACK | La routine BuildScatterGatherListEx est appelée de façon synchrone. Si cet indicateur est défini et que les ressources DMA requises ne sont pas immédiatement disponibles, l’appel échoue et retourne STATUS_INSUFFICIENT_RESOURCES. |
Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, le paramètre ExecutionRoutine est facultatif et peut être NULL. Si cet indicateur n’est pas défini, ExecutionRoutine doit être un pointeurNULL non valide. Pour plus d’informations sur cet indicateur, consultez la section Remarques.
[in, optional] ExecutionRoutine
Pointeur vers le pilote fourni AdapterListControl routine qui lance le transfert DMA pour le pilote. Le gestionnaire d’E/S appelle la routine AdapterListControl une fois les ressources requises allouées pour l’objet adaptateur. Une fois la routine de AdapterListControl retournée, le gestionnaire d’E/S libère automatiquement l’objet d’adaptateur et les ressources allouées pour cet objet.
Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini, ExecutionRoutine est facultatif et peut être NULL. Si ExecutionRoutine est NULL, l’appelant peut utiliser les ressources allouées par BuildScatterGatherListEx. Pour plus d’informations, consultez la section Remarques.
[in, optional] Context
Contexte de contrôle d’adaptateur déterminé par le pilote. Ce contexte est passé à la routine AdapterListControl en tant que paramètre context.
[in] WriteToDevice
Direction du transfert DMA. Définissez ce paramètre sur TRUE pour une opération d’écriture, qui transfère les données de la mémoire à l’appareil. Définissez ce paramètre sur FALSE pour une opération de lecture, qui transfère les données de l’appareil en mémoire.
[in] ScatterGatherBuffer
Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la routine écrit la liste de nuages de points/collecte pour le transfert DMA. Cette liste commence par une structure SCATTER_GATHER_LIST, suivie d’un tableau SCATTER_GATHER_ELEMENT.
[in] ScatterGatherLength
Taille, en octets, de la mémoire tampon passée dans le paramètre ScatterGatherBuffer. La taille de la mémoire tampon allouée doit être suffisamment grande pour contenir la liste de points/regroupements, ainsi que les données internes stockées par le système d’exploitation dans cette mémoire tampon. Pour calculer la taille de mémoire tampon requise, appelez la routine GetDmaTransferInfo ou CalculateScatterGatherList routine.
[in, optional] DmaCompletionRoutine
Non utilisé. Défini sur NULL .
[in, optional] CompletionContext
Non utilisé. Défini sur NULL .
[out, optional] ScatterGatherList
Pointeur vers une variable dans laquelle la routine écrit un pointeur dans la liste de nuages de points/regroupements pour le transfert DMA. Cette liste commence par une structure SCATTER_GATHER_LIST, qui contient un pointeur vers un tableau SCATTER_GATHER_ELEMENT. Ce pointeur de sortie correspond toujours à la valeur de paramètre ScatterGatherBuffer.
Si l’indicateur DMA_SYNCHRONOUS_CALLBACK est défini et que le paramètre ExecutionRoutine est NULL, ScatterGatherList doit être un pointeurNULL valide, non NULL. Si executionRoutine n’est pasNULL, ScatterGatherList est facultatif et peut être NULL si le pilote appelant ne nécessite pas la liste de nuages de points/collectes. L’appel BuildScatterGatherListEx échoue si l’indicateur de DMA_SYNCHRONOUS_CALLBACK est défini et ScatterGatherList et ExecutionRoutine sont NULL, ou si l’indicateur DMA_SYNCHRONOUS_CALLBACK n’est pas défini et ExecutionRoutine est NULL.
Valeur de retour
BuildScatterGatherListEx retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles incluent les codes d’état suivants.
| Retourner le code | Description |
|---|---|
| STATUS_INVALID_PARAMETERS | La routine a échoué en raison de valeurs de paramètre non valides passées par l’appelant. |
| STATUS_BUFFER_TOO_SMALL | La mémoire tampon fournie par l’appelant dans ScatterGatherBuffer est trop petite pour contenir la liste de nuages de points/regroupements. |
| STATUS_INSUFFICIENT_RESOURCES | La routine n’a pas pu allouer de ressources requises pour le transfert DMA. |
Remarques
BuildScatterGatherListEx* 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 de l’adresse retournée dans une structureDMA_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_VERSION3. Si IoGetDmaAdapter retourne NULL, la routine n’est pas disponible sur votre plateforme.
Utilisez BuildScatterGatherListEx uniquement pour les adaptateurs bus-master. N’utilisez pas cette routine pour un adaptateur DMA système.
BuildScatterGatherListEx est similaire à la routine GetScatterGatherListEx, sauf qu’il exige que l’appelant alloue la mémoire tampon pour la liste de nuages de points/regroupements.
Par exemple, un pilote peut préallouer une ou plusieurs mémoires tampons de nuages de points/collecter pendant l’initialisation de l’appareil. Plus tard, un appel BuildScatterGatherListEx qui utilise une telle mémoire tampon peut réussir dans des conditions de faible disponibilité de la mémoire susceptibles d’entraîner l’échec d’un appel GetScatterGatherListEx.
Par défaut, BuildScatterGatherListEx retourne de façon asynchrone, sans attendre que l’allocation de ressources demandée soit terminée. Après ce retour, l’appelant peut, le cas échéant, annuler la demande d’allocation en attente en appelant la routine CancelAdapterChannel.
Si le pilote appelant définit l’indicateur DMA_SYNCHRONOUS_CALLBACK, la routine BuildScatterGatherListEx se comporte comme suit :
Si les ressources demandées ne sont pas immédiatement disponibles, BuildScatterGatherListEx n’attend pas les ressources, ne génère pas de liste de nuages de points/collectes et n’appelle pas la routine AdapterListControl. Au lieu de cela, BuildScatterGatherListEx échoue et retourne STATUS_INSUFFICIENT_RESOURCES.
Le pilote n’est pas nécessaire pour fournir une routine AdapterListControl si l’indicateur de DMA_SYNCHRONOUS_CALLBACK est défini.
Si le pilote fournit une routine AdapterListControl, l’indicateur DMA_SYNCHRONOUS_CALLBACK indique que cette routine doit être appelée dans le contexte du thread appelant, avant BuildScatterGatherListEx retourne.
Si le pilote ne fournit pas de routine AdapterListControl, le pilote peut utiliser les ressources allouées et la liste de nuages de points/regroupements après BuildScatterGatherListEx retourne. Dans ce cas, le pilote doit fournir un pointeurNULL valideScatterGatherList valide. En outre, une fois le transfert DMA initié par le pilote terminé, le pilote doit appeler la routine FreeAdapterObject pour libérer les ressources qui BuildScatterGatherListEx allouées pour l’objet adaptateur.
BuildScatterGatherListEx est une version étendue de la routine BuildScatterGatherList. La liste suivante récapitule les fonctionnalités disponibles uniquement dans la version étendue :
| Caractéristique | Description |
|---|---|
| Décalage de départ | Le pilote appelant peut spécifier un décalage de départ pour un transfert DMA de nuage de points/collecter au lieu de démarrer le transfert à la première adresse de mémoire tampon au début de la chaîne MDL. |
| Annulation de la demande d’allocation | Le pilote peut appeler CancelAdapterChannel pour annuler une demande d’allocation en attente lorsque l’adaptateur DMA est mis en file d’attente pour attendre les ressources DMA. |
| Rappel synchrone | Le pilote peut définir l’indicateur de DMA_SYNCHRONOUS_CALLBACK pour demander que la routine AdapterListControl fournie par le pilote soit appelée dans le thread appelant, avant BuildScatterGatherListEx retourne. |
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 8. |
| plateforme cible | Bureau |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | DISPATCH_LEVEL |