EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO回调函数（sercx.h）

项目
10/30/2024

EvtSerCx2PioTransmitDrainFifo 事件回调函数由串行框架扩展版本 2 （SerCx2）调用，以耗尽串行控制器硬件中的传输 FIFO。

语法

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO EvtSercx2PioTransmitDrainFifo;

void EvtSercx2PioTransmitDrainFifo(
  [in] SERCX2PIOTRANSMIT PioTransmit
)
{...}

参数

[in] PioTransmit

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

返回值

没有

言论

串行控制器驱动程序可以根据需要实现此函数。如果驱动程序实现此函数，则它还必须实现 EvtSerCx2PioTransmitCancelDrainFifo 和 EvtSerCx2PioTransmitPurgeFifo 事件回调函数。实现这些函数的驱动程序在创建 PIO 传输对象的 SerCx2PioTransmitCreate 调用中注册它们。

SerCx2 调用 EvtSerCx2PioTransmitDrainFifo 函数（如果实现），以在 PIO 传输事务结束时在串行控制器硬件中清空传输 FIFO。此函数可确保传输 FIFO 中保留的任何数据字节都传输到串行连接的外围设备。从 FIFO 传输最后一个字节后，EvtSerCx2PioTransmitDrainFifo 函数调用 SerCx2PioTransmitDrainFifoComplete 方法来通知 SerCx2。

如果串行控制器驱动程序实现 EvtSerCx2PioTransmitDrainFifo 函数，则在驱动程序调用 SerCx2PioTransmitDrainFifoComplete之前，SerCx2 不会完成挂起的写入（IRP_MJ_WRITE）请求。

如果串行控制器具有用于保存传输数据的硬件 FIFO（或类似缓冲机制），驱动程序应实现 EvtSerCx2PioTransmitDrainFifo 函数。否则，SerCx2 无法确认传输 FIFO 在完成挂起的写入请求之前已清空。相反，SerCx2 在写入缓冲区中的最后一个字节写入传输 FIFO 后完成此请求。不能保证写入到传输 FIFO 的数据将传输，而不会造成重大延迟。写入请求完成后保留在 FIFO 中的任何数据都可能会丢失，然后才能将其传输到串行连接的外围设备。在成功完成的写入请求中，这种意外的数据丢失可能会给外围驱动程序造成可靠性问题。

例如，外围设备可能会将写入请求发送到外围设备连接到的串行端口。在完成所有未完成的写入请求之前，此驱动程序应延迟发送 IOCTL 以更改串行端口传输数据的波特率。但是，如果未实现任何 EvtSerCx2PioTransmitDrainFifo 函数，则传输 100 字节数据的写入请求可能已完成，而 50 个数据字节仍保留在传输 FIFO 中。如果外围驱动程序随后发送 IOCTL 以设置新的波特率，则 FIFO 中的一些剩余字节可能以新的波特率传输，从而导致错误。

同样，如果写入请求传输 100 字节的数据已完成，而 50 个数据字节仍保留在传输 FIFO 中，并且串行控制器退出 D0 以进入低功率设备状态，然后 FIFO 中的剩余字节可以传输，外围驱动程序将不知道这些字节丢失。

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

例子

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

例如，若要定义名为的 MyPioTransmitDrainFifo 回调函数，请使用 EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO 函数类型，如以下代码示例所示：

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO  MyPioTransmitDrainFifo;

然后，按如下所示实现回调函数：

_Use_decl_annotations_
VOID
  MyPioTransmitDrainFifo(
    SERCX2PIOTRANSMIT  PioTransmit
    )
  {...}

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO 函数类型在 Sercx.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations 批注可确保使用应用于头文件中 EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO 函数类型的批注。有关函数声明要求的详细信息，请参阅使用 KMDF 驱动程序的函数角色类型声明函数。有关 Use_decl_annotations的详细信息，请参阅批注函数行为。