Работа с USB-каналами в драйверах UMDF 1.x

Платформа представляет каждый канал в USB-интерфейсе в виде объекта USB-канала платформы. Когда драйвер настраивает USB-устройство, платформа создает объект USB-канала платформы для каждого канала в каждом выбранном интерфейсе. Методы объекта pipe позволяют драйверу:

• Получение сведений о трубе.

• Чтение из канала.

• запись в канал.

• Остановить, промыть или сброситьканал.

• Задать политику трубопровода.

• Обработка ошибок канала.

Получение сведений о трубе UMDF-USB

После того как драйвер UMDF вызовет метод IWDFUsbInterface::RetrieveUsbPipeObject для получения указателя на интерфейс IWDFUsbTargetPipe для объекта USB-канала, драйвер может вызвать следующие методы, которые объект USB-канала предоставляет для получения сведений об USB-канале:

IWDFUsbTargetPipe::GetInformation
Извлекает сведения о USB-канале и его конечной точке.

IWDFUsbTargetPipe::GetType
Возвращает тип USB-канала.

IWDFUsbTargetPipe::IsInEndPoint
Определяет, подключен ли USB-канал к входной конечной точке.

IWDFUsbTargetPipe::IsOutEndPoint
Определяет, подключен ли USB-канал к выходной конечной точке.

IWDFUsbTargetPipe::RetrievePipePolicy
Извлекает политику канала данных WinUsb.

Чтение из канала UMDF-USB

Чтобы считывать данные из USB-канала ввода, драйвер может использовать любой из следующих методов:

• Синхронно считывать данные.

  Чтобы считывать данные синхронно из USB-канала ввода, драйвер UMDF сначала вызывает метод IWDFIoTarget::FormatRequestForRead для создания запроса на чтение. Затем драйвер вызывает метод IWDFIoRequest::Send, указав флаг WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, чтобы отправить запрос синхронно.

• Асинхронно считывать данные.

  Чтобы асинхронно считывать данные из USB-канала ввода, драйвер UMDF сначала вызывает метод IWDFIoTarget::FormatRequestForRead для создания запроса на чтение. Затем драйвер вызывает метод IWDFIoRequest::Send без указания флага WDF_REQUEST_SEND_OPTION_SYNCHRONOUS.

• Синхронно и непрерывно считывать данные.

  непрерывный считыватель — это механизм, предоставляемый платформой, который гарантирует, что запрос на чтение всегда доступен для USB-канала. Этот механизм гарантирует, что драйвер всегда готов получать данные от устройства, предоставляющего асинхронный неопрошенный входной поток. Например, драйвер сетевой карты (сетевой адаптер) может использовать непрерывное средство чтения для получения входных данных.

  Чтобы настроить непрерывное средство чтения для входного канала, драйвер должен вызвать функцию обратного вызова IPnpCallbackHardware::OnPrepareHardware методом IWDFUsbTargetPipe2::ConfigureContinuousReader. Этот метод помещает в очередь набор запросов на чтение в целевой объект устройства ввода-вывода.

  Кроме того, функция обратного вызова драйвера IPnpCallback::OnD0Entry должна вызывать IWDFIoTargetStateManagement::Start для запуска непрерывного считывателя, а функция обратного вызова драйвера IPnpCallback::OnD0Exit должна вызывать IWDFIoTargetStateManagement::Stop, чтобы остановить непрерывный считыватель.

  Каждый раз, когда данные доступны на устройстве, целевой объект ввода-вывода завершит запрос на чтение, и платформа вызовет одну из двух функций обратного вызова: IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion, если целевой объект ввода-вывода успешно считывает данные, или IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure, если целевой объект ввода-вывода сообщает об ошибке.

  После вызова драйвера IWDFUsbTargetPipe2::ConfigureContinuousReader, драйвер не может использовать IWDFIoRequest::Send для отправки запросов ввода-вывода в канал, если не вызывается функция обратного вызова драйвера IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure и не возвращает FALSE.

  Непрерывные считыватели поддерживаются в UMDF версии 1.9 и более поздних.

Запись в канал UMDF-USB

Чтобы записать данные в usb-канал вывода, драйвер UMDF может сначала вызвать метод IWDFIoTarget::FormatRequestForWrite для создания запроса на запись. Затем драйвер может вызвать метод IWDFIoRequest::Send для асинхронной отправки запроса.

остановка, очистка и сброс трубы UMDF-USB

Драйвер UMDF может вызывать следующие методы для остановки, сброса или очистки USB-пайпа:

IWDFUsbTargetPipe::Abort
Синхронно отправляет запрос, чтобы остановить все ожидающие передачи на USB-канале.

IWDFUsbTargetPipe::Flush
Синхронно отправляет запрос на удаление любых данных, сохраненных WinUsb, когда устройство вернуло больше данных, чем запрашивается клиентом.

IWDFUsbTargetPipe::Reset
Синхронно отправляет запрос на сброс USB трубки.

настройка политики для канала UMDF-USB

Драйвер UMDF может вызывать метод IWDFUsbTargetPipe::SetPipePolicy для управления поведением, которое используется WinUsb для USB-канала (например, время ожидания, обработка коротких пакетов и другое поведение).

Обработка ошибок пайпа

Если usb-целевой объект драйвера завершает запрос ввода-вывода со значением состояния ошибки, драйвер должен выполнить следующее:

1. Вызовите IWDFIoTargetStateManagement::Stop с установленным флагом WdfIoTargetCancelSentIo. Этот вызов останавливает канал и отменяет все дополнительные запросы ввода-вывода, отправленные драйвером в USB-целевой объект, если целевой объект не завершил запросы.

2. Вызовите IWDFUsbTargetPipe::Abort, чтобы отправить запрос прерывания в поток.

3. Вызовите IWDFUsbTargetPipe::Reset, чтобы отправить запрос на сброс в канал.

4. Вызовите IWDFIoTargetStateManagement::Start, чтобы перезапустить канал.

5. Повторно отправьте запрос ввода-вывода, который завершился ошибкой, и все запросы ввода-вывода, которые последовали за неудачным запросом.