Sdílet prostřednictvím

Napište ovladač klienta řadiče funkcí

Tento článek popisuje různé úlohy, které klientský ovladač kontroleru funkcí provádí při interakci s rozšířením řadiče funkce USB (UFX).

Důležitá rozhraní API

Popisuje různé úlohy, které klientský ovladač kontroleru funkcí provádí při interakci s rozšířením řadiče funkce USB (UFX). UFX a klientský ovladač vzájemně komunikují pomocí metod exportu a funkcí zpětného volání událostí. Metody exportu (pojmenované UfxDeviceXxx nebo UfxEndpointXxx) exportuje UFX a vyvolá ovladač klienta. Funkce zpětného volání (pojmenované EVT_UFX_Xxx)jsou implementovány v klientském ovladači a vyvolány UFX.

UFX volá všechny funkce zpětného volání klientského ovladače asynchronně a jedno zpětné volání v čase na objekt. Například objekt zařízení USB a tři koncové objekty. Současně se můžou volat maximálně čtyři funkce zpětného volání (jedna pro zařízení a jedna pro každý koncový bod). Pro každou metodu zpětného volání UFX čeká, až ovladač klienta zavolá metodu UfxDeviceEventComplete a tím indikuje, že ovladač dokončil požadavek. Jedinou jinou metodou exportu, kterou UFX naslouchá při čekání na tyto exporty, je UfxDeviceNotifyHardwareFailure. Mnoho funkcí zpětného volání klienta je volitelné. Požadované funkce jsou následující:

Inicializace

  1. Klientský ovladač kontroleru funkcí spustí proces inicializace, když Windows Driver Foundation (WDF) vyvolá implementaci klientského ovladače zpětného volání EVT_WDF_DRIVER_DEVICE_ADD. V této implementaci se očekává, že klientský ovladač zavolá UfxFdoInit a pak vytvoří objekt zařízení voláním WdfDeviceCreate.
  2. Klientský ovladač volá UfxDeviceCreate ke vytvoření objektu zařízení USB a k načtení popisovače UFXDEVICE.
  3. Klientský ovladač volá UfxDeviceNotifyHardwareReady, aby UFX naznačil, že může teď vyvolat funkce zpětného volání klientského ovladače.
  4. UFX provádí inicializační úlohy, jako jsou:
    • UFX volá EVT_UFX_DEVICE_DEFAULT_ENDPOINT_ADD implementaci klientského ovladače k vytvoření výchozího koncového bodu.
    • UFX vytvoří potomkové objekty fyzického zařízení (PDO) pro rozhraní podporovaná zařízením.
    • UFX čeká na aktivaci ovladače třídy zařízení, když odešle požadavek IOCTL_INTERNAL_USBFN_ACTIVATE_USB_BUS. Také čeká, až klientský ovladač zavolá UfxDeviceNotifyAttach, který označuje, že zařízení bylo připojeno.

Oznámení o ovladači třídy

Aby byl informován o paketech nastavení a stavu sběrnice, třídní ovladač by měl odeslat žádosti IOCTL_INTERNAL_USBFN_ACTIVATE_USB_BUS. UFX tyto požadavky zařadí do front oznámení specifických pro ovladače třídy. Při přijetí oznámení o události sběrnice z klientského ovladače se UFX zobrazí z každé příslušné fronty a dokončí požadavek. Aby ovladače třídy nepřišly o oznámení, UFX udržuje frontu oznámení s pevnou velikostí pro ovladač třídy.

Události připojení a odpojení zařízení

UFX předpokládá, že zařízení je odpojeno, dokud klientský ovladač funkčního řadiče nevolá UfxDeviceNotifyAttach.

Po volání nastaví UFX stav zařízení na Powered, jak je definováno ve specifikaci USB. Pokud chcete klientovi oznámit změnu stavu, UFX vyvolá EVT_UFX_DEVICE_USB_STATE_CHANGE implementaci klientského ovladače.

UFX upozorňuje řidiče nabíječky (Cad.sys), aby pomohl s nabíjením zařízení. UFX také upozorní ovladače třídy dokončením IOCTL_INTERNAL_USBFN_BUS_EVENT_NOTIFICATION požadavků odeslaných dříve ovladači třídy.

