Napisz sterownik kontrolera portu USB Type-C

Należy napisać sterownik kontrolera portu USB Type-C, jeśli sprzęt USB Type-C implementuje fizyczną warstwę USB Type-C lub Power Delivery (PD), ale nie implementuje maszyn stanowych wymaganych dla Power Delivery.

W Windows 10, wersja 1703, architektura USB Type-C została ulepszona dla obsługi projektów sprzętowych wdrażających warstwę fizyczną USB Type-C lub Power Delivery (PD), ale nieposiadających odpowiedniego silnika polityki PD ani implementacji warstwy protokołu. W przypadku tych projektów system Windows 10 wersja 1703 oferuje programowy silnik zasad PD i zarządzanie zasadami urządzeń za pomocą nowego rozszerzenia klasy o nazwie "Menedżer Złączy USB Type-C — Rozszerzenie Klasy Kontrolera Portu" (UcmTcpciCx). Sterownik klienta napisany przez IHV lub OEM/ODM komunikuje się z UcmTcpciCx w celu dostarczenia informacji o wymaganych zdarzeniach sprzętowych potrzebnych do prawidłowego funkcjonowania silnika zasad PD i menedżera zasad urządzeń w UcmTcpciCx. Ta komunikacja jest włączona za pośrednictwem zestawu interfejsów programowania opisanych w tym artykule i w sekcji referencyjnej.

Rozszerzenie dla klasy UcmTcpciCx samo w sobie jest sterownikiem klienckim UcmCx. Decyzje dotyczące zasad dotyczących kontraktów energetycznych i ról danych są podejmowane w UcmCx i przekazywane do UcmTcpciCx. UcmTcpciCx implementuje te zasady i zarządza maszynami stanu Type-C i PD przy użyciu interfejsu kontrolera portu dostarczonego przez sterownik klienta UcmTcpciCx.

Podsumowanie

• Usługi udostępniane przez rozszerzenie klasy UcmTcpci
• Oczekiwane zachowanie sterownika klienta

Oficjalne specyfikacje

• Specyfikacja interfejsu kontrolera portów USB Type-C
• Specyfikacje usb 3.1 i USB Type-C
• Dostarczanie zasilania USB

Ważne interfejsy API

Dokumentacja rozszerzeń klasy sterowników interfejsu kontrolera portów USB Type-C

Szablon sterownika klienta UcmTcpciCx

Szablon sterownika klienta UcmTcpciCx

Zanim rozpoczniesz

• Określ typ sterownika, który ma być zapisywany w zależności od tego, czy sprzęt lub oprogramowanie układowe implementuje maszynę stanu PD. Aby uzyskać więcej informacji, zobacz Tworzenie sterowników systemu Windows dla łączników Type-C USB.

• Zainstaluj system Windows 10 dla wersji klasycznych (Home, Pro, Enterprise i Education) na komputerze docelowym lub Windows 10 Mobile za pomocą łącznika Type-C USB.

• Zainstaluj najnowszy zestaw sterowników systemu Windows (WDK) na komputerze dewelopera. Zestaw zawiera wymagane pliki nagłówkowe i biblioteki do pisania sterownika klienta, w szczególności potrzebujesz:

  • Biblioteka wycinków (UcmTcpciCxStub.lib). Biblioteka tłumaczy wywołania wykonywane przez sterownik klienta i przekazuje je do rozszerzenia klasy.
  • Plik nagłówka UcmTcpciCx.h.

  Sterownik klienta działa w trybie jądra i wiąże się z biblioteką KMDF 1.15.

  

• Zdecyduj, czy sterownik klienta obsługuje alerty.

• Kontroler portów nie jest wymagany do zapewnienia zgodności z protokołem TCPCI. Interfejs przechwytuje możliwości dowolnego kontrolera portów Type-C. Pisanie sterownika klienta UcmTcpciCx dla sprzętu, który nie jest zgodny ze standardem TCPCI, obejmuje mapowanie znaczenia rejestrów i poleceń w specyfikacji TCPCI na sprzęt.

• Większość kontrolerów TCPCI jest połączona przez I²C. Sterownik klienta używa zasobu połączeniowego szeregowej magistrali peryferyjnej (SPB) i linii przerwania do komunikowania się ze sprzętem. Sterownik używa interfejsu programowania SPB Framework Extension (SpbCx). Zapoznaj się z programem SpbCx, czytając następujące artykuły:

  • [Przewodnik projektowania sterowników prostej magistrali peryferyjnej (SPB) ]
  • [Dokumentacja programowania sterowników SPB]

