HW_BUILDIO fonction de rappel (storport.h)

Article
03/01/2024

La routine HwStorBuildIo traite le SRB avec un accès non synchronisé aux structures de données système partagées avant de le transmettre à HwStorStartIo.

Syntaxe

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Paramètres

DeviceExtension

Pointeur vers le pilote miniport par zone de stockage HBA.

Srb

Pointeur vers le bloc de requête SCSI (SRB) à traiter.

Valeur retournée

HwStorBuildIo retourne TRUE pour informer l’appelant que StorPort doit appeler la routine HwStorStartIo si StorPort considère que le LUN est prêt à recevoir des E/S. HwStorBuildIo retourne FALSE pour informer l’appelant que le SRB ne doit pas être passé à HwStorStartIo. Dans ce cas, le pilote miniport doit terminer le SRB en appelant StorPortNotification avec un type de notification RequestComplete. Cela peut être effectué dans HwStorBuildIo ou ailleurs dans le pilote miniport, tant que le SRB est terminé avant le délai d’expiration spécifié dans le champ TimeOutValue de la structure SRB.

Remarques

Le nom HwStorBuildIo est simplement un espace réservé pour la fonction miniport vers laquelle pointe le membre HwBuildIo dans la structure HW_INITIALIZATION_DATA . Le prototype réel de cette routine est défini dans Storport.h comme suit :

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Le pilote de port appelle la routine HwStorBuildIo à DISPATCH IRQL sans contenir de verrous de rotation. Pour cette raison, l’allocation de mémoire à l’aide de StorPortAllocatePool et l’exclusion mutuelle via StorPortAcquireSpinLock sont autorisées dans HwStorBuildIo. Dans un environnement multiprocesseur, plusieurs HwStorBuildIo peuvent être actifs à la fois. Le pilote miniport est donc nécessaire pour synchroniser l’accès aux ressources système, ce qui peut être en conflit si plusieurs instance de HwStorBuildIo sont actifs à un moment donné.

En effectuant des activités d’installation d’E/S chronophages dans HwStorBuildIo plutôt que dans HwStorStartIo, le pilote miniport permet une plus grande concurrence des E/S et améliore par conséquent le débit d’E/S. Pour des performances optimales, les pilotes miniport sont censés effectuer autant de prétraitement que possible dans HwStorBuildIo afin qu’il puisse envoyer des requêtes à l’adaptateur HBA via HwStorStartIo dans un délai aussi court que possible. Les données et l’état prétraités peuvent être stockés dans les structures DeviceExtension ou SrbExtension . Seules les modifications apportées à des parties uniques de DeviceExtension doivent se produire, car aucun verrou n’est conservé. HwStorBuildIo et HwStorStartIo reçoivent les types de fonctions Srb suivants :

SRB_FUNCTION_EXECUTE_SCSI : envoie une base de données CDB au bus/cible/lun spécifié.
- Srb-DataTransferLength> est valide pour toutes les Cdb.
- Srb-DataBuffer> a la valeur NULL pour les demandes de lecture et d’écriture. Pour accéder aux données associées, utilisez StorPortGetScatterGatherList (pour les transferts Dma) ou StorPortGetSystemAddress (pour les E/S contrôlées par le programme) pour obtenir la liste Scatter Collect ou l’adresse virtuelle de la mémoire tampon. Pour les autres demandes, Srb-Databuffer> pointe vers les données associées au Srb.
- Srb-PathId> est valide et représente le pathid donné à Storport dans StorPortNotification (BusChange). Les enregistreurs de pilotes miniport doivent utiliser pathid comme index dans une table de bus dans le miniport.
- Srb-TargetId> et Srb-Lun> sont valides.
SRB_FUNCTION_IO_CONTROL : miniport défini.
- Srb-DataTransferLength> et Srb-DataBuffer> sont valides s’ils sont définis par le demandeur.
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.
SRB_FUNCTION_RESET_LOGICAL_UNIT : réinitialisez l’unité logique spécifiée (si l’appareil est compatible).
- Srb-DataTransferLength> et Srb-DataBuffer> ne sont pas valides.
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.
SRB_FUNCTION_RESET_DEVICE : réinitialisez la cible SCSI spécifiée.
- Srb-DataTransferLength> et Srb-DataBuffer>, Srb-Lun> ne sont pas valides.
- Srb-PathId> et Srb-TargetId> sont valides.
SRB_FUNCTION_RESET_BUS : réinitialisez toutes les cibles sur le bus SCSI spécifié.
- Seul Srb-PathId> est valide.
SRB_FUNCTION_FLUSH : indique au pilote miniport de vider toutes les données mises en cache.
- Effectué uniquement par le pilote miniport s’il définit CachesData == TRUE dans la structure PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.
SRB_FUNCTION_SHUTDOWN : indique au pilote miniport de vider toutes les données mises en cache préparatoires à l’arrêt.
- Effectué uniquement par le pilote miniport s’il définit CachesData == TRUE dans la structure PORT_CONFIGURATION_INFORMATION .
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.
SRB_FUNCTION_DUMP_POINTERS : fournit les informations nécessaires au pilote miniport pour prendre en charge le vidage sur incident et la mise en veille prolongée.
- Cette demande est envoyée à un pilote de miniport virtuel Storport qui est utilisé pour contrôler le disque qui contient les données de vidage sur incident. À compter de Windows 8, les pilotes miniports non virtuels peuvent éventuellement recevoir cette demande.
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.
SRB_FUNCTION_FREE_DUMP_POINTERS : à compter de Windows 8, cette demande est envoyée au miniport pour les ressources gratuites allouées pendant la demande de SRB_FUNCTION_DUMP_POINTERS.
- Srb-PathId>, Srb-TargetId> et Srb-Lun> sont tous valides.

À partir de Windows 8, le paramètre Srb peut pointer vers SCSI_REQUEST_BLOCK ou STORAGE_REQUEST_BLOCK. Si l’identificateur de fonction dans le champ Fonction de Srb est SRB_FUNCTION_STORAGE_REQUEST_BLOCK, le SRB est une structure de requête STORAGE_REQUEST_BLOCK .

Pour plus d’informations sur ce que vous pouvez et ne pouvez pas faire en toute sécurité dans cette routine de pilote miniport, consultez Routine HwStorBuildIo non synchronisée.

Exemples

Pour définir une fonction de rappel HwStorBuildIo , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel HwStorBuildIo nommée MyHwBuildIo, utilisez le type HW_BUILDIO comme indiqué dans cet exemple de code :

HW_BUILDIO MyHwBuildIo;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

Le type de fonction HW_BUILDIO est défini dans le fichier d’en-tête Storport.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction HW_BUILDIO dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes Storport. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.