HW_ADAPTER_CONTROL fonction de rappel (storport.h)

Article
08/07/2023

La routine HwStorAdapterControl d’un pilote miniport est appelée pour effectuer des opérations synchrones afin de contrôler l’état ou le comportement d’un adaptateur, telles que l’arrêt ou le redémarrage de l’adaptateur de bus hôte (HBA) pour la gestion de l’alimentation.

Syntaxe

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

Paramètres

[in] DeviceExtension

Pointeur vers la zone de stockage par HBA du pilote miniport.

[in] ControlType

Valeur SCSI_ADAPTER_CONTROL_TYPE qui spécifie une opération de contrôle d’adaptateur, où chaque type de contrôle lance une action par le pilote miniport. Pour plus d’informations, consultez SCSI_ADAPTER_CONTROL_TYPE .

[in] Parameters

Pointeur vers une structure ou une valeur qui contient des informations relatives au ControlType, ou NULL si le type de contrôle n’utilise pas de structure. Toutes les structures sont allouées par l’appelant. Pour plus d’informations, consultez SCSI_ADAPTER_CONTROL_TYPE .

Valeur retournée

Selon le type de contrôle, HwStorAdapterControl retourne l’une des valeurs SCSI_ADAPTER_CONTROL_STATUS suivantes :

Code de retour	Description
ScsiAdapterControlSuccess	Le pilote miniport a effectué l’opération demandée avec succès. Actuellement, HwStorAdapterControl doit retourner cette valeur pour tous les types de contrôles.
ScsiAdapterControlUnsuccessful	L’opération de contrôle de l’adaptateur n’a pas réussi.

Remarques

HwStorAdapterControl est une fonction obligatoire.

Storport appelle le HwStorAdapterControl d’un miniport avec un type de contrôle ScsiQuerySupportedControlTypes après l’initialisation du HBA, mais avant la première E/S. Le pilote miniport remplit la structure SCSI_SUPPORTED_CONTROL_TYPE_LIST dans Paramètres avec les opérations qu’il prend en charge. Une fois que HwStorAdapterControl est retourné à partir de cet appel, le pilote Storport appelle le rappel HwStorAdapterControl du pilote miniport uniquement pour les opérations prises en charge par le miniport.

Étant donné que les pilotes miniport qui fonctionnent avec le pilote Storport doivent prendre en charge Plug-and-Play (PnP), les miniports doivent prendre en charge les types de contrôles ScsiStopAdapter et ScsiRestartAdapter.

Le tableau suivant répertorie l’IRQL actuel et le verrouillage tournant acquis lors de l’émission du type de contrôle.

Type de contrôle	IRQL	Verrouillage de rotation
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	None
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	None
ScsiSetRunningConfig	PASSIVE_LEVEL	None
ScsiPowerSettingNotification	PASSIVE_LEVEL	None
ScsiAdapterPower	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	None
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	None
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	None
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	None
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	None
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	None
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	None
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	None
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	None
ScsiAdapterQueryFruId	PASSIVE_LEVEL	None
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	None

Le nom HwStorAdapterControl n’est qu’un espace réservé. Le prototype réel de cette routine est défini dans storport.h comme suit :

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Exemples

Pour définir une fonction de rappel HwStorAdapterControl , 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 permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des 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 HwStorAdapterControl nommée MyHwAdapterControl, utilisez le type HW_ADAPTER_CONTROL comme indiqué dans cet exemple de code :

HW_ADAPTER_CONTROL MyHwAdapterControl;

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

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

Le type de fonction HW_ADAPTER_CONTROL 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_ADAPTER_CONTROL 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.