• Zapoznaj się z programem Windows Driver Foundation (WDF). Zalecane czytanie: Opracowywanie sterowników z Windows Driver Foundation, napisane przez Penny Orwick i Guy Smith.

Zachowanie rozszerzenia klasy UcmTcpci

• W ramach wykonywania maszyny stanu UcmTcpciCx wysyła żądania IOCTL do kontrolera portu. Na przykład w komunikatach PD wysyła żądanie IOCTL_UCMTCPCI_PORT_CONTROLLER_SET_TRANSMIT_BUFFER, aby ustawić bufor transmisji. To żądanie (TRANSMIT_BUFFER) jest przekazywane do sterownika klienta. Następnie sterownik konfiguruje bufor nadawczy ze szczegółami dostarczonymi przez rozszerzenie klasy.

• UcmTcpciCx implementuje zasady dotyczące kontraktów zasilania, ról danych itd.

Oczekiwane zachowanie sterownika klienta

Sterownik klienta dla interfejsu UcmTcpciCx powinien:

• Być właścicielem polityki energetycznej. UcmTcpciCx nie uczestniczy w zarządzaniu energią kontrolera portu.

• Przetłumacz żądania otrzymane z UcmTcpciCx na sprzętowe polecenia odczytu lub zapisu. Polecenia muszą być asynchroniczne, ponieważ program DPM nie może zablokować oczekiwania na ukończenie transferu sprzętu.

• Podaj obiekt kolejki frameworku, który zawiera obiekty żądań frameworku. Dla każdego żądania, które rozszerzenie klasy UcmTcpci chce wysłać do sterownika klienta, rozszerzenie dodaje obiekt żądania w obiekcie kolejki sterownika. Po zakończeniu przetwarzania żądania sterownik wywołuje element WdfRequestComplete. Jest to odpowiedzialność kierowcy klienta za wykonywanie żądań w odpowiednim czasie.

• Odnajdywanie i zgłaszanie możliwości kontrolera portów. Te możliwości obejmują informacje, takie jak role, w których kontroler portów może działać (na przykład tylko źródło, tylko ujście, DRP). Istnieją jednak inne możliwości łącznika (patrz Uwaga dotycząca magazynu możliwości) i całego systemu, że program DPM musi wiedzieć, aby prawidłowo zaimplementować zasady Type-C USB i PD. Na przykład program DPM musi znać możliwości źródłowe systemu/łącznika, aby anonsować go do partnera portów.

  Magazyn możliwości

  Oprócz możliwości związanych z sterownikami klienta dodatkowe informacje pochodzą z lokalizacji globalnej systemu nazywanej magazynem możliwości. Ten globalny magazyn możliwości systemu jest przechowywany w ACPI. Jest to statyczny opis możliwości systemu i każdego z jego łączników USB Type-C używanych przez program DPM do określania zasad do wdrożenia.

  Oddzielając opis możliwości systemu od sterownika klienta dla kontrolerów portów, projekt umożliwia użycie sterownika w różnych systemach o różnych możliwościach. UcmCx, a nie UcmTcpciCx, interfejsuje z magazynem możliwości. UcmTcpciCx (lub jego sterownik klienta) nie wchodzi w interakcję z magazynem możliwości.

  Wszędzie tam, gdzie ma to zastosowanie, informacje z magazynu możliwości zastępują informacje pochodzące bezpośrednio ze sterownika klienta kontrolera portu. Na przykład kontroler portu może wykonać operację tylko ujścia, a sterownik klienta zgłasza te informacje. Jednak reszta systemu może nie być poprawnie skonfigurowana do działania wyłącznie jako zlew. W takim przypadku producent systemu może zgłosić, że łączniki są w stanie wykonać operację w trybie tylko Źródła w Magazynie Zdolności. Ustawienie w Sklepie Funkcji ma pierwszeństwo przed informacjami zgłoszonymi przez sterownik.

• Powiadom użytkownika UcmTcpciCx o wszystkich odpowiednich danych związanych z alertami.

• Opcjonalny. Wykonaj dodatkowe przetwarzanie po wprowadzeniu/zakończeniu trybu alternatywnego. Sterownik jest informowany o tych stanach przez rozszerzenie klasy za pośrednictwem żądań IOCTL.

Zarejestruj sterownik klienta w UcmTcpciCx

Przykładowe odniesienie: zobacz EvtPrepareHardware w Device.cpp.

1. W implementacji EVT_WDF_DRIVER_DEVICE_ADD wywołaj metodę UcmTcpciDeviceInitInitialize, aby zainicjować nieprzezroczystą strukturę WDFDEVICE_INIT. Wywołanie kojarzy sterownik klienta z ramami.

