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

Статья
10/30/2024

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

Синтаксис

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

Параметры

[in] PioTransmit

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

[in] Buffer

Указатель на буфер записи. Этот параметр является виртуальным адресом заблокированного буфера в системной памяти.

[in] Length

Количество байтов в буфере записи, доступное для передачи.

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

Функция EvtSerCx2PioTransmitWriteBuffer возвращает количество байтов данных, которые он успешно передает из буфера записи на передачу FIFO в оборудовании последовательного контроллера.

Замечания

Драйвер последовательного контроллера должен реализовать эту функцию. Драйвер регистрирует функцию в вызове SerCx2PioTransmitCreate, который создает объект piO-передачи.

SerCx2 может вызывать функцию EvtSerCx2PioTransmitWriteBuff er несколько раз во время транзакции передачи PIO. Один вызов EvtSerCx2PioTransmitWriteBuffer достаточно, если этот вызов может передать полное содержимое буфера записи на передачу FIFO. В противном случае SerCx2 продолжает вызывать эту функцию, так как больше места становится доступным в передаче FIFO, пока буфер записи не очищен.

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

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

Для каждого последовательного вызова функции EvtSerCx2PioTransmitWriteBuffer SerCx2 настраивает буфера, чтобы указать оставшиеся данные в буфере и задать длину число байт данных, оставшихся в буфере.

Готовое уведомление никогда не включено, если SerCx2 вызывает функцию EvtSerCx2PioTransmitEnableReadyNotification. Однако SerCx2 может вызывать эту функцию из того же потока, из которого драйвер вызвал метод SerCx2PioTransmitReady.

Если драйвер реализует функцию EvtSerCx2PioTransmitInitializeTransaction, SerCx2 вызывает эту функцию в начале транзакции передачи PIO перед первым вызовом функции EvtSerCx2PioTransmitWriteBuffer. Если драйвер реализует функцию EvtSerCx2PioTransmitCleanupTransaction, SerCx2 вызывает эту функцию в конце транзакции передачи PIO, после последнего вызова EvtSerCx2PioTransmitWriteBuffer, и после вызовов EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifoи EvtSerCx2PioTransmitPurgeFifo, если они реализованы.

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

Примеры

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

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

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

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

Требования

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