Klientský ovladač musí při odpojení sběrnice volat UfxDeviceNotifyDetach. Klient musí volat odpojení pouze jednou po každém volání UfxDeviceNotifyAttach. Po provedení volání UfxDeviceNotifyDetach UFX zavolá EVT_UFX_DEVICE_HOST_DISCONNECT, pokud se nejedná o změnu rozhraní. UFX pak pokračuje se všemi úlohami čištění, jako je vymazání všech front koncových bodů a spuštění výchozí fronty koncových bodů. UFX volá EVT_UFX_DEVICE_USB_STATE_CHANGE a upozorňuje ovladače třídy dokončením IOCTL_INTERNAL_USBFN_BUS_EVENT_NOTIFICATION žádostí.

Selhání hardwaru

Pokud dojde k chybě hardwaru, očekává se, že klientský ovladač zavolá UfxDeviceNotifyHardwareFailure. V reakci na to UFX roztrhne zásobník zařízení a může se pokusit z této situace zotavit voláním klientského ovladače EVT_UFX_DEVICE_CONTROLLER_RESET. Klient by měl obnovit kontroler do počátečního stavu. Pokud dojde k jinému selhání hardwaru, měl by klient znovu volat UfxDeviceNotifyHardwareFailure. Při druhém volání zaznamená UFX svůj stav a kontrolu chyb.

Detekce portů

Zjišťování portů provádí UFX. Volá zpětnou volací funkci EVT_UFX_DEVICE_PORT_DETECT v klientském ovladači řadiče, aby určila typ portu, ke kterému je zařízení připojeno. Klient odpoví voláním UfxDevicePortDetectComplete nebo UfxDevicePortDetectCompleteEx s jedním z typů portů definovaných v USBFN_PORT_TYPE.

Pokud klient nemůže určit typ portu, měl by klient hlásit UsbfnUnknownPort. Pokud je port neznámý nebo podřízený port, UFX zavolá funkci EVT_UFX_DEVICE_HOST_CONNECT klientského ovladače. UFX chvíli naslouchá autobusu. Pokud je port neznámý, ale dochází k přenosu, například k přenosu instalačního paketu, UFX bude předpokládat UsbfnStandardDownstreamPort. V opačném případě UFX přiřadí port UsbfnInvalidDedicatedChargingPort. Po určení typu portu upozorní UFX Cad.sys a zavolá funkci EVT_UFX_DEVICE_PORT_CHANGE klientského ovladače. Ve funkci očekává, že klientský ovladač změní stav hardwaru tak, aby odpovídal typu portu UFX.

Vytvoření koncového bodu

UFX vytvoří výchozí koncový bod (koncový bod 0) zavoláním EVT_UFX_DEVICE_DEFAULT_ENDPOINT_ADD klientského ovladače, aby mohl zpracovat instalační pakety odeslané hostitelem. UFX vytváří další koncové body voláním EVT_UFX_DEVICE_ENDPOINT_ADD. UFX vytvoří koncové body pouze po volání klientského ovladače UfxDeviceNotifyHardwareReady. V těchto funkcích zpětného volání se očekává, že klientský ovladač zavolá UfxEndpointCreate do objektu koncového bodu a získá jeho popisovač UFXENDPOINT. UFX nastaví nadřazený objekt ovladače třídy spojený s rozhraním, ke kterému koncový bod patří. Nadřazeným objektem výchozího koncového bodu je zařízení USB. Koncový bod obsahuje dva objekty fronty architektury: frontu přenosu a frontu příkazů, z nichž obě mohou být přístupné pouze v případě, že je zařízení v nakonfigurovaném stavu (s výjimkou koncového bodu 0, ke kterému je možné získat přístup po volání UFX EVT_UFX_DEVICE_HOST_CONNECT).

Výčet zařízení

Klientský ovladač by neměl povolit připojení k hostiteli, dokud UFX nezavolá ovladače EVT_UFX_DEVICE_HOST_CONNECT. Výčet zařízení začíná, když ovladač klienta volá UfxDeviceNotifyReset. Ve stavu Výchozí zpracovává UFX standardní instalační pakety.

Resetování

UFX vyprázdní všechny fronty koncových bodů a odešle klientovi požadavek IOCTL_INTERNAL_USBFN_DESCRIPTOR_UPDATE, aby aktualizoval wMaxPacketSize koncového bodu 0. UFX spustí frontu výchozího koncového bodu a nastaví stav na Výchozí.

Výchozí

UFX volá funkci EVT_UFX_DEVICE_USB_STATE_CHANGE klientského ovladače. Také upozorňuje ovladače tříd na daný stav. Jakmile UFX přijme standardní instalační paket SET_ADDRESS, UFX nastaví stav na Adresovaný.

Adresováno