2. Po utworzeniu obiektu urządzenia ramy (WDFDEVICE) wywołaj metodę UcmTcpciDeviceInitialize, aby zarejestrować sterownik klienta z UcmTcpciCx.

Inicjowanie kanału komunikacyjnego I2C do sprzętu kontrolera portów

Przykładowe odwołanie: zobacz EvtCreateDevice w pliku Device.cpp.

W implementacji EVT_WDF_DEVICE_PREPARE_HARDWARE odczytaj zasoby sprzętowe, aby otworzyć kanał komunikacyjny. Jest to wymagane do pobrania możliwości PD i otrzymywania powiadomień o alertach.

Większość kontrolerów TCPCI jest podłączona przez I²C. W przykładzie referencyjnym sterownik klienta otwiera kanał I² przy użyciu interfejsu programowania SPB Framework Extension (SpbCx).

Sterownik klienta wylicza zasoby sprzętowe, wywołując funkcję WdfCmResourceListGetDescriptor.

Alerty są odbierane jako przerwania. W związku z tym sterownik tworzy obiekt przerwania ramy i rejestruje ISR, który obsługuje alerty. ISR wykonuje sprzętowe operacje odczytu i zapisu, które są zablokowane do momentu ukończenia dostępu do sprzętu. Ponieważ oczekiwanie nie jest dopuszczalne na poziomie DIRQL, sterownik działa na poziomie PASSIVE_LEVEL, wykonując ISR.

Zainicjuj funkcje Type-C i PD kontrolera portów

Przykładowe odwołanie: zobacz EvtDeviceD0Entry w pliku Device.cpp.

W Twojej implementacji EVT_WDF_DEVICE_D0_EXIT

1. Komunikowanie się ze sprzętem kontrolera portów i pobieranie identyfikacji i możliwości urządzeń przez odczytanie różnych rejestrów.

2. Zainicjuj UCMTCPCI_PORT_CONTROLLER_IDENTIFICATION i UCMTCPCI_PORT_CONTROLLER_CAPABILITIES przy użyciu pobranych informacji.

3. Zainicjuj strukturę UCMTCPCI_PORT_CONTROLLER_CONFIG przy użyciu poprzednich informacji przez przekazanie zainicjowanych struktur do UCMTCPCI_PORT_CONTROLLER_CONFIG_INIT.

4. Wywołaj UcmTcpciPortControllerCreate, aby utworzyć obiekt kontrolera portu i pobrać uchwyt UCMTCPCIPORTCONTROLLER.

Skonfiguruj obiekt kolejki struktury do odbierania żądań z UcmTcpciCx

Przykładowe odwołanie: zobacz EvtDeviceD0Entry w Device.cpp i HardwareRequestQueueInitialize w Queue.cpp.

1. W implementacji EVT_WDF_DEVICE_D0_EXIT utwórz obiekt kolejki struktury frameworku, wywołując funkcję WdfIoQueueCreate. W tym wywołaniu należy zarejestrować implementację wywołania zwrotnego w celu obsługi żądań IOCTL wysyłanych przez użytkownika UcmTpciCx. Sterownik klienta może używać kolejki zarządzanej przez zasilanie.

   Podczas wykonywania maszyn stanowych Type-C i PD, UcmTpciCx wysyła polecenia do wykonania przez sterownik klienta. UcmTcpciCx gwarantuje co najwyżej jedno wybitne żądanie kontrolera portów w danym momencie.

2. Wywołaj metodę UcmTcpciPortControllerSetHardwareRequestQueue, aby zarejestrować nowy obiekt kolejki struktury za pomocą interfejsu UcmTpciCx. Po pomyślnym wykonaniu tego wywołania polecenie UcmTcpciCx umieszcza obiekty kolejki struktury (WDFREQUEST) w tej kolejce, gdy wymaga akcji ze sterownika.

3. Zaimplementuj funkcję zwrotną EvtIoDeviceControl, aby obsłużyć te IOCTL.

1. Wywołaj UcmTcpciPortControllerStart, aby poinstruować UcmTcpciCx o uruchomieniu kontrolera portu. UcmTcpciCx przejmuje kontrolę nad USB Type-C i Power Delivery. Po uruchomieniu kontrolera portu narzędzie UcmTcpciCx może rozpocząć umieszczanie żądań w kolejce żądań sprzętowych.

Obsługa alertów ze sprzętu kontrolera portów

Przykładowe odwołanie: Zobacz ProcessAndSendAlerts w Alert.cpp

