Objets et handles UCX utilisés par un pilote de contrôleur hôte

  • Article

UCX étend la fonctionnalité d’objet WDF pour définir ses propres objets UCX spécifiques à USB. UCX utilise ces objets pour mettre en file d’attente les demandes adressées à 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 chaque objet est gérée par UCX.

API importantes

UCX étend la fonctionnalité d’objet WDF pour définir ses propres objets UCX spécifiques à USB. UCX utilise ces objets pour mettre en file d’attente les demandes adressées à n’importe quel pilote de contrôleur hôte sous-jacent.

Pour plus d’informations sur les objets WDF, consultez Présentation des objets framework.

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 contrôleur hôte instance. 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 des 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é, par exemple ACPI ou PCI. Le pilote fournit également des informations sur le périphérique du contrôleur hôte à l’aide de la structure UCX_CONTROLLER_CONFIG qui est passée à l’appel UcxControllerCreate .

Pour gérer les demandes d’E/S, le pilote du contrôleur hôte doit inscrire une interface de périphérique GUID_DEVINTERFACE_USB_HOST_CONTROLLER. Le pilote n’est pas nécessaire pour implémenter les IOCTL définis dans cette interface. Au lieu de cela, le client UCX transmet les requêtes IOCTL reçues sur cette interface à UCX en appelant UcxIoDeviceControl.

Voici les fonctions de rappel associées à l’objet contrôleur hôte, qui sont appelées par UCX. Ces fonctions doivent être implémentées par le pilote du contrôleur hôte.

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD Appelé lorsque le pilote du hub a déterminé, via l’interaction avec le hub racine et/ou le ou les hubs externes, qu’un nouvel appareil est présent sur le bus.

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY Appelé par 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é par 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é pour récupérer le numéro d’image actuel du contrôleur hôte, qui est utilisé par le pilote hub pour la planification des transferts isochroneuses.

UCXROOTHUB : objet hub racine

Obtient et contrôle la status 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 contrôleur hôte. Il ne doit y avoir qu’un seul objet hub racine par contrôleur hôte instance. Dans l’appel UcxRootHubCreate , le pilote enregistre ses implémentations de rappel.


EVT_UCX_ROOTHUB_GET_INFO Retourne le nombre de ports USB 2.0 et USB 3.0 du hub racine.


EVT_UCX_ROOTHUB_GET_20PORT_INFO Retourner des 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 transferts d’interruption et de contrôle. UCX facilite 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 la demande d’informations sur les ports modifiés.

Pour plus d’informations, consultez Fonctions de rappel de hub racine d’un pilote de contrôleur hôte.

UCXUSBDEVICE : objet périphérique 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 EVT_UCX_CONTROLLER_USBDEVICE_ADD rappel en appelant la méthode UcxUsbDeviceCreate .

Lorsque l’objet est créé, le pilote du contrôleur hôte inscrit son implémentation des fonctions de rappel avec l’appel UcxUsbDeviceCreate .

Ces fonctions de rappel sont destinées à tenir le contrôleur et le pilote informés de la status actuelle des périphériques USB.


EVT_UCX_USBDEVICE_ENABLE Prépare le contrôleur à 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 Programme une adresse dans le contrôleur et envoie un transfert SET_ADDRESS à l’appareil, pour le ramener à l’état adressé.


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE Programme des points de terminaison autres que les points de terminaison par défaut dans le contrôleur et/ou libère d’autres points de terminaison non par défaut.


EVT_UCX_USBDEVICE_RESET Notification du contrôleur indiquant qu’un appareil a été réinitialisé, auquel cas le pilote prend toutes les mesures nécessaires pour synchroniser le contrôleur avec le périphérique USB.


EVT_UCX_USBDEVICE_UPDATE Avertit le contrôleur de divers éléments 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 périphérique USB 3.0 suspendu a signalé la mise en éveil, le pilote est censé appeler UcxUsbDeviceRemoteWakeNotification pour avertir UCX.

Une fois l’objet créé, la durée de vie de l’objet est gérée par UCX et le pilote ne doit pas supprimer l’objet.

UCXENDPOINT : objet Endpoint

Représente un point de terminaison sur un objet de périphérique USB. Les objets de point de terminaison sont créés par le contrôleur hôte lors d’un rappel EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD ou d’un rappel EVT_UCX_USBDEVICE_ENDPOINT_ADD . Lorsqu’un objet de point de terminaison est créé, le pilote inscrit ses fonctions de rappel.

Le pilote crée également un objet de file d’attente d’infrastructure pour chaque point de terminaison et transmet le WDFQUEUE de cette file d’attente à UCX en appelant UcxEndpointSetWdfIoQueue. Une fois le point de terminaison créé, la durée de vie de l’objet et de ses files d’attente associées est gérée par UCX, et le pilote ne doit pas supprimer ces objets lui-même.

L’objet endpoint implémente plusieurs fonctions de rappel qui permettent au pilote d’aider UCX avec les opérations liées au point de terminaison.


EVT_UCX_ENDPOINT_ABORT Abandonnez la file d’attente associée au point de terminaison.


EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS Informez le pilote du contrôleur qu’il peut effectuer des transferts annulés sur le point de terminaison.


EVT_UCX_ENDPOINT_PURGE Terminez toutes les demandes d’E/S en suspens sur le point de terminaison.


EVT_UCX_ENDPOINT_START Démarrez la file d’attente associée au point de terminaison.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD Créez des flux statiques.


EVT_UCX_ENDPOINT_RESET Informez 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 de réponse usb 3.0 no ping sur un point de terminaison, le pilote doit appeler UcxEndpointNoPingResponseError. Cet appel entraîne la réception d’EVT_UCX_USBDEVICE_UPDATE par l’objet périphérique USB. Pour plus d’informations, consultez Configuration de points de terminaison USB dans un pilote de contrôleur hôte.

UCXSTREAMS : objet Stream

Représente un certain nombre de canaux vers l’appareil sur un point de terminaison unique. 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 inscrit 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 retourner 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 à UCX en appelant UcxStaticStreamsSetStreamInfo.

L’objet stream fournit plusieurs fonctions de rappel pour le contrôleur hôte afin d’aider UCX à gérer les flux statiques.


EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE Ressources du contrôleur de mise en production pour tous les flux d’un point de terminaison.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE Activez le matériel de 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 UCX, et le pilote ne doit pas supprimer les objets.