Поделиться через

Функции WinUSB для изменения политики канала

  • Статья

Чтобы приложения могли получать и задавать параметры политики политики канала конечной точки по умолчанию, Winusb.dll предоставляет функцию WinUsb_GetPipePolicy для получения политики по умолчанию канала. Функция WinUsb_SetPipePolicy позволяет приложению задать параметр политики новым значением.

WinUSB позволяет изменить поведение по умолчанию, применяя политики к каналу конечной точки. С помощью этих политик вы можете настроить WinUSB для оптимального соответствия устройств своим возможностям. В следующей таблице приведен список политик канала, поддерживаемых WinUSB.

Примечание.

Политики, описанные в таблице, допустимы только для указанных конечных точек. Настройка политики на других конечных точках не влияет на поведение WinUSB для запросов на чтение или запись.

Номер политики Имя политики Description Конечная точка (направление) Default value
0x01 SHORT_PACKET_TERMINATE Отправляет пакет нулевой длины для запроса на запись, в котором буфер является нескольким из максимального размера пакета, поддерживаемого конечной точкой. Bulk (OUT)

Прерывание (OUT)		 FALSE
0x02 AUTO_CLEAR_STALL Автоматически очищает застойный канал без остановки потока данных. Массовый (IN)

Прерывание (IN)		 FALSE
0x03 PIPE_TRANSFER_TIMEOUT Ожидает интервал времени ожидания в миллисекундах перед отменой запроса. Массовый (IN)

Bulk (OUT)

Прерывание (IN)

Прерывание (OUT)		 5 секунд (5000 миллисекунд) для управления; 0 для других
0x04 IGNORE_SHORT_PACKETS Завершает запрос на чтение при получении короткого пакета или определенного количества байтов. Если размер файла неизвестен, запрос завершается по короткому пакету. Массовый (IN)

Прерывание (IN)		 FALSE
0x05 ALLOW_PARTIAL_READS Разрешает чтение запросов с устройства, которое возвращает больше данных, чем запрашивается вызывающим абонентом. Массовый (IN)

Прерывание (IN)		 TRUE
0x06 AUTO_FLUSH Сохраняет избыточные данные из запроса на чтение и добавляет его в следующий запрос на чтение или удаляет избыточные данные. Массовый (IN)

Прерывание (IN)		 FALSE
0x07 RAW_IO Пропускает очередь и обработку ошибок для повышения производительности для нескольких запросов на чтение. Массовый (IN)

Прерывание (IN)		 FALSE
0x08 MAXIMUM_TRANSFER_SIZE Возвращает максимальный размер USB-передачи, поддерживаемой WinUSB. Это политика только для чтения, которую можно получить путем вызова WinUsb_GetPipePolicy. Массовый (IN)

Bulk (OUT)

Прерывание (IN)

Прерывание (OUT)
0x09 RESET_PIPE_ON_RESUME Сбрасывает канал конечной точки после возобновления приостановки перед принятием новых запросов. Массовый (IN)

Bulk (OUT)

Прерывание (IN)

Прерывание (OUT)		 FALSE

В следующей таблице описаны рекомендации по использованию каждой из политик канала и описание результирующего поведения при включении политики.

Политика Включите, если... Поведение
SHORT_PACKET_TERMINATE(0x01) Для устройства требуется, чтобы передача out была завершена с помощью пакета нулевой длины. Большинство устройств не имеют этого требования. Если параметр политики включен (значение параметра политики равно TRUE или ненулевому), то за каждым запросом на запись, который является кратным максимальным размером пакетов, поддерживаемым конечной точкой, следует пакет нулевой длины.

После отправки данных на контроллер узла WinUSB отправляет запрос на запись с пакетом нулевой длины, а затем завершает запрос, созданный WinUsb_WritePipe.
AUTO_CLEAR_STALL Вы не хотите, чтобы неудачные передачи не покидали конечную точку в застопорном состоянии. Эта политика полезна только при наличии нескольких ожидающих запросов на чтение в конечную точку при отключении RAW_IO.
  • Если параметр политики включен (значение параметра политики равно TRUE или ненулевому), условие остановки очищается автоматически. Этот параметр политики не влияет на каналы управления.

    Если запрос на чтение завершается ошибкой, и контроллер узла возвращает состояние, отличное от STATUS_CANCELLED или STATUS_DEVICE_NOT_CONNECTED, WinUSB сбрасывает канал перед завершением неудачного запроса. Сброс канала очищает условие остановки без прерывания потока данных. Данные продолжают поступать в конечные точки до тех пор, пока новые передачи продолжают поступать с устройства. Новый перенос может включать тот, который был в очереди, когда произошел застой.

    Включение этой политики значительно не влияет на производительность.

  • Если значение параметра политики отключено (значение параметра политики равно FALSE или нулю), все передачи, поступающие в конечную точку после сбоя остановленной передачи, пока вызывающий объект вручную не сбрасывает канал конечной точки путем вызова WinUsb_ResetPipe.
