структура WDF_USB_CONTINUOUS_READER_CONFIG (wdfusb.h)

Статья
02/07/2025

[Применимо к KMDF и UMDF]

Структура WDF_USB_CONTINUOUS_READER_CONFIG содержит сведения, которые платформа использует для настройки непрерывного чтения для USB-канала.

Синтаксис

typedef struct _WDF_USB_CONTINUOUS_READER_CONFIG {
  ULONG                                 Size;
  size_t                                TransferLength;
  size_t                                HeaderLength;
  size_t                                TrailerLength;
  UCHAR                                 NumPendingReads;
  PWDF_OBJECT_ATTRIBUTES                BufferAttributes;
  PFN_WDF_USB_READER_COMPLETION_ROUTINE EvtUsbTargetPipeReadComplete;
  WDFCONTEXT                            EvtUsbTargetPipeReadCompleteContext;
  PFN_WDF_USB_READERS_FAILED            EvtUsbTargetPipeReadersFailed;
} WDF_USB_CONTINUOUS_READER_CONFIG, *PWDF_USB_CONTINUOUS_READER_CONFIG;

Члены

Size

Размер этой структуры в байтах.

TransferLength

Максимальная длина данных в байтах, которые можно получить с устройства.

HeaderLength

Смещение в байтах в буфер, получающий данные от устройства. Платформа будет хранить данные с устройства в буфере чтения, начиная со значения смещения. Другими словами, это пространство предшествует TransferLength-размер пространства, в котором платформа хранит данные с устройства.

TrailerLength

Длина в байтах конечного буферного пространства. Это пространство следует TransferLength-размер пространства, в котором платформа хранит данные с устройства.

NumPendingReads

Количество запросов на чтение, которые платформа будет ставить в очередь для получения данных из целевого объекта ввода-вывода. Если это значение равно нулю, платформа использует число запросов чтения по умолчанию. Если указанное значение больше допустимого максимума, платформа использует разрешенное максимальное значение. Дополнительные сведения о элементе NumPendingReads см. в следующем разделе "Примечания".

BufferAttributes

Структура WDF_OBJECT_ATTRIBUTES, указывающая атрибуты объектов для объекта памяти платформы, который платформа создает для каждого запроса на чтение. Этот элемент может быть null. Невозможно задать элемент ParentObject структуры WDF_OBJECT_ATTRIBUTES.

EvtUsbTargetPipeReadComplete

Указатель на функцию обратного вызова драйвера EvtUsbTargetPipeReadComplete.

EvtUsbTargetPipeReadCompleteContext

Нетипизированный указатель на определяемые драйвером сведения о контексте, которые платформа передает драйвера EvtUsbTargetPipeReadComplete функцию обратного вызова.

EvtUsbTargetPipeReadersFailed

Указатель на функцию обратного вызова драйвера EvtUsbTargetPipeReadersFailed. Этот указатель необязателен и может быть null. Дополнительные сведения об этом параметре см. в разделе "Примечания" WdfUsbTargetPipeConfigContinuousReader.

Замечания

Структура WDF_USB_CONTINUOUS_READER_CONFIG используется в качестве входных данных для метода WdfUsbTargetPipeConfigContinuousReader.

Чтобы инициализировать структуру WDF_USB_CONTINUOUS_READER_CONFIG, драйвер должен вызвать WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

Используйте следующие рекомендации при выборе значения для элемента NumPendingReads:

Задайте для NumPendingReads значение 0, если вы хотите, чтобы драйвер использовал значение по умолчанию платформы.
Значение по умолчанию больше 1 и определено, чтобы обеспечить достаточно хорошую производительность для многих устройств во многих конфигурациях процессора.
Установите NumPendingReads значение 1, если важно, чтобы драйвер получал буферы данных в том порядке, в который устройство доставляет данные.
Задайте NumPendingReads числом, удовлетворяющим требованиям к производительности устройства, на основе тщательного измерения производительности.
Сначала проверьте устройство со значением по умолчанию (0) для NumPendingReads. Тесты должны включать различные аппаратные конфигурации, включая различные типы и номера процессоров и различные контроллеры USB-узла и USB-конфигурации. Затем можно экспериментировать с более высокими значениями, используя те же тесты. Драйвер, который может потребовать более высокого значения, является одним для устройства с высокой скоростью прерываний, где данные могут быть потеряны, если прерывания не обслуживаются быстро.

Значение NumPendingReads, которое слишком велико, может замедлить производительность системы. Необходимо использовать наименьшее значение, соответствующее вашим требованиям к производительности. Как правило, значения, превышающие 3 или 4, не повышают пропускную способность данных. Но более высокие значения могут снизить задержку или вероятность отсутствия данных на канале высокой частоты.