Share via

Oggetti UCX e handle usati da un driver del controller host

  • Articolo

UCX estende la funzionalità dell'oggetto WDF per definire i propri oggetti UCX specifici per USB. UCX usa questi oggetti per accodare le richieste a qualsiasi driver del controller host sottostante.

Riepilogo

  • Gli oggetti UCX vengono usati dal driver del controller host per gestire le operazioni correlate al controller, al relativo hub radice e a tutti gli endpoint.
  • Gli oggetti UCX vengono creati dal driver del controller host e la durata di ogni oggetto viene gestita da UCX.

API importanti

UCX estende la funzionalità dell'oggetto WDF per definire i propri oggetti UCX specifici per USB. UCX usa questi oggetti per accodare le richieste a qualsiasi driver del controller host sottostante.

Per altri dettagli sugli oggetti WDF, vedere Introduzione agli oggetti Framework.

UCXCONTROLLER: oggetto controller host

Rappresenta il controller host creato dal driver del controller host. Il driver deve creare un solo oggetto controller host per ogni istanza del controller host. In genere creato all'interno del callback EvtDriverDeviceAdd chiamando il metodo UcxControllerCreate.

Quando il driver del controller host crea l'oggetto, il driver registra l'implementazione delle funzioni di callback richiamate da UCX. Il driver deve inoltre identificare il tipo di bus su cui è connesso il controller host, ad esempio ACPI o PCI. Il driver fornisce anche informazioni sul dispositivo del controller host usando la struttura UCX_CONTROLLER_CONFIG passata alla chiamata UcxControllerCreate.

Per gestire le richieste di I/O, il driver del controller host deve registrare un'interfaccia del dispositivo GUID_DEVINTERFACE_USB_HOST_CONTROLLER. Il driver non è necessario per implementare gli IOCTL definiti in questa interfaccia. Al contrario, il client UCX passa le richieste IOCTL ricevute su questa interfaccia a UCX chiamando UcxIoDeviceControl.

Ecco le funzioni di callback associate all'oggetto controller host, richiamate da UCX. Queste funzioni devono essere implementate dal driver del controller host.

*
EVT_UCX_CONTROLLER_USBDEVICE_ADD Chiamato quando il driver hub ha determinato, tramite l'interazione con l'hub radice e/o gli hub esterni, che un nuovo dispositivo è presente nel bus.

*
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY Chiamata da UCX per raccogliere informazioni sulle varie funzionalità supportate dai controller host USB.

*EVT_UCX_CONTROLLER_RE edizione Standard T
Chiamato da UCX per reimpostare l'hardware del controller, possibilmente in risposta a un errore rilevato.

*
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER Usato per recuperare il numero di frame corrente dal controller host, usato dal driver hub per la pianificazione dei trasferimenti isocroni.

UCXROOTHUB: oggetto hub radice

Ottiene e controlla lo stato delle porte radice del controller host. Creato dal driver del controller host in genere all'interno del callback EvtDriverDeviceAdd chiamando il metodo UcxRootHubCreate dopo la creazione dell'oggetto controller host. Deve essere presente un solo oggetto hub radice per ogni istanza del controller host. Nella chiamata UcxRootHubCreate il driver registra le implementazioni di callback.


EVT_UCX_ROOTHUB_GET_INFO Restituisce il numero di porte USB 2.0 e USB 3.0 dell'hub radice.


EVT_UCX_ROOTHUB_GET_20PORT_INFO Restituire informazioni sulle porte USB 2.0 o USB 3.0 (*EVT_UCX_ROOTHUB_GET_30PORT_INFO) dell'hub radice.

Dopo aver creato e inizializzato l'oggetto hub radice, il driver hub interagisce con le porte dell'hub radice inviando trasferimenti di interrupt e controllo. UCX assiste con questi trasferimenti richiamando queste funzioni di callback implementate dal driver del controller host.


EVT_UCX_ROOTHUB_CONTROL_URB gestisce le richieste di controllo delle funzionalità dall'hub USB.


EVT_UCX_ROOTHUB_INTERRUPT_TX gestisce la richiesta di informazioni sulle porte modificate.

Per altre informazioni, vedere Funzioni di callback dell'hub radice di un driver del controller host.

UCXUSBDEVICE: oggetto dispositivo USB

Rappresenta un dispositivo USB fisico connesso al bus. Creato dal driver del controller host in genere all'interno del callback EVT_UCX_CONTROLLER_USBDEVICE_ADD chiamando il metodo UcxUsbDeviceCreate.

Quando l'oggetto viene creato, il driver del controller host registra l'implementazione delle funzioni di callback con la chiamata UcxUsbDeviceCreate.

Queste funzioni di callback sono progettate per mantenere il controller e il driver informati sullo stato corrente dei dispositivi USB.


