EVT_SERCX2_PIO_RECEIVE_READ_BUFFER回调函数 (sercx.h)

项目
02/26/2024

串行框架扩展版本 2 (SerCx2) 调用 EvtSerCx2PioReceiveReadBuffer 事件回调函数，以使用编程的 I/O (PIO) 将数据从串行控制器中的接收 FIFO 传输到读取缓冲区。

语法

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

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

参数

[in] PioReceive

PIO 接收对象的 SERCX2PIORECEIVE 句柄。串行控制器驱动程序以前调用 SerCx2PioReceiveCreate 方法来创建此对象。

[out] Buffer

指向读取缓冲区的指针。此参数是系统内存中锁定缓冲区的虚拟地址。

[in] Length

读取缓冲区中可用于存储接收数据的字节数。

返回值

EvtSerCx2PioReceiveReadBuffer 函数返回它成功从串行控制器硬件中的接收 FIFO 传输到读取缓冲区的数据字节数。

注解

串行控制器驱动程序必须实现此函数。驱动程序在创建 PIO-receive 对象的 SerCx2PioReceiveCreate 调用中注册函数。

SerCx2 可能会在 PIO 接收事务期间多次调用 EvtSerCx2PioReceiveReadBuffer 函数。如果此调用可以使用来自接收 FIFO 的数据填充读取缓冲区，则单个 EvtSerCx2PioReceiveReadBuffer 调用就足够了。否则，SerCx2 将继续调用此函数，因为接收 FIFO 中有更多数据可用，直到读取缓冲区被填充。

EvtSerCx2PioReceiveReadBuffer 函数使用 PIO 将尽可能多的字节从接收 FIFO 传输到读取缓冲区。只要传递给此函数的缓冲区未满，并且 LSR () 行状态寄存器指示 FIFO 中提供了更多数据，函数将继续从 FIFO 传输数据。如果 LSR 指示 FIFO 为空，则函数返回而不填充缓冲区。否则，函数将填充缓冲区并返回。在任一情况下，此函数返回的值都是从接收 FIFO 成功传输到读取缓冲区的数据字节数。

通常， EvtSerCx2PioReceiveReadBuffer 函数不启用任何中断。相反，如果接收 FIFO 在函数可以填充读取缓冲区之前用完数据，SerCx2 会调用 EvtSerCx2PioReceiveEnableReadyNotification 事件回调函数来启用就绪通知，并且此函数支持在接收 FIFO 中提供更多数据时发生的中断。

对于对 EvtSerCx2PioReceiveReadBuffer 函数的连续调用，SerCx2 会将 Buffer 调整为指向要填充的下一个缓冲区区域，并将 Length 设置为缓冲区中剩余的未填充空间的字节数。

当 SerCx2 调用 EvtSerCx2PioReceiveEnableReadyNotification 函数时，永远不会启用就绪通知。但是，SerCx2 可能从驱动程序调用 SerCx2PioReceiveReady 方法的同一线程调用此函数。

如果驱动程序实现 EvtSerCx2PioReceiveInitializeTransaction 函数，则 SerCx2 在 PIO 传输事务开始时调用此函数，然后再首次调用 EvtSerCx2PioReceiveReadBuffer 函数。如果驱动程序实现 EvtSerCx2PioReceiveCleanupTransaction 函数，则 SerCx2 在 PIO 接收事务结束时调用此函数，最后调用 EvtSerCx2PioReceiveReadBuffer 函数之后。

除了在 PIO 接收事务期间调用 EvtSerCx2PioReceiveReadBuffer 函数外，SerCx2 还调用此函数，以在串行控制器退出 D0 设备电源状态之前保存接收 FIFO 的状态。有关详细信息，请参阅 SerCx2SaveReceiveFifoOnD0Exit。

有关 PIO 接收事务的详细信息，请参阅 SerCx2 PIO-Receive 事务。

示例

若要定义 EvtSerCx2PioReceiveReadBuffer 回调函数，必须先提供一个函数声明来标识要定义的回调函数的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

例如，若要定义名为 MyPioReceiveReadBuffer的 EvtSerCx2PioReceiveReadBuffer 回调函数，请使用 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的详细信息，请参阅批注函数行为。