EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER回调函数 (sercx.h)

项目
02/29/2024

串行框架扩展的版本 2 (SerCx2) 调用 EvtSerCxx2PioTransmitWriteBuffer 事件回调函数，以使用编程的 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 的数据字节数。

注解

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

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的 EvtSerCx2PioTransmitWriteBuffer 回调函数，请使用 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的详细信息，请参阅批注函数行为。