HW_BUILDIO fonction de rappel (storport.h)

Article
02/07/2025

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 la zone de stockage HBA du pilote miniport.

Srb

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

Valeur de retour

HwStorBuildIo retourne TRUE pour informer l’appelant que StorPort doit appeler la routine HwStorStartIo si StorPort considère le numéro d’unité logique prêt à recevoir des E/S. HwStorBuildIo retourne FAUX 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 n’est qu’un espace réservé pour la fonction miniport pointée par 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. Par conséquent, le pilote miniport est requis pour synchroniser l’accès aux ressources système, ce qui peut être en conflit si plusieurs instances de HwStorBuildIo sont actives à tout moment.

En effectuant des activités d’installation d’E/S fastidieuses dans HwStorBuildIo au lieu de HwStorStartIo, le pilote miniport active une concurrence d’E/S supérieure et améliore donc le débit d’E/S. Pour des performances optimales, les pilotes miniports 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 aux parties uniques de l'DeviceExtension doivent se produire, car aucun verrou n’est conservé. HwStorBuildIo et HwStorStartIo recevoir 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 Cdbs.
- Srb->DataBuffer est 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 de collecte de points ou l’adresse virtuelle de la mémoire tampon. Pour d’autres requêtes, 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 buss 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 capable).
- 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.
- Uniquement effectué 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 : demande au pilote miniport de vider toutes les données mises en cache préparatoires à l’arrêt.
- Uniquement effectué 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 des 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 miniporteur virtuel Storport utilisé pour contrôler le disque qui contient les données de vidage sur incident. À compter de Windows 8, les pilotes miniport non virtuels peuvent éventuellement recevoir cette demande.
- Srb->PathId, Srb->TargetId et Srb->Lun sont tous valides.
SRB_FUNCTION_FREE_DUMP_POINTERS : à partir de Windows 8, cette demande est envoyée au miniport pour libérer les ressources 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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 lorsque vous exécutez les 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 les conditions requises 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 annoter le comportement de la fonction.