Share via

UCX-Objekte und -Handles, die von einem Hostcontrollertreiber verwendet werden

  • Artikel

UCX erweitert die WDF-Objektfunktionalität, um eigene USB-spezifische UCX-Objekte zu definieren. UCX verwendet diese Objekte zum Anstellen von Anforderungen an einen zugrunde liegenden Hostcontrollertreiber.

Zusammenfassung

  • UCX-Objekte werden vom Hostcontrollertreiber verwendet, um Vorgänge im Zusammenhang mit dem Controller, seinem Stammhub und allen Endpunkten zu verarbeiten.
  • UCX-Objekte werden vom Hostcontrollertreiber erstellt, und die Lebensdauer jedes Objekts wird von UCX verwaltet.

Wichtige APIs

UCX erweitert die WDF-Objektfunktionalität, um eigene USB-spezifische UCX-Objekte zu definieren. UCX verwendet diese Objekte zum Anstellen von Anforderungen an einen zugrunde liegenden Hostcontrollertreiber.

Weitere Informationen zu WDF-Objekten finden Sie unter Einführung in Framework-Objekte.

UCXCONTROLLER: Hostcontrollerobjekt

Stellt den Hostcontroller dar, der vom Hostcontrollertreiber erstellt wird. Der Treiber darf nur ein Hostcontrollerobjekt pro Hostcontroller instance erstellen. In der Regel im EvtDriverDeviceAdd-Rückruf erstellt, indem die UcxControllerCreate-Methode aufgerufen wird.

Wenn der Hostcontrollertreiber das Objekt erstellt, registriert der Treiber seine Implementierung von Rückruffunktionen, die von UCX aufgerufen werden. Der Treiber sollte zusätzlich den Bustyp identifizieren, über den der Hostcontroller verbunden ist, z. B. ACPI oder PCI. Der Treiber stellt auch Hostcontroller-Geräteinformationen mithilfe der UCX_CONTROLLER_CONFIG-Struktur bereit, die an den UcxControllerCreate-Aufruf übergeben wird.

Zum Verarbeiten von E/A-Anforderungen muss der Hostcontrollertreiber eine GUID_DEVINTERFACE_USB_HOST_CONTROLLER Geräteschnittstelle registrieren. Der Treiber ist nicht erforderlich, um die in dieser Schnittstelle definierten IOCTLs zu implementieren. Stattdessen übergibt der UCX-Client die IOCTL-Anforderungen, die auf dieser Schnittstelle empfangen werden, an UCX, indem er UcxIoDeviceControl aufruft.

Hier sind die Rückruffunktionen aufgeführt, die dem Hostcontrollerobjekt zugeordnet sind, die von UCX aufgerufen werden. Diese Funktionen müssen vom Hostcontrollertreiber implementiert werden.

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD Wird aufgerufen, wenn der Hubtreiber über die Interaktion mit dem Stammhub und/oder externen Hub(s) festgestellt hat, dass ein neues Gerät im Bus vorhanden ist.

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY Wird von UCX aufgerufen, um Informationen zu verschiedenen Features zu sammeln, die von USB-Hostcontrollern unterstützt werden.

*
EVT_UCX_CONTROLLER_RESET Wird von UCX aufgerufen, um die Controllerhardware zurückzusetzen, möglicherweise als Reaktion auf einen erkannten Fehler.

*
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER Dient zum Abrufen der aktuellen Framenummer vom Hostcontroller, der vom Hubtreiber zum Planen isochroner Übertragungen verwendet wird.

UCXROOTHUB: Root Hub-Objekt

Ruft die status der Stammports des Hostcontrollers ab und steuert sie. Wird vom Hostcontrollertreiber in der Regel innerhalb des EvtDriverDeviceAdd-Rückrufs erstellt, indem die UcxRootHubCreate-Methode aufgerufen wird, nachdem das Hostcontrollerobjekt erstellt wurde. Pro Hostcontroller sollte nur ein Stammhubobjekt instance vorhanden sein. Im UcxRootHubCreate-Aufruf registriert der Treiber seine Rückrufimplementierungen.


EVT_UCX_ROOTHUB_GET_INFO Gibt die Anzahl der USB 2.0- und USB 3.0-Ports des Stammhubs zurück.


EVT_UCX_ROOTHUB_GET_20PORT_INFO Gibt Informationen zu den USB 2.0- oder USB 3.0-Anschlüssen (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) des Stammhubs zurück.

Nachdem das Stammhubobjekt erstellt und initialisiert wurde, interagiert der Hubtreiber mit den Stammhubports, indem er Interrupt- und Steuerungsübertragungen sendet. UCX unterstützt diese Übertragungen, indem diese Rückruffunktionen aufgerufen werden, die vom Hostcontrollertreiber implementiert werden.


EVT_UCX_ROOTHUB_CONTROL_URB Verarbeitet Funktionssteuerungsanforderungen durch den USB-Hub.


EVT_UCX_ROOTHUB_INTERRUPT_TX Verarbeitet die Anforderung von Informationen zu geänderten Ports.

Weitere Informationen finden Sie unter Root Hub-Rückruffunktionen eines Hostcontrollertreibers.

UCXUSBDEVICE: USB-Geräteobjekt

Stellt ein physisches USB-Gerät dar, das mit dem Bus verbunden ist. Wird vom Hostcontrollertreiber in der Regel innerhalb des EVT_UCX_CONTROLLER_USBDEVICE_ADD Rückrufs erstellt, indem die UcxUsbDeviceCreate-Methode aufgerufen wird .

Wenn das Objekt erstellt wird, registriert der Hostcontrollertreiber seine Implementierung der Rückruffunktionen mit dem UcxUsbDeviceCreate-Aufruf .

