StorPortBuildScatterGatherList, fonction (storport.h)

Article
02/07/2025

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 pilote miniport fourni ExecutionRoutine. Le pilote Storport appelle cette routine après avoir créé la liste de nuages 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 STOR_SCATTER_GATHER_LIST qui contient la liste de nuages de points/regroupements pour la mémoire tampon de données spécifiée.

Contexte

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

Le pilote Storport appelle le 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. Une valeur de TRUE indique un transfert de la mémoire tampon de données vers l’appareil, et une valeur de FALSE indique un transfert de l’appareil vers la mémoire tampon de données.

[in, out] ScatterGatherBuffer

Pointeur vers une mémoire tampon miniport fournie qui reçoit la liste de nuages 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 par le paramètre ScatterGatherBuffer.

Valeur de retour

StorPortBuildScatterGatherList retourne l’une des valeurs suivantes :

Retourner le code	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 nuages de points/de collecte avec succès. important voir « Remarques ».
STOR_STATUS_INVALID_PARAMETER	Le HwDeviceExtension a été transmis NULL.
STOR_STATUS_INVALID_IRQL	L’appel a été effectué à un IRQL non valide.
STOR_STATUS_INSUFFICIENT_RESOURCES	Le système dispose d’un nombre insuffisant de registres cartographiques disponibles pour le transfert.
STOR_STATUS_BUFFER_TOO_SMALL	Le paramètre Length est trop grand pour s’adapter à la mémoire tampon.

Remarques

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

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

Remarque Si StorPortBuildScatterGatherList retourne STOR_STATUS_SUCCESS, le rappel dans ExecutionRoutine a été correctement mis en file d’attente pour s’exécuter après la création de la liste de nuages de points/regroupements. Le miniport ne doit pas supposer que ExecutionRoutine a été appelée ou que la liste de nuages 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 vous assurer que la liste de nuages de points/regroupements est disponible.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	storport.h (include Storport.h)
IRQL	DISPATCH_LEVEL

Voir aussi

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Partager via