Fonction ScsiPortValidateRange (srb.h)

Article
08/07/2023

La routine ScsiPortValidateRange indique si les valeurs de plage d’accès spécifiées ont déjà été revendiquées dans le Registre par un autre pilote.

Note Les modèles de pilote de port SCSI et de pilote miniport SCSI peuvent être modifiés ou indisponibles à l’avenir. Au lieu de cela, nous vous recommandons d’utiliser les modèles de pilote Storport et de pilote Miniport Storport .

Syntaxe

SCSIPORT_API BOOLEAN ScsiPortValidateRange(
  [in] PVOID                 HwDeviceExtension,
  [in] INTERFACE_TYPE        BusType,
  [in] ULONG                 SystemIoBusNumber,
  [in] SCSI_PHYSICAL_ADDRESS IoAddress,
  [in] ULONG                 NumberOfBytes,
  [in] BOOLEAN               InIoSpace
);

Paramètres

[in] HwDeviceExtension

Pointeur vers l’extension de périphérique matériel. Il s’agit d’une zone de stockage par adaptateur HBA que le pilote de port alloue et initialise pour le compte du pilote miniport. Les pilotes miniport stockent généralement des informations spécifiques à L’adaptateur HBA dans cette extension, telles que l’état de l’adaptateur HBA et les plages d’accès mappées de l’adaptateur HBA. Cette zone est disponible pour le pilote miniport dans le membre DeviceExtension-HwDeviceExtension> de l’objet d’appareil de l’adaptateur HBA immédiatement après que le pilote miniport a appelé ScsiPortInitialize. Le pilote de port libère cette mémoire lorsqu’il supprime l’appareil.

[in] BusType

Spécifie la valeur du membre AdapterInterfaceType dans la structure PORT_CONFIGURATION_INFORMATION lorsque HwScsiFindAdapter est appelé.

[in] SystemIoBusNumber

Spécifie la valeur du membre SystemIoBusNumber dans les informations de configuration lorsque HwScsiFindAdapter est appelé.

[in] IoAddress

Spécifie une adresse de base relative au bus pour la plage de ports ou la mémoire de l’appareil à valider avant que la routine HwScsiFindAdapter du pilote miniport ne tente de mapper la plage d’accès pour l’adaptateur à cette adresse.

[in] NumberOfBytes

Spécifie la taille en octets ou le nombre d’éléments dans la plage.

[in] InIoSpace

Indique quand TRUE que la plage se trouve dans l’espace d’E/S, plutôt que dans la mémoire. Lorsque la valeur est FALSE, la plage se trouve dans l’espace mémoire.

Valeur retournée

ScsiPortValidateRange retourne TRUE si la routine HwScsiFindAdapter peut mapper en toute sécurité et utiliser la plage mappée pour accéder à l’adaptateur. ScsiPortValidateRange retourne FALSE si les valeurs de plage d’accès spécifiées ont déjà été revendiquées dans le Registre par un autre pilote.

Remarques

ScsiPortValidateRange peut être appelé uniquement à partir de la routine HwScsiFindAdapter d’un pilote miniport. Les appels d’autres routines de pilotes miniport entraînent une défaillance du système ou un fonctionnement incorrect pour l’appelant.

Si le pilote de port spécifique au système d’exploitation initialise un élément AccessRanges de la structure PORT_CONFIGURATION_INFORMATION avant d’appeler la routine HwScsiFindAdapter du pilote miniport, le pilote miniport doit passer les valeurs fournies à ScsiPortGetDeviceBase et utiliser les adresses logiques mappées pour la plage pour déterminer si un adaptateur HBA est celui qu’il prend en charge.

Le pilote de port remplit un élément de type ACCESS_RANGE avec une description complète d’une plage d’adresses relative au bus pour une carte, ou le pilote de port supprime tous les membres de l’élément.

Pour les éléments AccessRanges d’entrée définis avec des zéros par défaut, la routine HwScsiFindAdapter peut tenter de localiser une carte qu’elle prend en charge sur le bus d’E/S donné. Dans ces circonstances, un pilote miniport a généralement un ensemble d’adresses par défaut déterminées par le pilote pour ses types de HBA. Toutefois, un pilote précédemment chargé utilise peut-être déjà un adaptateur initialisé dans l’une des plages d’adresses par défaut de ce pilote miniport, en particulier dans les systèmes x86 uniquement dans lesquels certains appareils sont initialisés en mode réel x86. Pour éviter qu’un tel appareil ne soit reprogrammé par inadvertance, la routine HwScsiFindAdapter de chaque pilote miniport doit appeler ScsiPortValidateRange avant de mapper toutes les adresses fournies par le pilote avec ScsiPortGetDeviceBase , puis utiliser les adresses logiques mappées pour interroger les cartes sur un bus d’E/S.

Si ScsiPortValidateRange renvoie FALSE, HwScsiFindAdapter ne doit pas tenter de mapper les adresses de plage d’entrée, car un autre pilote a déjà revendiqué la plage dans le Registre.

Si ScsiPortValidateRange retourne TRUE, HwScsiFindAdapter peut effectuer les opérations suivantes en toute sécurité :

Mapper les adresses de plage relative du bus aux adresses de plage logique d’espace système avec ScsiPortGetDeviceBase.
Utilisez les adresses logiques mappées avec ScsiPortRead/WriteXxx pour déterminer si l’adaptateur est réellement un adaptateur HBA pris en charge par le pilote.

Si un pilote miniport utilise une plage correctement passée à ScsiPortValidateRange pour un adaptateur HBA qu’il prend en charge, ce pilote doit inverser la valeur InIoSpace lorsqu’il définit le membre RangeInMemory d’un élément AccessRanges dans le PORT_CONFIGURATION_INFORMATION.

ScsiPortValidateRange utilise SCSI_PHYSICAL_ADDRESS pour représenter les adresses relatives au bus.

typedef PHYSICAL_ADDRESS SCSI_PHYSICAL_ADDRESS, *PSCSI_PHYSICAL_ADDRESS;

Le type SCSI_PHYSICAL_ADDRESS est un type de données indépendant du système d’exploitation que les pilotes miniports SCSI utilisent pour représenter une adresse physique ou une adresse relative de bus.