EVT_UCX_USBDEVICE_ENABLE Prepara il controller per l'esecuzione dei trasferimenti all'endpoint predefinito del dispositivo.


EVT_UCX_USBDEVICE_DISABLE Rilascia le risorse controller associate al dispositivo e al relativo endpoint predefinito.


EVT_UCX_USBDEVICE_ADDRESS Programmi un indirizzo nel controller e invia un trasferimento edizione Standard T_ADDRESS al dispositivo per portarlo allo stato indirizzato.


EVT_UCX_USBDEVICE_ENDPOINTS_CONFIGURE Programmi endpoint non predefiniti nel controller e/o rilascia altri endpoint non predefiniti.

EVT_UCX_USBDEVICE_RE edizione Standard T
A notifica che un dispositivo è stato reimpostato, nel qual caso il driver esegue qualsiasi azione necessaria per sincronizzare il controller con il dispositivo USB.


EVT_UCX_USBDEVICE_UPDATE Notifica al controller di vari bit di informazioni correlate al dispositivo.


EVT_UCX_USBDEVICE_HUB_INFO Una notifica sulle proprietà dell'hub, se l'handle UCXUSBDEVICE riguarda un dispositivo hub.


EVT_UCX_USBDEVICE_ENDPOINT_ADD notifica al driver di creare un endpoint per il dispositivo. EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD per l'endpoint predefinito.

Quando un'interfaccia su un dispositivo USB 3.0 sospeso ha segnalato la riattivazione, il driver dovrebbe chiamare UcxUsbDeviceRemoteWakeNotification per notificare a UCX.

Dopo aver creato l'oggetto, la durata dell'oggetto viene gestita da UCX e il driver non deve eliminare l'oggetto.

UCXENDPOINT: oggetto Endpoint

Rappresenta un endpoint in un oggetto dispositivo USB. Gli oggetti endpoint vengono creati dal controller host durante un EVT_UCX_USBDEVICE_DEFAULT_ENDPOINT_ADD o un callback EVT_UCX_USBDEVICE_ENDPOINT_ADD. Quando viene creato un oggetto endpoint, il driver registra le funzioni di callback.

Il driver crea anche un oggetto coda del framework per ogni endpoint e passa WDFQUEUE per tale coda a UCX chiamando UcxEndpointSetWdfIoQueue. Dopo aver creato l'endpoint, la durata dell'oggetto e le code associate viene gestita da UCX e il driver non deve eliminare questi oggetti.

L'oggetto endpoint implementa diverse funzioni di callback che consentono al driver di assistere UCX con le operazioni correlate all'endpoint.


EVT_UCX_ENDPOINT_ABORT interrompere la coda associata all'endpoint.


EVT_UCX_ENDPOINT_OK_TO_CANCEL_TRANSFERS Notificare al driver del controller che può completare i trasferimenti annullati nell'endpoint.


EVT_UCX_ENDPOINT_PURGE Completare tutte le richieste di I/O in sospeso nell'endpoint.


EVT_UCX_ENDPOINT_START Avviare la coda associata all'endpoint.


EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD Creare flussi statici.

EVT_UCX_ENDPOINT_RE edizione Standard Notifica
al driver di reimpostare la programmazione del controller dell'endpoint.

Quando il driver del controller host riceve un errore di risposta ping USB 3.0 su un endpoint, il driver deve chiamare UcxEndpointNoPingResponseError. La chiamata genera l'oggetto dispositivo USB che riceve EVT_UCX_USBDEVICE_UPDATE. Per altre informazioni, vedere Configurazione degli endpoint USB in un driver del controller host.

UCXSTREAMS: oggetto Stream

Rappresenta una serie di pipe al dispositivo in un singolo endpoint. Il driver del controller host crea oggetti flusso nel callback EVT_UCX_ENDPOINT_STATIC_STREAMS_ADD chiamando UcxStatic Flussi Create.

Durante la chiamata UcxStatic Flussi Create, il driver del controller host registra le funzioni di callback. Per un oggetto endpoint specifico, il driver può determinare se ha creato un oggetto streams e restituire l'handle UCXSTREAMS chiamando UcxEndpointGetStatic Flussi Referenced.

Dopo aver creato l'oggetto , il driver crea un oggetto coda del framework per ogni flusso e invia l'handle WDFQUEUE a UCX chiamando UcxStatic Flussi SetStreamInfo.

L'oggetto flusso fornisce diverse funzioni di callback per il controller host per assistere UCX nella gestione dei flussi statici.

EVT_UCX_ENDPOINT_STATIC_STREAMS_DISABLE Rilasciare
le risorse del controller per tutti i flussi per un endpoint.

EVT_UCX_ENDPOINT_STATIC_STREAMS_ENABLE Abilitare l'hardware
del controller di tutti i flussi per questo endpoint.

La durata dell'oggetto e delle code associate viene gestita da UCX e il driver non deve eliminare gli oggetti.