Obsługa potoków USB

Framework reprezentuje każdy potok w interfejsie USB jako obiekt potoku USB frameworku. Gdy sterownik konfiguruje urządzenie USB, platforma tworzy obiekt rurociągu USB dla każdego rurociągu w każdym wybranym interfejsie. Metody obiektu potoku umożliwiają sterownikowi wykonywanie następujących operacji:

• Uzyskaj informacje o rurze.

• Wykonaj odczyt z potoku.

• Pisz do potoku.

• Zatrzymaj lub zresetuj rurę.

• Wyślij URB do rury.

uzyskiwanie informacji o przewodzie

Po wywołaniu WdfUsbInterfaceGetConfiguredPipe w celu uzyskania uchwytu do obiektu potoku USB struktury sterownik może wywołać następujące metody, które obiekt potoku USB definiuje w celu uzyskania informacji o potoku USB:

WdfUsbTargetPipeGetIoTarget
Zwraca uchwyt do obiektu docelowego wejścia/wyjścia skojarzonego z potokiem USB. Sterownik może przekazać ten uchwyt do WdfRequestSend.

WdfUsbTargetPipeGetInformation
Pobiera informacje o potoku USB i jego punkcie końcowym.

WdfUsbTargetPipeGetType
Zwraca typ potoku USB.

WdfUsbTargetPipeIsInEndpoint
Określa, czy potok USB jest podłączony do wejściowego punktu końcowego.

WdfUsbTargetPipeIsOutEndpoint
Określa, czy potok USB jest podłączony do wyjściowego punktu końcowego.

WDF_USB_PIPE_DIRECTION_IN
Określa, czy punkt końcowy USB jest punktem końcowym wejściowym.

WDF_USB_PIPE_DIRECTION_OUT
Określa, czy punkt końcowy USB jest punktem końcowym wyjściowym.

Aby uzyskać powiązane informacje, zobacz też Jak wyliczać potoki USB.

odczytywanie z potoku

Aby odczytać dane z rury wejściowej USB, sterownik może użyć dowolnych (lub wszystkich) następujących trzech technik:

• Synchronicznie odczytywanie danych

  Aby synchronicznie odczytywać dane z potoku wejściowego USB, sterownik może wywołać metodę WdfUsbTargetPipeReadSynchronously. Ta metoda kompiluje i wysyła żądanie odczytu i zwraca je po zakończeniu operacji we/wy.

• Odczytywanie danych asynchronicznie

  Aby odczytywać dane asynchronicznie z potoku wejściowego USB, sterownik może wywołać metodę WdfUsbTargetPipeFormatRequestForRead w celu skompilowania żądania odczytu. Następnie sterownik może wywołać WdfRequestSend, aby wysłać żądanie asynchronicznie (lub synchronicznie).

• Odczytuj dane asynchronicznie i ciągle

  czytnik ciągły jest mechanizmem dostarczonym przez system, aby zapewnić, że żądanie odczytu jest zawsze dostępne dla potoku USB. Ten mechanizm gwarantuje, że sterownik będzie zawsze gotowy do odbierania danych z urządzenia, które zapewnia asynchroniczny, niepożądany strumień wejściowy. Na przykład sterownik karty sieciowej (NIC) może używać ciągłego czytnika do odbierania danych wejściowych.

  Aby skonfigurować czytnik ciągły dla potoku wejściowego, EvtDevicePrepareHardware funkcja wywołania zwrotnego musi wywołać funkcję WdfUsbTargetPipeConfigContinuousReader. Ta metoda kolejkuje zestaw żądań odczytu do docelowego urządzenia I/O.

  Ponadto funkcja wywołania zwrotnego EvtDeviceD0Entry musi wywołać WdfIoTargetStart, aby uruchomić czytnik ciągły, a funkcja wywołania zwrotnego EvtDeviceD0Exit musi wywołać WdfIoTargetStop, aby zatrzymać czytnik ciągły.

  Za każdym razem, gdy dane są dostępne na urządzeniu, docelowy we/wy ukończy żądanie odczytu, a struktura wywoła jedną z dwóch funkcji wywołania zwrotnego: EvtBTargetPipeReadComplete, jeśli cel we/wy pomyślnie odczytuje dane, lub EvtUsbTargetPipeReadersFailed, jeśli docelowy we/wy zgłasza błąd.

  Jeśli nie podasz opcjonalnego EvtUsbTargetPipeReadersFailed wywołania zwrotnego, struktura odpowiada na nieudaną próbę odczytu, wysyłając kolejne żądanie odczytu. W związku z tym, jeśli magistrala jest w stanie, w którym nie akceptuje odczytów, platforma stale wysyła nowe żądania w celu odzyskania po nieudanym odczytaniu.

  Po wywołaniu sterownika WdfUsbTargetPipeConfigContinuousReader, nie można użyć WdfUsbTargetPipeReadSynchronously lub WdfRequestSend do wysyłania żądań WE/WY do potoku, chyba że funkcja wywołania zwrotnego EvtUsbTargetPipeReadersFailed zostanie wywołana i zwróci FALSE.

Domyślnie platforma zgłasza błąd, jeśli sterownik określa bufor odczytu, który nie jest wielokrotnością maksymalnego rozmiaru pakietu potoku. Sterownik może wywołać WdfUsbTargetPipeSetNoMaximumPacketSizeCheck, aby wyłączyć ten test rozmiarów buforu odczytu.

