PVIDEO_HW_FIND_ADAPTER fonction de rappel (video.h)

Article
08/07/2023

HwVidFindAdapter effectue l’initialisation des données spécifiques au pilote miniport et aux périphériques pris en charge par le pilote miniport.

Syntaxe

PVIDEO_HW_FIND_ADAPTER PvideoHwFindAdapter;

VP_STATUS PvideoHwFindAdapter(
  PVOID HwDeviceExtension,
  PVOID HwContext,
  PWSTR ArgumentString,
  PVIDEO_PORT_CONFIG_INFO ConfigInfo,
  PUCHAR Again
)
{...}

Paramètres

HwDeviceExtension

Pointeur vers la zone de stockage par périphérique du pilote. Pour plus d’informations, consultez Extensions d’appareil.

HwContext

A la valeur NULL et doit être ignoré par le pilote miniport.

ArgumentString

Pointeur vers une chaîne ASCII terminée par null qui provient de l’utilisateur. Ce pointeur peut être NULL.

ConfigInfo

Pointeur vers une structure VIDEO_PORT_CONFIG_INFO . Le pilote de port vidéo alloue de la mémoire pour et initialise cette structure avec toutes les informations de configuration connues, telles que le numéro de bus d’E/S système et les valeurs définies par le pilote miniport dans la structure VIDEO_HW_INITIALIZATION_DATA .

Again

Doit être ignoré par le pilote miniport.

Valeur retournée

HwVidFindAdapter doit retourner l’un des codes status suivants :

Code de retour	Description
ERROR_DEV_NOT_EXIST	Indique, pour un bus réumable, que le pilote miniport n’a pas pu trouver l’appareil.
ERROR_INVALID_PARAMETER	Indique que le pilote miniport n’a pas pu configurer ou initialiser correctement l’adaptateur.
NO_ERROR	Indique la réussite de l’opération.

Remarques

Chaque pilote de miniport vidéo doit avoir une fonction HwVidFindAdapter .

Le pilote de port vidéo effectue les opérations suivantes avant d’appeler HwVidFindAdapter :

Alloue du stockage pour la zone de stockage par adaptateur du pilote miniport en fonction de la valeur de HwDeviceExtensionSize que la fonction DriverEntry du pilote miniport spécifiée dans la structure VIDEO_HW_INITIALIZATION_DATA et initialise zéro le stockage alloué.
Alloue du stockage pour une structure VIDEO_PORT_CONFIG_INFO et remplit toutes les informations disponibles en fonction des informations fournies par le pilote miniport dans VIDEO_HW_INITIALIZATION_DATA.

Le pilote de port vidéo appelle ensuite la fonction HwVidFindAdapter du pilote miniport avec des pointeurs vers la zone de stockage initialisée par carte et les informations de configuration dans les paramètres HwDeviceExtension et ConfigInfo , respectivement.

La fonction HwVidFindAdapter pour les appareils sur un bus énumérable doit effectuer les opérations suivantes :

Vérifiez la taille de la structure VIDEO_PORT_CONFIG_INFO vers laquelle ConfigInfo pointe pour garantir un contrôle de version correct.
Appelez VideoPortGetAccessRanges pour obtenir les adresses physiques relatives au bus auxquelles l’appareil répondra. Ces adresses sont affectées par le gestionnaire PnP. Le pilote miniport doit passer null dans les paramètres VendorId, DeviceId et Slot de VideoPortGetAccessRanges.
Pour les pilotes miniport qui prennent en charge plusieurs types d’appareils, déterminez le type de périphérique détecté par le gestionnaire PnP. Le pilote miniport peut appeler VideoPortGetBusData pour obtenir des informations de configuration PCI.
Renseignez toutes les informations de configuration pertinentes mais manquantes dans les membres appropriés de la structure VIDEO_PORT_CONFIG_INFO avec des données spécifiques à l’adaptateur.

HwVidFindAdapter ne doit pas tenter d’initialiser l’appareil.

