fonction de rappel HW_STARTIO (storport.h)

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

Syntaxe

HW_STARTIO HwStartio;

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

Valeur de retour

HwStorStartIo retourne TRUE si la requête a été lancée avec succès. Sinon, elle 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 préparé dans HwStorBuildIo et stocké dans DeviceExtension ou Srb-SrbExtension>. Étant donné que HwStorBuildIo est appelé sans verrous de rotation, les meilleures performances du 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 miniport non virtuels de stockage, 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. Le runtime d’intégration 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 simultanée des canaux (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 l’état 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 l’état SCSI (éventuellement avec des données) a été retourné.
    • Storport retourne les données et l’état à l’appelant.
    • L’action Miniport n’est aucune, sauf pour terminer la requête à l’aide de StorPortNotification pour RequestComplete, probablement à partir de HwStorDpcRoutine.
  • SRB_STATUS_BUSY

    • Indique qu’il existe un problème temporaire lié à 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 vers et émet une nouvelle extension. 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 le DataTransferLength de Srb.
    • Étant donné qu’une nouvelle extension Srb est émise, le miniport doit s’assurer qu’il ne émet jamais 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 occupés par le 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 passée 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
  );

À compter 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 indiqué 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 fonctions de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilote statique (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 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 lorsque vous exécutez les outils d’analyse du code, veillez à ajouter la _Use_decl_annotations_ annotation définition de votre fonction. Garantit _Use_decl_annotations_ annotation 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 La 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.

Configuration requise

   
Plateforme cible Universal
En-tête storport.h (inclure Storport.h)
IRQL DISPATCH_LEVEL (voir la section Notes.)

Voir aussi

HwStorBuildIo

SCSI_REQUEST_BLOCK

STORAGE_REQUEST_BLOCK

StorPortInitialize