HW_STARTIO fonction de rappel (storport.h)

Article
08/07/2023

Le pilote Storport appelle la routine HwStorStartIo une fois pour chaque demande d’E/S entrante.

Syntaxe

HW_STARTIO HwStartio;

BOOLEAN HwStartio(
  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 à démarrer.

Valeur retournée

HwStorStartIo retourne TRUE si la demande a été lancée avec succès. Sinon, il retourne FALSE.

Remarques

HwStorStartIo lance une opération d’E/S. StorPort est conçu pour utiliser les données privées d’un miniport qui sont préparées dans HwStorBuildIo et stockées dans DeviceExtension ou Srb-SrbExtension>. Étant donné que HwStorBuildIo est appelé sans verrous de rotation, les meilleures performances de pilote sont obtenues en préparant autant de données que possible dans HwStorBuildIo.

Storport appelle HwStorStartIo de la manière suivante :

Pour les pilotes de miniport de stockage non virtuels, en fonction de la valeur de SynchronizationModel définie dans PORT_CONFIGURATION_INFORMATION, Storport appelle toujours HwStorStartIo au même IRQL et utilise un verrou de rotation interne pour s’assurer que les demandes d’E/S sont lancées séquentiellement. L’IRQL est DISPATCH_LEVEL (mode duplex intégral) ou DIRQL (mode demi-duplex).

Lors de la gestion des E/S en mode demi-duplex, la routine HwStorStartIo n’a pas besoin d’acquérir son propre verrou de rotation. En outre, l’allocation de mémoire à l’aide de StorPortAllocatePool et l’exclusion mutuelle via StorPortAcquireSpinLock ne sont pas autorisées dans la routine HwStorStartIo . En mode duplex intégral, StorPortAllocatePool et StorPortAcquireSpinLock peuvent être utilisés dans la routine HwStorStartIo .

Si un miniport non virtuel prend en charge l’optimisation des canaux simultanés (STOR_PERF_CONCURRENT_CHANNELS défini par StorPortInitializePerfOpts), plusieurs appels à HwStorStartIo sont possibles simultanément. Dans ce cas, le miniport doit s’assurer que toutes les ressources partagées sont protégées par un verrou. Avec cette optimisation des performances, Storport n’acquiert pas le verrou StartIo avant d’appeler HwStorStartIo et le miniport doit fournir son propre verrou si nécessaire.
Pour les pilotes miniport virtuels de stockage, Storport appelle HwStorStartIo à n’importe quel IRQL <= DISPATCH_LEVEL et n’utilise pas de verrou de rotation interne. La routine HwStorStartIo peut acquérir son propre verrou de rotation en appelant StorPortAcquireSpinLock. En outre, les appels à StorPortAllocatePool sont autorisés dans la routine HwStorStartIo d’un pilote miniport virtuel de stockage.

Le SRB est censé être terminé lorsque le status SCSI est reçu. Lorsque le pilote Storport termine le SRB en appelant StorPortNotification avec un NotificationType de RequestComplete, un SRB est censé retourner l’une des valeurs suivantes dans le champ SrbStatus du Srb :

SRB_STATUS_SUCCESS
- Indique que le Srb a été envoyé et que le status SCSI (éventuellement avec des données) a été retourné.
- Storport retourne les données et les status à l’appelant.
- L’action Miniport n’est aucune, sauf pour terminer la demande à l’aide de StorPortNotification pour RequestComplete, probablement à partir de HwStorDpcRoutine.
SRB_STATUS_BUSY
- Indique qu’il existe un problème temporaire lors de l’envoi du Srb (par exemple, les registres d’adaptateurs ou les mémoires tampons sont occupés).
- Storport ignore l’extension Srb d’origine vers laquelle Srb-SrbExtension> pointe et en émet une nouvelle. Storport envoie le Srb d’origine avec l’extension Srb nouvellement émise dans les appels suivants à HwStorBuildIo et HwStorStartIo. Toutes les données de l’extension Srb d’origine seront perdues.
- Le miniport ne doit pas mettre à jour dataTransferLength du Srb.
- Étant donné qu’une nouvelle extension Srb est émise, le miniport doit s’assurer qu’il n’émet jamais de SRB_STATUS_BUSY au milieu d’une transaction SCSI. Une fois la transaction démarrée, elle doit être terminée ou annulée. Les états d’occupation du matériel pendant la transaction doivent être gérés par le pilote miniport.

Le nom HwStorStartIo est un espace réservé pour décrire la routine miniport définie dans le membre HwStartIo de HW_INITIALIZATION_DATA structure. Cette structure est transmise dans le paramètre HwInitializationData de StorPortInitialize. Le prototype réel de cette routine est défini dans Storport.h comme suit :

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

À 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 .

Exemples

Pour définir une routine de rappel HwStorStartIo , vous devez d’abord fournir une déclaration de fonction requise par Static Driver Verifier (SDV) et d’autres outils de vérification, comme illustré dans l’exemple de code suivant :

Pour définir une fonction de rappel HwStorStartIo , 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 HwStorStartIo nommée MyHwStartIo, utilisez le type HW_STARTIO et implémentez votre routine de rappel comme suit :

HW_STARTIO MyHwStartIo

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

Le type de fonction HW_STARTIO 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 le _Use_decl_annotations_ annotation à votre définition de fonction. le _Use_decl_annotations_ annotation garantit que les annotations appliquées au type de fonction HW_STARTIO 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.