VIRTUAL_HW_FIND_ADAPTER fonction de rappel (storport.h)

Article
08/07/2023

Le miniport virtuel Storport utilise les informations de configuration fournies à la routine VIRTUAL_HW_FIND_ADAPTER pour s’initialiser davantage.

Syntaxe

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

ULONG VirtualHwFindAdapter(
  PVOID DeviceExtension,
  PVOID HwContext,
  PVOID BusInformation,
  PVOID LowerDevice,
  PCHAR ArgumentString,
  PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  PBOOLEAN Again
)
{...}

Paramètres

DeviceExtension

Pointeur vers la zone de stockage non paginée par adaptateur du pilote miniport. Le pilote de port spécifique au système d’exploitation alloue de la mémoire pour et initialise cette extension avec des zéros avant d’appeler la routine VIRTUAL_HW_FIND_ADAPTER du miniport.

HwContext

Pointeur vers l’AOP dans la pile d’appareils. L’adaptateur HBA lui-même est le FDO. L’AOP peut appartenir au pilote Pci.sys si le pilote miniport contrôle le matériel physique. Mais dans le cas d’un pilote de miniport virtuel, l’AOP appartient au gestionnaire PnP.

BusInformation

Pointeur vers l’objet d’appareil fonctionnel (FDO) du miniport.

LowerDevice

Pointeur vers l’objet d’appareil contrôlé par le FDO du miniport.

ArgumentString

Pointeur vers une chaîne ASCII terminée par null. Cette chaîne, si elle est fournie, contient des informations sur l’appareil provenant du Registre, telles qu’un paramètre de base.

ConfigInfo

Pointeur vers une structure PORT_CONFIGURATION_INFORMATION . Le pilote de port initialise cette structure avec toutes les informations de configuration connues, telles que les valeurs définies par driverEntry du pilote miniport dans le VIRTUAL_HW_INITIALIZATION_DATA. VIRTUAL_HW_FIND_ADAPTER devez utiliser les informations fournies pour déterminer si l’adaptateur HBA virtuel qu’il décrit est pris en charge par le pilote miniport. Si c’est le cas, VIRTUAL_HW_FIND_ADAPTER initialise et configure cet adaptateur HBA et renseigne toutes les informations de configuration manquantes. Si possible, un pilote miniport doit avoir des valeurs de configuration par défaut pour chaque type de HBA qu’il prend en charge, dans le cas où le pilote de port dépendant du système d’exploitation ne peut pas fournir d’informations de configuration supplémentaires qui n’ont pas été fournies par la routine DriverEntry du pilote miniport.

Again

Non utilisé.

Valeur retournée

VIRTUAL_HW_FIND_ADAPTER devez retourner l’une des valeurs status suivantes :

Code de retour	Description
SP_RETURN_FOUND	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 de PORT_CONFIGURATION_INFORMATION .
SP_RETURN_ERROR	Un HBA a été trouvé, mais une erreur s’est produite quand il a obtenu les informations de configuration. Si possible, une telle erreur doit être enregistrée avec ScsiPortLogError.
SP_RETURN_BAD_CONFIG	Les informations de configuration fournies n’étaient pas valides pour l’adaptateur.
SP_RETURN_NOT_FOUND	Aucun HBA pris en charge n’a été trouvé pour les informations de configuration fournies.

Remarques

Le champ VirtualDevice dans la structure d’informations de configuration doit être défini sur TRUE. D’autres champs peuvent être définis en fonction des besoins.

Le pilote de port appelle le VIRTUAL_HW_FIND_ADAPTER du miniport virtuel Storport à PASSIVE_LEVEL.

Le nom VirtualHwStorFindAdapter est un texte d’espace réservé pour le nom réel de la routine. Le prototype réel de cette routine est défini dans Srb.h comme suit :

typedef
ULONG
VIRTUAL_HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );

Exemples

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

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

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

_Use_decl_annotations_
ULONG
MyVirtualHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );
  {
      ...
  }

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