функция обратного вызова EVT_SPB_CONTROLLER_SEQUENCE (spbcx.h)

Статья
08/07/2023

Функция обратного вызова события EvtSpbControllerIoSequence драйвера контроллера SPB выполняет последовательность передачи данных между указанным целевым устройством и буферами, которые предоставляются вместе с запросом последовательности.

Синтаксис

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Параметры

[in] Controller

Дескриптор WDFDEVICE для объекта устройства платформы , представляющего контроллер SPB.

[in] Target

Дескриптор SPBTARGET для целевого объекта для этого запроса ввода-вывода. Целевой объект — это периферийное устройство или порт, подключенный к шине. Расширение платформы SPB (SpbCx) ранее назначило этот дескриптор целевому объекту в обратном вызове EvtSpbTargetConnect , открывшем подключение к целевому объекту.

[in] Request

Дескриптор SPBREQUEST для запроса ввода-вывода. Драйвер контроллера SPB должен выполнить этот запрос, выполнив запрошенную операцию или возвратив состояние ошибки. Дополнительные сведения см. в разделе Примечания.

[in] TransferCount

Количество отдельных передач в этой последовательности передачи ввода-вывода. Каждая отдельная передача является простой операцией чтения или записи.

Возвращаемое значение

None

Remarks

SpbCx управляет очередью ввода-вывода для контроллера SPB. SpbCx вызывает функцию обратного вызова EvtSpbControllerIoSequence драйвера контроллера SPB, когда клиент (драйвер периферийного устройства) контроллера SPB отправляет запрос IOCTL_SPB_EXECUTE_SEQUENCE целевому устройству, подключенному к шине. Значение параметра Request — это дескриптор, который инкапсулирует этот запрос.

Обратный вызов EvtSpbControllerIoSequence не возвращает значение состояния. Вместо этого драйвер контроллера SPB указывает состояние операции последовательности в состоянии завершения запроса ввода-вывода.

Обратный вызов EvtSpbControllerIoSequence является асинхронным. То есть функция обратного вызова должна инициировать запрошенную последовательность (или первую часть последовательности) операцию, а затем возвращать ее, не дожидаясь завершения операции. Позже драйвер контроллера SPB продолжает обработку запроса или завершает его во время прерывания DPC или контроллера таймера.

Драйвер контроллера SPB может получить значения параметров из запроса ввода-вывода, чтобы определить максимальную длину передач в последовательности. Драйвер может использовать эту длину для выделения ресурсов DMA, которые он может повторно использовать для каждой передачи в последовательности.

Драйвер контроллера SPB может вызвать метод SpbRequestGetTransferParameters для получения параметров управления и буфера данных для каждой передачи в последовательности. Буфер — это объект WDFMEMORY, который в текущей реализации инкапсулирует цепной MDL. Дополнительные сведения о цепочек MDL см. в разделе Использование многомерных выражений.

Контроллер SPB должен оставить целевое устройство выбранным для всей операции последовательности. Если целевой объект выбран линией выбора устройства, строка может постоянно утверждаться с начала первой передачи в последовательности до окончания последней передачи. Эта строка может быть заявлена уже после операции блокировки в начале последовательности и может оставаться в ней до тех пор, пока операция разблокировки не завершится.

Для каждой передачи в последовательности можно указать необязательную задержку. Драйвер контроллера SPB отвечает за задержку по крайней мере этого количества микросекунд перед началом передачи. Если первая передача в последовательности связана с задержкой, драйвер должен сначала передать адрес или подтвердить линию выбора устройства целевого устройства, а затем отложить на указанное время, прежде чем начать передачу данных. Во время этой задержки целевой объект должен оставаться выбранным, но контроллер не должен запускать часы в шине.

Если целевое устройство сигнализирует о NACK во время передачи в последовательности, контроллер SPB останавливает последовательность. (То есть контроллер не повторяет неудачную передачу и не пытается выполнить остальные передачи в последовательности.) В этом случае драйвер контроллера SPB должен задать состояние завершения запроса ввода-вывода на STATUS_SUCCESS, задать для поля Сведения в блоке состояния ввода-вывода количество фактически переданных байтов (не считая данных, потерянных при передаче, которая получила NACK), и завершить запрос.

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

Контроллер SPB не может выбрать целевое устройство (например, целевое устройство в шине I²C сигнализирует о NACK, когда контроллер передает байт адреса).
Драйвер контроллера SPB получает состояние ошибки при вызове службы WDF или WDM при обработке операции последовательности.

Чтобы зарегистрировать функцию обратного вызова EvtSpbControllerIoSequence , вызовите метод SpbDeviceInitialize .

Примеры

Чтобы определить функцию обратного вызова EvtSpbControllerIoSequence , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию обратного вызова EvtSpbControllerIoSequence с именем MyEvtSpbControllerIoSequence, используйте тип функции EVT_SPB_CONTROLLER_SEQUENCE, как показано в следующем примере кода:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Затем реализуйте функцию обратного вызова следующим образом:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

Тип функции EVT_SPB_CONTROLLER_SEQUENCE определен в файле заголовка Spbcx.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции EVT_SPB_CONTROLLER_SEQUENCE в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в разделе Объявление функций с помощью типов ролей функций для драйверов KMDF. Дополнительные сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	spbcx.h
IRQL	Вызывается в IRQL <= DISPATCH_LEVEL.

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