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

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

  • Статья

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

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

Примечание

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

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

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

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

Массовый (OUT)

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

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

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

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

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

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

Массовый (OUT)

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

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

Массовый (OUT)

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

Прерывание (OUT)		 Ложь.

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

Политика Включить, если... Поведение
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 Ожидается, что передача данных в конечную точку завершится в течение определенного времени.
  • Если задано значение 0 (по умолчанию), время ожидания передачи не истекает, так как контроллер узла не отменит передачу. В этом случае передача ожидается неограниченное время, пока она не будет отменена вручную или передача не завершится в обычном режиме.
  • Если задано ненулевое значение (интервал времени ожидания), контроллер узла запускает таймер при получении запроса на передачу. Когда таймер превышает заданный интервал времени ожидания, запрос отменяется.

    Небольшое снижение производительности происходит из-за управления таймером.

    Время ожидания запросов в очереди 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 отключен, winUSB игнорирует значение AUTO_FLUSH.

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

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

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

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

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


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