UFX volá funkci EVT_UFX_DEVICE_ADDRESSED klientského ovladače, která určuje klientovi, jakou adresu má použít. – Pokud je adresa 0, UFX nastaví stav zpět na Výchozí a zavolá EVT_UFX_DEVICE_USB_STATE_CHANGE a upozorní ovladače tříd. Při přijetí standardního konfiguračního paketu SET_CONFIGURATION nastaví UFX stav na Nakonfigurovaný.

Nastavený

Pokud je vybraná konfigurace 0, UFX vyprázdní koncové body rozhraní a nastaví stav na Adresováno. UFX odešle požadavek IOCTL_INTERNAL_USBFN_DESCRIPTOR_UPDATE na aktualizaci wMaxPacketSize koncových bodů rozhraní klientskému ovladači. UFX zajišťuje, že všechny fronty koncových bodů rozhraní dokončily mazání, a poté spouští fronty koncových bodů rozhraní. Pokud typ portu není UsbfnStandardDownstreamPort nebo UsbfnChargingDownstreamPort, UFX změňte typ portu na UsbfnStandardDownstreamPort a informuje Cad.sys; klientský ovladač voláním EVT_UFX_DEVICE_PORT_CHANGE a EVT_UFX_DEVICE_USB_STATE_CHANGE k aktualizaci stavu; ovladače třídy konfigurovaného stavu.

Standardní přenosy ovládacích prvků

UFX může zpracovávat přenosy ovládacích prvků na výchozím koncovém bodu kdykoli po volání EVT_UFX_DEVICE_DEFAULT_ENDPOINT_ADD, ve kterém klientský ovladač vytvoří výchozí koncový bod pomocí. Všechny přenosy ovládacích prvků začínají 8 bajtovým instalačním paketem. Chcete-li odeslat instalační paket hostiteli, ovladač klienta by měl volat UfxEndpointNotifySetup. Standardní řídicí přenosy jsou dokončovány UFX. Pokud jsou k přenosu ovládacího prvku přidružená data, funkce UFX bude podle potřeby číst a zapisovat do výchozího koncového bodu ovládacího prvku.

Nestandardní přenosy ovládacích prvků

Pokud UFX nemůže zpracovat řízení přenosu, přepošle přenos příslušnému ovladači třídy dokončením požadavku IOCTL_INTERNAL_USBFN_BUS_EVENT_NOTIFICATION. Přenosy ovládacích prvků můžou nastat na jakémkoli koncovém bodu, který je definovaný jako koncový bod ovládacího prvku v popisovači koncového bodu. Přenosy řízení u koncových bodů kromě výchozího koncového bodu ovládacího prvku jsou vždy nestandardní přenosy řízení. Pokud je koncový bod ovládacího prvku výchozí, UFX upozorní ovladače tříd na pakety nastavení označené jako požadavky pro příslušné třídy ovladačů. Pokud koncový bod ovládacího prvku patří k rozhraní, UFX upozorní třídní ovladač přidružený k tomuto rozhraní. V případě potřeby se očekává, že ovladače třídy budou číst a zapisovat do řídicího koncového bodu.

Přenosy dat

Přenosy dat jsou inicializovány ovladači třídy odesláním žádostí IOCTL_INTERNAL_USBFN_TRANSFER_IN, IOCTL_INTERNAL_USBFN_TRANSFER_IN_APPEND_ZERO_PKTnebo IOCTL_INTERNAL_USBFN_TRANSFER_OUT. Po ověření každého z těchto požadavků ho UFX předá do příslušné fronty koncového bodu, kterou bude zpracovávat ovladač klienta. Očekává se, že klientský ovladač provede další ověření. Klientský ovladač přijímá požadavky na přenos ve frontách koncových bodů. Klientský ovladač může načíst tolik požadavků z této fronty, kolik potřebuje k maximalizaci využití sběrnice. Klientský ovladač by měl dokončit úspěšné požadavky stavem STATUS_SUCCESS. Ovladač by se měl pokusit co nejlépe zrušit požadavky a dokončit zrušené žádosti se stavem STATUS_CANCELLED, pokud byly zrušeny. Pokud jsou předány neplatné parametry, ovladač klienta dokončí požadavek s STATUS_INVALID_PARAMETER.

Přenosy ovládacích prvků