PIPE_TRANSFER_TIMEOUT Вы ожидаете, что передача в конечную точку завершится в течение определенного времени.
  • Если задано равно нулю (по умолчанию), передача не будет истекать, так как контроллер узла не отменяет передачу. В этом случае передача ожидается неограниченное время, пока она не будет отменена вручную или передача завершается нормально.
  • Если задано значение ненулевого значения (интервал времени ожидания), контроллер узла запускает таймер при получении запроса на передачу. Когда таймер превышает заданный интервал времени ожидания, запрос отменяется.

    Незначительные штрафы за производительность возникают из-за управления таймером.

    Запросы не истекает во время ожидания в очереди WinUSB.

    В Windows Vista для всех передач (кроме передачи с включенным RAW_IO), WinUSB очереди запроса до завершения всех предыдущих передач в конечной точке назначения. Контроллер узла не включает время очереди в расчет интервала времени ожидания.

    Если включена RAW_IO, WinUSB не очереди запроса. Вместо этого он передает запрос непосредственно в стек USB, будет ли usb-стек занят обработкой предыдущих передач. Если стек USB занят, он может отложить обработку нового запроса. Это может привести к истечении времени ожидания.
IGNORE_SHORT_PACKETS RAW_IO отключен, и вы не хотите, чтобы короткие пакеты завершили запросы на чтение.
  • Если параметр политики включен (значение параметра политики равно TRUE или ненулевому), контроллер узла не завершит операцию чтения сразу после получения короткого пакета. Вместо этого операция завершается только в том случае, если:
    • Происходит ошибка.
    • Запрос отменен.
    • Получены все запрошенные байты.
  • Если параметр политики отключен (значение параметра политики равно FALSE или нулю), контроллер узла завершает операцию чтения после того, как он считывает запрошенное число байтов или получил короткий пакет.
ALLOW_PARTIAL_READS Устройство может отправлять больше данных, чем запрашивается, если размер буфера запроса является нескольким из максимального размера пакета конечной точки.

Используйте, если приложение хочет прочитать несколько байтов, чтобы определить, сколько байтов требуется для чтения.
  • Если параметр политики отключен (значение параметра политики равно FALSE или нулю), а устройство возвращает больше данных, чем запрошено, WinUSB завершает запрос ошибкой.
  • Если параметр политики имеет значение TRUE или ненулевое значение, а устройство возвращает больше данных, чем запрошено, WinUSB может (в зависимости от параметров AUTO_FLUSH) добавить избыточные данные из запроса на чтение в начало следующего запроса на чтение или отменить избыточные данные.

    Если этот параметр включен, WinUSB немедленно завершает запросы на чтение для нулевых байтов и не отправляет запросы вниз по стеку.
AUTO_FLUSH ALLOW_PARTIAL_READS политика включена.

Устройство может отправлять больше данных, чем запрошено, и ваше приложение не требует других данных. Это возможно, если размер буфера запроса является нескольким из максимального размера пакета конечной точки.		 AUTO_FLUSH определяет поведение WinUSB при включении ALLOW_PARTIAL_READS. Если ALLOW_PARTIAL_READS отключен, значение AUTO_FLUSH игнорируется WinUSB.

WinUSB может отменить оставшиеся данные или отправить его с помощью следующего запроса на чтение вызывающего средства.

  • Если параметр политики включен (значение параметра политики равно TRUE или ненулевому), WinUSB удаляет дополнительные байты без какого-либо кода ошибки.
  • Если параметр политики отключен (значение параметра политики равно FALSE или нулю), WinUSB сохраняет дополнительные байты, добавляет их в начало следующего запроса на чтение вызывающего объекта, а затем отправляет данные вызывающему объекту в следующей операции чтения.
RAW_IO Производительность является приоритетом, и приложение отправляет одновременные запросы на чтение в ту же конечную точку.

RAW_IO накладывает определенные ограничения на буфер, передаваемый вызывающим объектом в WinUsb_ReadPipe:

  • Длина буфера должна быть несколькими из максимального размера пакета конечной точки.
  • Длина должна быть меньше или равна значению MAXIMUM_TRANSFER_SIZE, полученному WinUsb_GetPipePolicy.
 Если этот параметр включен, передача обхода очереди и обработки ошибок для повышения производительности для нескольких запросов на чтение. WinUSB обрабатывает запросы на чтение следующим образом:

  • Запрос, который не является нескольким из максимального размера пакета конечной точки, завершается сбоем.
  • Запрос, превышающий максимальный размер передачи, поддерживаемый WinUSB, завершается ошибкой.
  • Все хорошо сформированные запросы немедленно отправляются в стек ядра USB для планирования в контроллере узла.


Включение этого параметра значительно повышает производительность нескольких запросов на чтение, уменьшая задержку между последним пакетом одной передачи и первым пакетом следующей передачи.
RESET_PIPE_ON_RESUME Устройство не сохраняет состояние переключения данных во время приостановки. При возобновлении приостановки WinUSB сбрасывает конечную точку, прежде чем разрешить вызывающему объекту отправлять новые запросы в конечную точку.