Diese Rückruffunktionen sollen Controller und Treiber über die aktuelle status von USB-Geräten auf dem Laufenden halten.


EVT_UCX_USBDEVICE_ENABLE Bereitet den Controller für die Durchführung von Übertragungen an den Standardendpunkt des Geräts vor.


EVT_UCX_USBDEVICE_DISABLE Gibt Controllerressourcen frei, die dem Gerät und seinem Standardendpunkt zugeordnet sind.


EVT_UCX_USBDEVICE_ADDRESS Programmiert eine Adresse in den Controller und sendet eine SET_ADDRESS Übertragung an das Gerät, um es in den adressierten Zustand zu bringen.


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE Programmiert nicht standardmäßige Endpunkte in den Controller und/oder gibt andere nicht standardmäßige Endpunkte frei.


EVT_UCX_USBDEVICE_RESET Eine Controllerbenachrichtigung, dass ein Gerät zurückgesetzt wurde. In diesem Fall ergreift der Treiber alle erforderlichen Maßnahmen, um den Controller mit dem USB-Gerät zu synchronisieren.


EVT_UCX_USBDEVICE_UPDATE Benachrichtigt den Controller über verschiedene Informationen im Zusammenhang mit dem Gerät.


EVT_UCX_USBDEVICE_HUB_INFO Eine Benachrichtigung über Hubeigenschaften, wenn das UCXUSBDEVICE-Handle für ein Hubgerät gilt.


EVT_UCX_USBDEVICE_ENDPOINT_ADD Benachrichtigt den Treiber, einen Endpunkt für das Gerät zu erstellen. EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD für den Standardendpunkt.

Wenn eine Schnittstelle auf einem angehaltenen USB 3.0-Gerät die Aktivierung signalisiert hat, wird erwartet, dass der Treiber UcxUsbDeviceRemoteWakeNotification aufruft , um UCX zu benachrichtigen.

Nachdem das Objekt erstellt wurde, wird die Lebensdauer des Objekts von UCX verwaltet, und der Treiber darf das Objekt nicht löschen.

UCXENDPOINT: Endpunktobjekt

Stellt einen Endpunkt auf einem USB-Geräteobjekt dar. Endpunktobjekte werden vom Hostcontroller entweder während eines EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD oder eines EVT_UCX_USBDEVICE_ENDPOINT_ADD-Rückrufs erstellt. Wenn ein Endpunktobjekt erstellt wird, registriert der Treiber seine Rückruffunktionen.

Der Treiber erstellt auch ein Framework-Warteschlangenobjekt für jeden Endpunkt und übergibt das WDFQUEUE für diese Warteschlange an UCX, indem ucxEndpointSetWdfIoQueue aufgerufen wird. Nachdem der Endpunkt erstellt wurde, wird die Lebensdauer des Objekts und der zugehörigen Warteschlangen von UCX verwaltet, und der Treiber darf diese Objekte selbst nicht löschen.

Das Endpunktobjekt implementiert mehrere Rückruffunktionen, mit denen der Treiber UCX bei Vorgängen im Zusammenhang mit dem Endpunkt unterstützen kann.


EVT_UCX_ENDPOINT_ABORT Abbrechen der Warteschlange, die dem Endpunkt zugeordnet ist.


EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS Benachrichtigen Sie den Controllertreiber, dass er abgebrochene Übertragungen auf dem Endpunkt abschließen kann.


EVT_UCX_ENDPOINT_PURGE Schließen Sie alle ausstehenden E/A-Anforderungen auf dem Endpunkt ab.


EVT_UCX_ENDPOINT_START Starten Sie die dem Endpunkt zugeordnete Warteschlange.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD Erstellen sie statische Datenströme.


EVT_UCX_ENDPOINT_RESET Benachrichtigen Sie den Treiber, um die Programmierung des Endpunkts durch den Controller zurückzusetzen.

Wenn der Hostcontrollertreiber einen USB 3.0 No Ping Response Error auf einem Endpunkt empfängt, muss der Treiber UcxEndpointNoPingResponseError aufrufen. Dieser Aufruf führt dazu, dass das USB-Geräteobjekt EVT_UCX_USBDEVICE_UPDATE empfängt. Weitere Informationen finden Sie unter Konfigurieren von USB-Endpunkten in einem Hostcontrollertreiber.

UCXSTREAMS: Stream-Objekt

Stellt eine Reihe von Pipes an das Gerät über einen einzelnen Endpunkt dar. Der Hostcontrollertreiber erstellt Streamobjekte im EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD Rückruf durch Aufrufen von UcxStaticStreamsCreate.

Während des UcxStaticStreamsCreate-Aufrufs registriert der Hostcontrollertreiber seine Rückruffunktionen. Für ein bestimmtes Endpunktobjekt kann der Treiber bestimmen, ob er ein Streams-Objekt erstellt hat, und das UCXSTREAMS-Handle zurückgeben, indem er UcxEndpointGetStaticStreamsReferenced aufruft.

Nachdem das Objekt erstellt wurde, erstellt der Treiber ein Frameworkwarteschlangenobjekt für jeden Stream und sendet das WDFQUEUE-Handle an UCX, indem UcxStaticStreamsSetStreamInfo aufgerufen wird.

Das Streamobjekt stellt mehrere Rückruffunktionen für den Hostcontroller bereit, um UCX bei der Verwaltung der statischen Datenströme zu unterstützen.


EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE Freigeben von Controllerressourcen für alle Streams für einen Endpunkt.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE Aktivieren Sie controllerhardware aller Streams für diesen Endpunkt.

Die Lebensdauer des Objekts und der zugehörigen Warteschlangen werden von UCX verwaltet, und der Treiber darf die Objekte nicht löschen.