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

  • Статья

Предупреждение

UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. В UMDF 1 новые функции не добавляются, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2.

Архивные примеры UMDF 1 можно найти в Windows 11 версии 22H2 — обновление примеров драйверов за май 2022 г.

Дополнительные сведения см. в разделе начало работы с помощью UMDF.

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

Получение сведений о канале 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. Повторно отправьте запрос ввода-вывода, который завершился сбоем, и все запросы ввода-вывода, которые последовали за неудачным запросом.