Aby uzyskać powiązane informacje, zobacz:

• Jak wysyłać żądania transferu zbiorczego USB
• Jak przesyłać dane do izochronicznych punktów końcowych USB
• Jak używać czytnika strumieniowego do odczytywania danych z potoku USB

Pisanie do rury

Aby zapisać dane w kanale wyjściowym USB, sterownik może użyć jednej (lub obu) z następujących technik:

• Synchronicznie zapisuj dane

  Aby zapisać dane synchronicznie w potoku wyjściowym USB, sterownik może wywołać metodę WdfUsbTargetPipeWriteSynchronously. Ta metoda kompiluje i wysyła żądanie zapisu i zwraca je po zakończeniu operacji we/wy.

• Asynchronicznie zapisuj dane

  Aby zapisać dane asynchronicznie do potoku wejściowego USB, sterownik może wywołać metodę WdfUsbTargetPipeFormatRequestForWrite w celu zbudowania żądania zapisu. Następnie sterownik może wywołać WdfRequestSend, aby wysłać żądanie asynchronicznie.

Aby uzyskać powiązane informacje, zobacz Jak wysyłać żądania transferu zbiorczego USB.

zatrzymywanie i resetowanie potoku

Sterownik może wywołać następujące metody, aby zatrzymać lub zresetować potok USB:

WdfUsbTargetPipeAbortSynchronously
Synchronicznie wysyła żądanie zatrzymania kanału USB.

WdfUsbTargetPipeFormatRequestForAbort
Formatuje żądanie zatrzymania rury USB. Sterownik może wywołać WdfRequestSend, aby wysłać żądanie synchronicznie lub asynchronicznie.

WdfUsbTargetPipeResetSynchronously
Synchronicznie wysyła żądanie zresetowania rury USB.

WdfUsbTargetPipeFormatRequestForReset
Formatuje żądanie zresetowania kanału USB. Sterownik musi wywołać WdfRequestSend, aby wysłać żądanie synchronicznie lub asynchronicznie.

Jeśli docelowa USB sterownika zakończy żądanie wejścia/wyjścia z wartością stanu błędu, sterownik powinien wykonać następujące czynności:

1. Zatrzymaj kanał i anuluj wszystkie dodatkowe żądania wejścia/wyjścia, które sterownik wysłał do urządzenia docelowego USB, jeśli urządzenie docelowe nie zakończyło żądań.

   Wywołaj WdfIoTargetStop z ustawioną flagą WdfIoTargetCancelSentIo.

2. Synchronicznie wyślij żądanie przerwania do potoku.

   Wywołaj WdfUsbTargetPipeAbortSynchronouslylub wywołaj WdfUsbTargetPipeFormatRequestForAbort a następnie WdfRequestSend z zestawem flagi WDF_REQUEST_SEND_OPTION_SYNCHRONOUS.

3. Synchronicznie wyślij żądanie resetowania do potoku.

   Wywołaj WdfUsbTargetPipeResetSynchronouslylub wywołaj WdfUsbTargetPipeFormatRequestForReset a następnie WdfRequestSend z ustawionym flagą WDF_REQUEST_SEND_OPTION_SYNCHRONOUS.

4. Uruchom ponownie potok.

   Wywołaj WdfIoTargetStart.

5. Wyślij ponownie żądanie we/wy, które zakończyło się niepowodzeniem, i wszystkie żądania we/wy, które nastąpiły po żądaniu, które zakończyły się niepowodzeniem.

Po znacznej liczbie wielu awarii sterownik powinien spróbować zresetować port USB, wykonując następujące czynności:

1. Zatrzymaj wszystkie aktywne potoki i anuluj wszelkie dodatkowe żądania we/wy, które sterownik wysłał do docelowego urządzenia USB każdego potoku, jeśli nie zostały one ukończone przez urządzenie docelowe.

   Dla każdego aktywnego potoku wywołaj WdfIoTargetStop z ustawioną flagą WdfIoTargetCancelSentIo.

2. Synchronicznie wyślij żądanie zresetowania portu USB.

   Wywołaj WdfUsbTargetDeviceResetPortSynchronously.

3. Uruchom ponownie rury.

   Wywołaj WdfIoTargetStart dla każdego kanału zatrzymanego przez sterownik.

4. Wyślij ponownie ostatnie żądanie we/wy, które zakończyło się niepowodzeniem, oraz wszystkie kolejne żądania we/wy, które nastąpiły po nim.

Aby uzyskać powiązane informacje, zobacz Jak odzyskiwać po błędach przesyłu USB.

wysyłanie URB do rurki

Jeśli sterownik KMDF komunikuje się z kanałem USB, wysyłając żądania we/wy zawierające URBy, sterownik może wywołać następujące metody:

WdfUsbTargetPipeSendUrbSynchronously (tylko KMDF)
Synchronicznie wysyła żądanie We/Wy zawierające URB.

WdfUsbTargetPipeFormatRequestForUrb (tylko dla KMDF)
Formatuje żądanie I/O zawierające URB. Sterownik może wywołać WdfRequestSend, aby wysłać żądanie synchronicznie lub asynchronicznie.

WdfUsbTargetPipeWdmGetPipeHandle (tylko KMDF)
Zwraca uchwyt potoku USBD urządzenia. Niektóre bloki żądań USB wymagają tego uchwytu.