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

Статья
10/30/2024

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

Синтаксис

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Параметры

[in] PioReceive

Дескриптор SERCX2PIORECEIVE объекту piO-receive. Драйвер последовательного контроллера ранее вызывал метод SerCx2PioReceiveCreate для создания этого объекта.

[out] Buffer

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

[in] Length

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

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

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

Замечания

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

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

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

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

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

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

Если драйвер реализует функцию EvtSerCx2PioReceiveInitializeTransaction, SerCx2 вызывает эту функцию в начале транзакции передачи PIO перед первым вызовом функции EvtSerCx2PioReceiveReadBuffer. Если драйвер реализует функцию EvtSerCx2PioReceiveCleanupTransaction, SerCx2 вызывает эту функцию в конце транзакции получения PIO, после окончательного вызова функции EvtSerCx2PioReceiveReadBuffer.

Помимо вызова функции EvtSerCx2PioReceiveReadBuff er во время транзакций получения PIO-receive, SerCx2 вызывает эту функцию, чтобы сохранить состояние получения FIFO непосредственно перед выходом из состояния питания устройства D0. Дополнительные сведения см. в SerCx2SaveReceiveFifoOnD0Exit.

Дополнительные сведения о транзакциях получения piO см. в SerCx2 PIO-Receive транзакций.

Примеры

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

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

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

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

Требования

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