Přenosy řízení začínají 8 bajtovým instalačním paketem. Chcete-li odeslat instalační paket hostiteli, ovladač klienta by měl volat UfxEndpointNotifySetup. UFX upozorní ovladače tříd na nestandardní přenosy řízení splněním žádostí o oznámení. Klienti i UFX používají IOCTL_INTERNAL_USBFN_TRANSFER_IN, IOCTL_INTERNAL_USBFN_TRANSFER_IN_APPEND_ZERO_PKT, nebo IOCTL_INTERNAL_USBFN_TRANSFER_OUT ke čtení a zápisu do výchozího řídicího koncového bodu. Rozhraní však může definovat jiné koncové body ovládacích prvků, které mohou používat pouze odpovídající ovladač třídy. Koncové body řízení je možné zastavit v reakci na instalační paket. Ovladače třídy odesílají požadavek IOCTL_INTERNAL_USBFN_SET_PIPE_STATE, aby zastavily koncový bod. Po odeslání zastavení se očekává, že hardware nebo klientský ovladač okamžitě znovu zahájí provoz na daném koncovém bodu. Řídicí koncové body můžou také odesílat a přijímat pakety nulové délky (ZLP) bez jakýchkoli předchozích dat. Klientský ovladač a UFX to mohou provést pomocí IOCTL_INTERNAL_USBFN_CONTROL_STATUS_HANDSHAKE_IN a IOCTL_INTERNAL_USBFN_CONTROL_STATUS_HANDSHAKE_OUT.

Hromadné přenosy a přerušované přenosy

Hromadné přenosy zaručují doručení dat a slouží k odesílání velkých objemů dat. Přenosy lze odesílat na hromadný koncový bod pomocí příkazů IOCTL_INTERNAL_USBFN_TRANSFER_IN, IOCTL_INTERNAL_USBFN_TRANSFER_IN_APPEND_ZERO_PKT, nebo IOCTL_INTERNAL_USBFN_TRANSFER_OUT. Hromadné koncové body je možné zastavit podobně jako u koncových bodů řízení pomocí IOCTL_INTERNAL_USBFN_SET_PIPE_STATE. Očekává se, že klientský ovladač odešle paket STALL v reakci na všechny požadavky hostitele a bude uchovávat požadavky IOCTL. Na rozdíl od kontrolních koncových bodů zůstává pozastavený hromadný koncový bod pozastavený, dokud není stav pozastavení explicitně odstraněn.

Přerušovací přenosy jsou podobné hromadným přenosům, ale mají zaručenou latenci. Přenosy přerušení mají stejné rozhraní jako hromadné přenosy, ale nemají možnosti streamování.

Izochronové přenosy

Klientský ovladač v této verzi nepodporuje izochronní přenosy.

Řízení spotřeby

Klientský ovladač vlastní všechny aspekty řízení spotřeby. Vzhledem k tomu, že funkce zpětného volání jsou asynchronní, očekává se, že klientský ovladač by se měl vrátit do příslušného stavu napájení a splní žádost před zavoláním příslušné funkce pro dokončení exportu události, například UfxDeviceEventComplete.

UFX je v pracovním stavu, pokud je stav zařízení (definovaný v USBFN_DEVICE_STATE) UsbfnDeviceStateSuspended a UsbfnDeviceStateAttacheda nenahlásil typ portu. Alternativně UFX oznámil typ portu (definovaný v USBFN_PORT_TYPE) UsbfnStandardDownstreamPort nebo UsbfnChargingDownstreamPort.

UFX přechází do pracovního stavu a zpět voláním implementací EVT_UFX_DEVICE_USB_STATE_CHANGE nebo EVT_UFX_DEVICE_PORT_CHANGE. Přechod do nebo z pracovního stavu je dokončen, když ovladač klienta volá UfxDeviceEventComplete.

V pracovním stavu může UFX volat jakékoli zpětné volání. I když není v pracovním stavu, UFX volá pouze EVT_UFX_DEVICE_USB_STATE_CHANGE, aby vstoupil do pracovního stavu; EVT_UFX_DEVICE_REMOTE_WAKEUP_SIGNAL, aby vyvolal vzdálené probuzení během pozastavení (pokud je podporováno).

Pozastavení zařízení

K pozastavení zařízení dochází, když na sběrnici není žádný provoz po dobu 3 milisekund. V tomto případě musí klientský ovladač informovat UFX, když zjistí pozastavení a obnovení voláním UfxDeviceNotifySuspend a UfxDeviceNotifyResume. Při přijetí tato volání volá UFX EVT_UFX_DEVICE_USB_STATE_CHANGE a upozorní ovladače tříd dokončením požadavků IOCTL_INTERNAL_USBFN_BUS_EVENT_NOTIFICATION. Pokud je vzdálené probuzení podporováno zařízením a povoleno hostitelem, může UFX volat EVT_UFX_DEVICE_USB_STATE_CHANGE při pozastavení provozu za účelem vyslání signálu vzdáleného probuzení.

  • Last updated on