Sterownik klienta musi obsługiwać alerty (lub zdarzenia) odebrane ze sprzętu kontrolera portów i wysłać je do interfejsu UcmTcpciCx z danymi związanymi ze zdarzeniem.

W przypadku wystąpienia alertu sprzętowego sprzęt kontroler portów obsługuje wysoki numer PIN alertu. Powoduje to wywołanie ISR sterownika klienta (zarejestrowanego w kroku 2). Rutyna obsługuje przerwania sprzętowe na poziomie PASSIVE_LEVEL. Ta rutyna określa, czy przerwanie jest alertem ze sprzętu kontrolera portów; Jeśli tak, zakończy przetwarzanie alertu i powiadomi UcmTcpciCx przez wywołanie UcmTcpciPortControllerAlert.

Przed wywołaniem interfejsu UcmTcpciPortControllerAlert klient jest odpowiedzialny za uwzględnienie wszystkich odpowiednich danych związanych z alertem w strukturze UCMTCPCI_PORT_CONTROLLER_ALERT_DATA. Klient udostępnia tablicę wszystkich alertów, które są aktywne, ponieważ istnieje możliwość jednoczesnego potwierdzenia wielu alertów przez sprzęt.

Oto przykładowy przepływ zadań niezbędnych do zgłoszenia zmiany statusu CC.

1. Klient otrzymuje alert sprzętowy.

2. Klient odczytuje rejestr ALERTów i określa typ alertów, które są aktywne.

3. Klient odczytuje rejestr STANU DW i opisuje zawartość rejestru STANU DW w UCMTCPCI_PORT_CONTROLLER_ALERT_DATA. Sterownik ustawia element członkowski AlertType na element członkowski UcmTcpciPortControllerAlertCCStatus i CCStatus rejestru.

4. Klient wywołuje interfejs UcmPortControllerAlert, aby wysłać tablicowe alerty sprzętowe do interfejsu UcmTcpciCx.

5. Klient czyści alert (może się to zdarzyć w dowolnym momencie po pobraniu informacji o alercie przez klienta)

Przetwarzaj żądania odebrane z UcmTcpciCx

Przykładowe informacje: Zobacz PortControllerInterface.cpp

W ramach wykonywania maszyny stanu UcmTcpciCx musi wysyłać żądania do kontrolera portu. Na przykład musi ustawić TRANSMIT_BUFFER. To żądanie jest przekazywane do sterownika klienta. Sterownik ustawia bufor nadawczy ze szczegółami podanymi przez UcmTcpciCx. Większość tych żądań przekłada się na sprzętowy odczyt lub zapis przez sterownik klienta. Polecenia muszą być asynchroniczne, ponieważ program DPM nie może zablokować oczekiwania na ukończenie transferu sprzętu.

UcmTcpciCx wysyła polecenia jako kod sterowania wejścia/wyjścia opisujący operację get/set, której wymaga sterownik klienta. W konfiguracji kolejki sterownika klienta sterownik zarejestrował swoją kolejkę przy użyciu interfejsu UcmTcpciCx. UcmTcpciCx rozpoczyna umieszczanie obiektów żądań platformy w kolejce, które wymagają operacji od sterownika. Kody kontrolek we/wy są wymienione w tabeli w kroku 4.

Jest to odpowiedzialność kierowcy klienta za wykonywanie żądań w odpowiednim czasie.

Sterownik klienta wywołuje funkcję WdfRequestComplete dla obiektu żądania wewnętrznego środowiska ze stanem ukończenia, gdy zakończy żądaną operację.

Aby wykonać operację sprzętową, sterownik klienta może wymagać wysłania żądania we/wy do innego sterownika. Na przykład w przykładzie sterownik wysyła żądanie SPB do kontrolera portu podłączonego do I²C. W takim przypadku sterownik nie może przekazać obiektu żądania platformy otrzymanego z interfejsu UcmTcpciCx, ponieważ obiekt żądania może nie mieć poprawnej liczby lokalizacji stosu w IRP WDM. Sterownik klienta musi utworzyć inny obiekt żądania struktury i przekazać go do innego sterownika. Sterownik klienta może wstępnie przydzielić obiekty żądań, których potrzebuje podczas inicjowania, zamiast tworzyć jeden za każdym razem, gdy pobiera żądanie z interfejsu UcmTcpciCx. Jest to możliwe, ponieważ UcmTcpciCx gwarantuje, że w danym momencie będzie istnieć tylko jedno żądanie zaległe.

Zobacz też

• Dokumentacja rozszerzeń klasy sterowników interfejsu kontrolera portów USB Type-C