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 für Warteschlangenanforderungen an einen zugrunde liegenden Hostcontrollertreiber.

Zusammenfassung

  • UCX-Objekte werden vom Hostcontrollertreiber verwendet, um Vorgänge im Zusammenhang mit dem Controller, dem 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 für Warteschlangenanforderungen an einen zugrunde liegenden Hostcontrollertreiber.

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

UCXCONTROLLER: Hostcontrollerobjekt

Stellt den Hostcontroller dar, der vom Hostcontrollertreiber erstellt wird. Der Treiber muss pro Hostcontrollerinstanz nur ein Hostcontrollerobjekt erstellen. Wird normalerweise innerhalb des Rückrufs EvtDriverDeviceAdddurch Aufrufen der Methode UcxControllerCreate erstellt.

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 angeschlossen ist, z. B. ACPI oder PCI. Der Treiber stellt außerdem Hostcontrollergeräteinformationen mithilfe der UCX_CONTROLLER_CONFIG -Struktur bereit, die an den UcxControllerCreate übergeben wird.

Um E/A-Anforderungen zu verarbeiten, 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 auf dieser Schnittstelle empfangenen IOCTL-Anforderungen durch Aufrufen von UcxIoDeviceControl an UCX.

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

*EVT_UCX_CONTROLLER_USBDEVICE_ADD
Wird aufgerufen, wenn der Hub-Treiber durch Interaktion mit dem Root-Hub und/oder externen Hubs festgestellt hat, dass ein neues Gerät auf dem Bus vorhanden ist.

*EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY
Wird von UCX aufgerufen, um Informationen zu verschiedenen von USB-Hostcontrollern unterstützten Funktionen zu sammeln.

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

*EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER
Wird verwendet, um die aktuelle Frame-Nummer vom Host-Controller abzurufen, die vom Hub-Treiber zum Planen isochroner Übertragungen verwendet wird.

UCXROOTHUB: Stammhubobjekt

Ruft den Status der Stammports des Hostcontrollers ab und steuert den Status. Wird vom Host-Controller-Treiber erstellt, normalerweise innerhalb des Rückrufs EvtDriverDeviceAdd, indem die Methode UcxRootHubCreate aufgerufen wird, nachdem das Host-Controller-Objekt erstellt wurde. Pro Hostcontrollerinstanz sollte nur ein Stammhubobjekt 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 Root-Hubs zurück.

EVT_UCX_ROOTHUB_GET_20PORT_INFO
Gibt Informationen zu den USB 2.0- oder USB 3.0-Ports (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) des Root-Hubs zurück.

Nachdem das Stammhubobjekt erstellt und initialisiert wurde, interagiert der Hubtreiber mit den Stammhubports, indem Unterbrechungs- und Steuerungsübertragungen gesendet werden. UCX unterstützt diese Übertragungen durch Aufrufen dieser Rückruffunktionen, die vom Hostcontrollertreiber implementiert werden.

EVT_UCX_ROOTHUB_CONTROL_URB
Verarbeitet Funktionssteuerungsanforderungen durch den USB-Hub.

EVT_UCX_ROOTHUB_INTERRUPT_TX
Bearbeitet Anfragen nach 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 Host-Controller-Treiber erstellt, normalerweise innerhalb des Rückruf EVT_UCX_CONTROLLER_USBDEVICE_ADD indem die Methode UcxUsbDeviceCreate aufgerufen wird.

Wenn das Objekt erstellt wird, registriert der Hostcontrollertreiber seine Implementierung der Rückruffunktionen beim UcxUsbDeviceCreate aufgerufen wird.

Diese Rückruffunktionen dienen dazu, den Controller und Treiber über den aktuellen Status von USB-Geräten zu informieren.

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

EVT_UCX_USBDEVICE_DISABLE
Gibt Controllerressourcen frei, die mit dem Gerät und seinem Standardendpunkt verknüpft 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 versetzen.

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 Controller-Benachrichtigung, 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 zum Gerät.

EVT_UCX_USBDEVICE_HUB_INFO
Eine Benachrichtigung über Hub-Eigenschaften, wenn der UCXUSBDEVICE-Handle für ein Hub-Gerät ist.

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 das Aufwecken signalisiert hat, wird vom Treiber erwartet, dass er 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: Endpunkt-Objekt

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 außerdem ein Framework-Warteschlangenobjekt für jeden Endpunkt und übergibt die WDFQUEUE für diese Warteschlange an UCX, indem er UcxEndpointSetWdfIoQueue aufruft. Nachdem der Endpunkt erstellt wurde, wird die Lebensdauer des Objekts und der zugehörigen Warteschlangen von UCX verwaltet, und der Treiber darf diese Objekte nicht selbst löschen.

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

EVT_UCX_ENDPOINT_ABORT
Brechen Sie die mit dem Endpunkt verknüpfte Warteschlange ab.

EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS
Benachrichtigt den Controller-Treiber, dass er abgebrochene Übertragungen am Endpunkt abschließen kann.

EVT_UCX_ENDPOINT_PURGE
Schließen Sie alle ausstehenden E/A-Anfragen am Endpunkt ab.

EVT_UCX_ENDPOINT_START
Startet die mit dem Endpunkt verknüpfte Warteschlange.

EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD
Erstellt statische Streams.

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

Wenn der Host-Controller-Treiber 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 Rohren an das Gerät über einen einzelnen Endpunkt dar. Der Host-Controller-Treiber erstellt Stream-Objekte im Rückruf EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD, indem er UcxStaticStreamsCreate aufruft.

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

Nachdem das Objekt erstellt wurde, erstellt der Treiber ein Framework-Warteschlangenobjekt für jeden Datenstrom und sendet das WDFQUEUE-Handle an UCX durch Aufrufen von UcxStaticStreamsSetStreamInfo.

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 der Controllerressourcen für alle Streams für einen Endpunkt.

EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE
Aktiviert die Controller-Hardware 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.