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

Статья
10/30/2024

Функция обратного вызова событий EvtSerCx2PioTransmitDrainFifo вызывается версией 2 расширения последовательной платформы (SerCx2) для очистки передачи FIFO в оборудовании последовательного контроллера.

Синтаксис

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO EvtSercx2PioTransmitDrainFifo;

void EvtSercx2PioTransmitDrainFifo(
  [in] SERCX2PIOTRANSMIT PioTransmit
)
{...}

Параметры

[in] PioTransmit

Дескриптор SERCX2PIOTRANSMIT объекту PIO-передачи. Драйвер последовательного контроллера, ранее называемый методом SerCx2PioTransmitCreate для создания этого объекта.

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

Никакой

Замечания

Драйвер последовательного контроллера может реализовать эту функцию в качестве параметра. Если драйвер реализует эту функцию, он также должен реализовать EvtSerCx2PioTransmitCancelDrainFifo и EvtSerCx2PioTransmitPurgeFifo функции обратного вызова событий. Драйвер, реализующий эти функции, регистрирует их в вызове SerCx2PioTransmitCreate, который создает объект передачи PIO.

SerCx2 вызывает функцию EvtSerCx2PioTransmitDrainFifo, если она реализована, для очистки передачи FIFO в оборудовании последовательного контроллера в конце транзакции передачи PIO-передачи. Эта функция гарантирует, что все байты данных, оставшиеся в передаче FIFO, передаются на последовательно подключенное периферийное устройство. После передачи последнего байта из FIFO функция EvtSerCx2PioTransmitDrainFifo вызывает метод SerCx2PioTransmitDrainFifoComplete для уведомления SerCx2.

Если драйвер последовательного контроллера реализует функцию EvtSerCx2PioTransmitDrainFifo, SerCx2 не завершает запрос ожидающей записи (IRP_MJ_WRITE) до тех пор, пока драйвер не вызывает SerCx2PioTransmitDrainFifoComplete.

Если последовательный контроллер имеет аппаратный механизм FIFO (или аналогичный механизм буферизации) для хранения данных, драйвер должен реализовать функцию EvtSerCx2PioTransmitDrainFifo. В противном случае SerCx2 не может подтвердить утечку FIFO перед завершением ожидающего запроса на запись. Вместо этого SerCx2 завершает этот запрос после последнего байта в буфере записи записывается в передаваемый FIFO. Невозможно гарантировать, что данные, записанные на передачу FIFO, будут передаваться без значительной задержки. Все данные, остающиеся в FIFO после завершения запроса на запись, могут быть потеряны до его передачи на подключенное периферийное устройство последовательно. Эта непредвиденная потеря данных в успешно завершенном запросе на запись может создать проблемы надежности для периферийного драйвера.

Например, периферийный драйвер может отправлять запросы на запись в последовательный порт, к которому подключено периферийное устройство. Пока не будут завершены все незавершенные запросы на запись, этот драйвер должен отложить отправку IOCTL для изменения скорости передачи данных последовательного порта. Однако если функция EvtSerCx2PioTransmitDrainFifo не реализована, запрос на запись для передачи 100 байт данных может быть завершен, а 50 байт данных по-прежнему остаются в передаче FI FO. Если периферийный драйвер отправляет IOCTL для задания новой скорости baud, некоторые из оставшихся байтов в FIFO могут передаваться по новой скорости baud, вызывая ошибку.

Аналогичным образом, если запрос на запись для передачи 100 байт данных завершен, а 50 байт данных по-прежнему остаются в передаче FIFO, а последовательный контроллер выходит из D0, чтобы ввести состояние устройства с низкой мощностью до передачи оставшихся байтов в FIFO, периферийный драйвер не будет знать, что эти байты потеряны.

Дополнительные сведения см. в разделе SerCx2 PIO-Transmit Транзакций.

Примеры

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

Например, чтобы определить функцию обратного вызова EvtSerCx2PioTransmitDrainFifo, которая называется MyPioTransmitDrainFifo, используйте тип функции EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO, как показано в этом примере кода:

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO  MyPioTransmitDrainFifo;

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

_Use_decl_annotations_
VOID
  MyPioTransmitDrainFifo(
    SERCX2PIOTRANSMIT  PioTransmit
    )
  {...}

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.1.
целевая платформа	Настольный
заголовка	sercx.h
IRQL	Вызывается в IRQL <= DISPATCH_LEVEL.