HW_FIND_ADAPTER fonction de rappel (storport.h)

Article
02/26/2024

La routine HwStorFindAdapter utilise la configuration fournie pour déterminer si un HBA spécifique est pris en charge et, le cas échéant, pour retourner des informations de configuration sur cet adaptateur.

Syntaxe

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Paramètres

DeviceExtension

Fournit une zone de stockage par adaptateur.

[in] HwContext

valeur de l’en-tête définie sur Null.

[in] BusInformation

valeur de l’en-tête définie sur Null.

[in] ArgumentString

Fournit une chaîne terminée par NULL avec des informations de contexte sur le pilote.

[in/out] ConfigInfo

Fournit une structure PORT_CONFIGURATION_INFORMATION initialisée que le pilote miniport utilise lors de l’initialisation.

[in] Reserved3

Réservé pour le système.

Valeur retournée

HwStorFindAdapter doit retourner l’une des valeurs de status suivantes :

Code de retour	Description
SP_RETURN_FOUND	Indique qu’un HBA pris en charge a été trouvé et que les informations de configuration pertinentes pour HBA ont été correctement déterminées et définies dans la structure PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Indique qu’un HBA a été trouvé, mais qu’une erreur s’est produite lors de l’obtention des informations de configuration. Si possible, une telle erreur doit être enregistrée avec StorPortLogError.
SP_RETURN_BAD_CONFIG	Indique que les informations de configuration fournies n’étaient pas valides pour l’adaptateur.
SP_RETURN_NOT_FOUND	Indique qu’aucun HBA pris en charge n’a été trouvé pour les informations de configuration fournies.

Remarques

Étant donné que le pilote Storport prend en charge uniquement les appareils Plug-and-Play (PnP), les paramètres HwContext et BusInformation de HwStorFindAdapter ne sont pas fournis aux pilotes miniport non virtuels.

HwStorFindAdapter doit définir les champs MaximumTransferLength et NumberOfPhysicalBreaks dans la structure ConfigInfo . En dehors de ces champs, la structure PORT_CONFIGURATION_INFORMATION spécifie toujours entièrement toutes les ressources de l’adaptateur nécessaires au démarrage de l’adaptateur.

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

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

Dans la plupart des cas, StorPort appelle la routine HwStorFindAdapter à IRQL == PASSIVE_LEVEL sans acquérir de verrous de rotation. Le cas d’exception est lorsque le miniport ne prend pas en charge l’appel de HwStorAdaptorControl avec le type de contrôle ScsiRestartAdapter . Dans ce cas, StorPort réinitialise plutôt l’adaptateur en appelant HwStorFindAdapter et HwStorInitialize. Dans ce cas, HwStorFindAdapter est appelé dans IRQL == DISPATCH_LEVEL. En outre, en mode vidage, HwStorFindAdapter est appelé dans IRQL == HIGH_LEVEL.

Exemples

Pour définir une fonction de rappel HwStorFindAdapter , 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 HwStorFindAdapter nommée MyHwFindAdapter, utilisez le type HW_FIND_ADAPTER comme indiqué dans cet exemple de code :

HW_FIND_ADAPTER MyHwFindAdapter;

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

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

Le type de fonction HW_FIND_ADAPTER 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_FIND_ADAPTER 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.