HwVidFindAdapter peut allouer des ressources, telles que de la mémoire et des verrous, à utiliser par le pilote miniport. Ces ressources peuvent être spécifiques à un appareil ou être partagées par plusieurs appareils pris en charge par le pilote miniport. Si HwVidFindAdapter retourne une valeur autre que NO_ERROR, il doit libérer toutes les ressources spécifiques à l’appareil avant de retourner. Pour les ressources partagées entre plusieurs appareils, HwVidFindAdapter doit conserver un nombre de références. Par exemple, le nombre de références peut indiquer le nombre d’appels précédents à HwVidFindAdapter qui ont réussi. De cette façon, si HwVidFindAdapter doit échouer et qu’il détermine que tous les appels précédents à HwVidFindAdapter ont échoué, il peut libérer les ressources partagées.

Si HwVidFindAdapter échoue chaque fois qu’il est appelé par le pilote de port vidéo, le système d’exploitation peut décharger le pilote miniport ultérieurement. Dans ce cas, toutes les ressources que HwVidFindAdapter a allouées mais n’ont pas libérées fuit.

Pour un appareil sur un bus rééumable tel qu’ISA, PnP tente toujours de démarrer l’appareil, bien qu’il soit de la responsabilité de HwVidFindAdapter de déterminer si l’appareil est réellement présent. Si l’appareil est introuvable, HwVidFindAdapter doit retourner ERROR_DEV_NOT_EXIST.

HwVidFindAdapter doit également appeler VideoPortSetRegistryParameters pour stocker des informations spécifiques à l’adaptateur dans la clé HardwareInformation . Ces informations sont utilisées par le programme Afficher dans Panneau de configuration. Pour plus d’informations, consultez Définition des informations matérielles dans le Registre .

Selon l’adaptateur et la valeur AdapterInterfaceType dans VIDEO_PORT_CONFIG_INFO, HwVidFindAdapter peut appeler certaines des fonctions VideoPortXxx suivantes pour obtenir les données de configuration relatives du bus et les plages d’accès mappées nécessaires pour communiquer avec l’adaptateur :

VideoPortGetBusData pour obtenir des informations de configuration spécifiques au type de bus sur un adaptateur sur un bus d’E/S particulier.
VideoPortGetDeviceData pour obtenir des informations spécifiques à VIDEO_DEVICE_DATA_TYPE à partir du registre et appeler HwVidQueryDeviceCallback pour traiter ces informations.
VideoPortGetRegistryParameters pour obtenir des informations de configuration à partir du Registre.
VideoPortGetAccessRanges pour obtenir des adresses de plages d’accès relatives aux bus et éventuellement d’autres valeurs de configuration matérielle, et pour les revendiquer dans le Registre pour les utiliser par le pilote d’une carte.
VideoPortVerifyAccessRanges pour déterminer si la mémoire vidéo relative du bus et/ou les ports d’E/S de l’adaptateur peuvent être revendiqués par le pilote miniport ; dans le cas contraire, un pilote précédemment chargé a déjà revendiqué la ressource dans le Registre et HwVidFindAdapter doit essayer de revendiquer d’autres plages d’accès si possible ou échoue.
VideoPortGetDeviceBase pour mapper chaque adresse de base et la taille de plage relatives de bus correctement revendiquées, comme décrit dans une structure de VIDEO_ACCESS_RANGE , aux adresses logiques de l’espace système . HwVidFindAdapter doit appeler correctement VideoPortVerifyAccessRanges ou VideoPortGetAccessRanges avant de pouvoir appeler VideoPortGetDeviceBase.

Si le pilote ne gère pas les interruptions, HwVidFindAdapter doit définir BusInterruptLevel et BusInterruptVector dans la structure VIDEO_PORT_CONFIG_INFO sur zéro après son appel à VideoPortGetAccessRanges. Si les deux membres sont zéro, le pilote de port vidéo ne connecte pas l’interruption pour le pilote miniport. Définir explicitement BusInterruptLevel et BusInterruptVector sur zéro dans HwVidFindAdapter désactive le point d’entrée HwVidInterrupt , le cas échéant, qui a été configuré par la routine DriverEntry du pilote miniport.

HwVidFindAdapter ne doit pas laisser un adaptateur non pris en charge dont l’état a changé. Pour les adaptateurs VGA/SVGA, HwVidFindAdapter doit laisser l’adaptateur dans un état VGA et restaurer tous les registres étendus qu’il a pu modifier à leur condition d’origine.

HwVidFindAdapter doit être rendu paginable.