通过

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER回调函数 （sercx.h）

  • 项目

EvtSerCx2PioReceiveReadBuffer 事件回调函数由串行框架扩展版本 2 调用，以使用编程 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 接收对象的 SerCx2PioReceiveCreate 调用中注册函数。

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

EvtSerCx2PioReceiveReadBuffer 函数使用 PIO 将尽可能多的字节从接收 FIFO 传输到读取缓冲区。 只要传递给此函数的缓冲区未满，函数将继续从 FIFO 传输数据，并且行状态寄存器（LSR）指示 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 回调函数，请使用 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。

另请参阅

EvtSerCx2PioReceiveCleanupTransaction

EvtSerCx2PioReceiveEnableReadyNotification

EvtSerCx2PioReceiveInitializeTransaction

SERCX2PIORECEIVE

SerCx2PioReceiveCreate