EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER回调函数（sercx.h）

项目
10/30/2024

EvtSerCx2PioTransmitWriteBuffer 事件回调函数由串行框架扩展版本 2 调用，以使用编程 I/O （PIO）将写入缓冲区的内容传输到串行控制器中的传输 FIFO。

语法

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

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

参数

[in] PioTransmit

PIO 传输对象的 SERCX2PIOTRANSMIT 句柄。串行控制器驱动程序以前调用 SerCx2PioTransmitCreate 方法来创建此对象。

[in] Buffer

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

[in] Length

写入缓冲区中可供传输的字节数。

返回值

EvtSerCx2PioTransmitWriteBuffer 函数返回成功从写入缓冲区传输到串行控制器硬件中的传输 FIFO 的数据字节数。

言论

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

SerCx2 可能会在 PIO 传输事务期间多次调用 EvtSerCx2PioTransmitWriteBuffer 函数。如果此调用可以将写入缓冲区的完整内容传输到传输 FIFO，则单个 EvtSerCx2PioTransmitWriteBuffer 调用就足够了。否则，SerCx2 将继续调用此函数，因为传输 FIFO 中可用的空间越多，直到写入缓冲区清空为止。

从写入缓冲区中的第一个字节开始，EvtSerCx2PioTransmitWriteBuffer 函数使用 PIO 将尽可能多的字节从缓冲区传输到传输 FIFO。只要缓冲区不为空，函数将继续从缓冲区传输数据，行状态寄存器（LSR）表示 FIFO 可以接受更多数据。如果 LSR 指示 FIFO 不能再接受任何数据，该函数将返回而不清缓冲区。否则，该函数将传输缓冲区中的所有字节并返回。在任一情况下，此函数返回的值都是成功从写入缓冲区传输到传输 FIFO 的数据字节数。

通常，EvtSerCx2PioTransmitWriteBuffer 函数不会启用任何中断。相反，如果函数无法将写入缓冲区的全部内容传输到传输 FIFO，则 SerCx2 会调用 EvtSerCx2PioTransmitEnableReadyNotification 事件回调函数来启用就绪通知，并且此函数启用传输 FIFO 变为空时发生的中断。

对于对 EvtSerCx2PioTransmitWriteBuffer 函数的每个连续调用，SerCx2 将 Buffer 调整为指向缓冲区中的剩余数据，并将 Length 设置为缓冲区中剩余的数据字节数。

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

如果驱动程序实现 EvtSerCx2PioTransmitInitializeTransaction 函数，则 SerCx2 在 PIO 传输事务的开头调用此函数，然后再调用 EvtSerCx2PioTransmitWriteBuffer 函数。如果驱动程序实现 EvtSerCx2PioTransmitCleanupTransaction 函数，则 SerCx2 会在 PIO 传输事务的末尾调用此函数，在最后一 EvtSerCx2PioTransmitWriteBuffer 调用之后，在对 EvtSerCx2PioTransmitDrainFifo、EvtSerCx2PioTransmitCancelDrainFifo和 EvtSerCx2PioTransmitPurgeFifo 函数的任何调用之后（如果实现）。

有关 PIO 传输事务的详细信息，请参阅 SerCx2 PIO-Transmit 事务。

例子

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

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