Fonction StorPortBuildScatterGatherList (storport.h)

Article
08/07/2023

La routine StorPortBuildScatterGatherList crée une liste de points/regroupements pour la mémoire tampon de données spécifiée.

Syntaxe

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

Paramètres

[in] HwDeviceExtension

Pointeur vers l’extension de périphérique matériel pour l’adaptateur de bus hôte (HBA).

[in] Mdl

Pointeur vers une liste de descripteurs de mémoire (MDL) qui décrit les pages mémoire associées à la mémoire tampon de données.

[in] CurrentVa

Adresse virtuelle de la mémoire tampon de données.

[in] Length

Longueur, en octets, de la mémoire tampon de données.

[in] ExecutionRoutine

Pointeur vers un executionRoutine fourni par le pilote miniport. Le pilote Storport appelle cette routine après avoir créé la liste de points/regroupements. Le pilote miniport doit effectuer toutes les opérations qui utilisent la liste de points/regroupements à l’intérieur de la routine d’exécution, et non dans le code qui suit l’appel à la routine StorPortBuildScatterGatherList .

Un ExecutionRoutine est déclaré comme suit :

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

Les pilotes miniport doivent ignorer ce paramètre.

Irp

Les pilotes miniport doivent ignorer ce paramètre.

ScatterGather

Pointeur vers une structure de STOR_SCATTER_GATHER_LIST qui contient la liste de points/regroupements pour la mémoire tampon de données spécifiée.

Context

Valeur de contexte spécifiée dans le paramètre Context de la fonction StorPortBuildScatterGatherList.

Le pilote Storport appelle executionRoutine d’un pilote miniport à IRQL = DISPATCH_LEVEL.

[in] Context

Valeur de contexte que le pilote de port transmet à la routine d’exécution spécifiée dans le paramètre ExecutionRoutine . La routine d’exécution utilise cette valeur pour identifier de manière unique la requête.

[in] WriteToDevice

Valeur qui indique la direction du transfert DMA. La valeur TRUE indique un transfert de la mémoire tampon de données vers l’appareil, et la valeur FALSE indique un transfert de l’appareil vers la mémoire tampon de données.

[in, out] ScatterGatherBuffer

Pointeur vers une mémoire tampon fournie par miniport qui reçoit la liste de points/regroupements. Un pilote miniport peut allouer de la mémoire pour cette mémoire tampon en appelant la routine StorPortAllocatePool .

[in] ScatterGatherBufferLength

Taille, en octets, de la mémoire tampon pointée vers le paramètre ScatterGatherBuffer .

Valeur retournée

StorPortBuildScatterGatherList retourne l’une des valeurs suivantes :

Code de retour	Description
STOR_STATUS_NOT_IMPLEMENTED	Cette fonction n’est pas implémentée sur le système d’exploitation actif.
STOR_STATUS_SUCCESS	Indique que la routine a créé la liste de points/de collecte avec succès. Important Consultez « Remarques ».
STOR_STATUS_INVALID_PARAMETER	La valeur HwDeviceExtension passée était NULL.
STOR_STATUS_INVALID_IRQL	L’appel a été effectué à un IRQL non valide.
STOR_STATUS_INSUFFICIENT_RESOURCES	Le système n’a pas suffisamment de registres de carte disponibles pour le transfert.
STOR_STATUS_BUFFER_TOO_SMALL	Le paramètre Length est trop volumineux pour tenir dans la mémoire tampon.

Remarques

Le pilote miniport appelle StorPortPutScatterGatherList pour libérer les ressources allouées par StorPortBuildScatterGatherList lors de la construction de la liste de points/regroupements.

Le pilote miniport doit appeler StorPortPutScatterGatherList avant de libérer ou de réutiliser la mémoire qu’il a allouée pour la liste de points/regroupements.

Note Si StorPortBuildScatterGatherList retourne STOR_STATUS_SUCCESS, le rappel dans ExecutionRoutine a été mis en file d’attente pour s’exécuter après la création de la liste de points/regroupements. Le miniport ne doit pas supposer qu’ExecutionRoutine a été appelé ou que la liste de points/regroupements est prête lorsque StorPortBuildScatterGatherList retourne. Si nécessaire, le miniport peut synchroniser l’exécution du code suivant StorPortBuildScatterGatherList avec le rappel dans ExecutionRoutine pour s’assurer que la liste de points/regroupements est disponible.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	storport.h (inclure Storport.h)
IRQL	DISPATCH_LEVEL

Voir aussi

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Partager via