Objets et handles UCX utilisés par un pilote de contrôleur hôte
L’UCX étend la fonctionnalité d’objet WDF pour définir ses propres objets UCX spécifiques pour l’USB. L’UCX utilise ces objets pour mettre en file d’attente les demandes à n’importe quel pilote de contrôleur hôte sous-jacent.
Résumé
- Les objets UCX sont utilisés par le pilote du contrôleur hôte pour gérer les opérations liées au contrôleur, à son hub racine et à tous les points de terminaison.
- Les objets UCX sont créés par le pilote du contrôleur hôte et la durée de vie de chacun d’eux est gérée par l’UCX.
API importantes
L’UCX étend la fonctionnalité d’objet WDF pour définir ses propres objets UCX spécifiques pour l’USB. L’UCX utilise ces objets pour mettre en file d’attente les demandes à n’importe quel pilote de contrôleur hôte sous-jacent.
Pour en savoir plus sur les objets WDF, consultez Présentation des objects de structure.
UCXCONTROLLER : objet contrôleur hôte
Représente le contrôleur hôte créé par le pilote du contrôleur hôte. Le pilote ne doit créer qu’un seul objet de contrôleur hôte par instance de contrôleur hôte. Généralement créé dans le rappel EvtDriverDeviceAdd en appelant la méthode UcxControllerCreate.
Lorsque le pilote du contrôleur hôte crée l’objet, il inscrit son implémentation de fonctions de rappel appelées par UCX. Le pilote doit également identifier le type de bus sur lequel le contrôleur hôte est connecté, tel que ACPI ou PCI. Le pilote fournit également des informations sur l’appareil du contrôleur hôte à l’aide de la structure UCX_CONTROLLER_CONFIG transmise à l’appel UcxControllerCreate.
Pour gérer les demandes d’E/S, le pilote du contrôleur hôte doit inscrire une interface d’appareil GUID_DEVINTERFACE_USB_HOST_CONTROLLER. Le pilote n’est pas nécessaire pour implémenter les IOCTL définis dans cette interface. En revanche, le client UCX transmet les demandes IOCTL reçues sur cette interface à l’UCX en appelant UcxIoDeviceControl.
Voici les fonctions de rappel associées à l’objet du contrôleur hôte, qui sont appelées par l’UCX. Ces fonctions doivent être implémentées par le pilote du contrôleur hôte.
*EVT_UCX_CONTROLLER_USBDEVICE_ADD
Appelée lorsque le pilote de hub a déterminé, via l’interaction avec le ou les hubs externes, qu’un nouvel appareil est présent sur le bus.
*EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY
Appelée par l’UCX pour collecter des informations sur les différentes fonctionnalités prises en charge par les contrôleurs hôtes USB.
*EVT_UCX_CONTROLLER_RESET
Appelée par l’UCX pour réinitialiser le matériel du contrôleur, éventuellement en réponse à une erreur détectée.
*EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER
Utilisée pour récupérer le numéro d’image actuel à partir du contrôleur hôte, utilisé par le pilote de hub pour la planification des transferts isochrones.
UCXROOTHUB : objet hub racine
Obtient et contrôle l’état des ports racine du contrôleur hôte. Créé par le pilote du contrôleur hôte généralement dans le rappel EvtDriverDeviceAdd en appelant la méthode UcxRootHubCreate après la création de l’objet du contrôleur hôte. Il ne doit y avoir qu’un seul objet hub racine par instance de contrôleur hôte. Dans l’appel UcxRootHubCreate, le pilote enregistre ses implémentations de rappel.
EVT_UCX_ROOTHUB_GET_INFO
Renvoie le nombre de ports USB 2.0 et USB 3.0 du hub racine.
EVT_UCX_ROOTHUB_GET_20PORT_INFO
Renvoie les informations sur les ports USB 2.0 ou USB 3.0 (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) du hub racine.
Une fois l’objet hub racine créé et initialisé, le pilote de hub interagit avec les ports du hub racine en envoyant des interruptions et des transferts de contrôle. L’UCX contribue à ces transferts en appelant ces fonctions de rappel implémentées par le pilote du contrôleur hôte.
EVT_UCX_ROOTHUB_CONTROL_URB
Gère les demandes de contrôle des fonctionnalités par le hub USB.
EVT_UCX_ROOTHUB_INTERRUPT_TX
Gère les demandes d’information sur les ports modifiés.
Pour en savoir plus, consultez les Fonctions de rappel du hub racine d’un pilote de contrôleur hôte.
UCXUSBDEVICE : objet d’appareil USB
Représente un périphérique USB physique connecté au bus. Créé par le pilote du contrôleur hôte généralement dans le rappel EVT_UCX_CONTROLLER_USBDEVICE_ADD en appelant la méthode UcxUsbDeviceCreate.
Lorsque l’objet est créé, le pilote du contrôleur hôte enregistre son implémentation des fonctions de rappel avec l’appel UcxUsbDeviceCreate.
Ces fonctions de rappel sont destinées à maintenir le contrôleur et le pilote informés de l’état actuel des appareils USB.
EVT_UCX_USBDEVICE_ENABLE
Prépare le contrôleur pour effectuer des transferts vers le point de terminaison par défaut de l’appareil.
EVT_UCX_USBDEVICE_DISABLE
Libère les ressources du contrôleur associées à l’appareil et à son point de terminaison par défaut.
EVT_UCX_USBDEVICE_ADDRESS
Programmes une adresse dans le contrôleur et envoie un transfert SET_ADDRESS à l’appareil, pour le faire passer à l’état adressé.
EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE
Programme des points de terminaison non définis par défaut dans le contrôleur et/ou libère d’autres points de terminaison non définis par défaut.
EVT_UCX_USBDEVICE_RESET
Notification de contrôleur indiquant qu’un appareil a été réinitialisé, auquel cas le pilote effectue toute action nécessaire pour synchroniser le contrôleur avec l’appareil USB.
EVT_UCX_USBDEVICE_UPDATE
Avertit le contrôleur de différents bits d’informations liés à l’appareil.
EVT_UCX_USBDEVICE_HUB_INFO
Notification sur les propriétés du hub, si le handle UCXUSBDEVICE est destiné à un appareil hub.
EVT_UCX_USBDEVICE_ENDPOINT_ADD
Avertit le pilote de créer un point de terminaison pour l’appareil. EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD pour le point de terminaison par défaut.
Lorsqu’une interface sur un appareil USB 3.0 suspendu a signalé un réveil, le pilote est censé appeler UcxUsbDeviceRemoteWakeNotification pour avertir l’UCX.
Une fois l’objet créé, sa durée de vie est gérée par l’UCX et le pilote ne doit pas le supprimer.
UCXENDPOINT : objet point de terminaison
Représente un point de terminaison sur un objet d’appareil USB. Les objets de point de terminaison sont créés par le contrôleur hôte pendant un rappel EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD ou EVT_UCX_USBDEVICE_ENDPOINT_ADD. Lorsqu’un objet de point de terminaison est créé, le pilote enregistre ses fonctions de rappel.
Il crée également un objet de file d’attente d’infrastructure pour chaque point de terminaison et transmet la WDFQUEUE pour cette file d’attente à l’UCX en appelant UcxEndpointSetWdfIoQueue. Une fois le point de terminaison créé, la durée de vie de l’objet et ses files d’attente associées sont gérées par l’UCX, et le pilote ne doit pas supprimer lui-même ces objets.
L’objet de point de terminaison implémente plusieurs fonctions de rappel grâce auxquelles le pilote peut aider l’UCX à effectuer des opérations liées au point de terminaison.
EVT_UCX_ENDPOINT_ABORT
Annuler la file d’attente associée au point de terminaison.
EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS
Avertir le pilote du contrôleur qu’il peut effectuer les transferts annulés sur le point de terminaison.
EVT_UCX_ENDPOINT_PURGE
Effectuer toutes les demandes d’E/S en attente sur le point de terminaison.
EVT_UCX_ENDPOINT_START
Lancer la file d’attente associée au point de terminaison.
EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD
Créer des flux statiques.
EVT_UCX_ENDPOINT_RESET
Avertir le pilote de réinitialiser la programmation du contrôleur du point de terminaison.
Lorsque le pilote du contrôleur hôte reçoit une erreur USB 3.0 Aucune réponse au test Ping sur un point de terminaison, il doit appeler UcxEndpointNoPingResponseError. Cet appel a pour conséquence que l’objet d’appareil USB reçoit d’EVT_UCX_USBDEVICE_UPDATE. Pour en savoir plus, consultez Configuration des points de terminaison USB dans un pilote de contrôleur hôte.
UCXSTREAMS : objet de flux
Représente un certain nombre de canaux vers l’appareil à travers un seul point de terminaison. Le pilote du contrôleur hôte crée des objets de flux dans le rappel EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD en appelant UcxStaticStreamsCreate.
Pendant l’appel UcxStaticStreamsCreate, le pilote du contrôleur hôte enregistre ses fonctions de rappel. Pour un objet de point de terminaison spécifique, le pilote peut déterminer s’il a créé un objet de flux et renvoyer le handle UCXSTREAMS en appelant UcxEndpointGetStaticStreamsReferenced.
Une fois l’objet créé, le pilote crée un objet de file d’attente d’infrastructure pour chaque flux et envoie le handle WDFQUEUE à l’UCX en appelant UcxStaticStreamsSetStreamInfo.
L’objet de flux fournit plusieurs fonctions de rappel pour le contrôleur hôte afin d’aider l’UCX à gérer les flux statiques.
EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE
Libérer les ressources du contrôleur pour tous les flux d’un point de terminaison.
EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE
Activer le matériel du contrôleur de tous les flux pour ce point de terminaison.
La durée de vie de l’objet et des files d’attente associées est gérée par l’UCX, et le pilote ne doit pas supprimer les objets.