EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO回调函数（sercx.h）

项目
10/30/2024

EvtSerCx2PioTransmitPurgeFifo 事件回调函数由串行框架扩展（SerCx2）版本 2 调用，以放弃串行控制器中传输 FIFO 中保留的任何未发送数据的字节。

语法

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO EvtSercx2PioTransmitPurgeFifo;

void EvtSercx2PioTransmitPurgeFifo(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] ULONG BytesAlreadyTransmittedToHardware
)
{...}

参数

[in] PioTransmit

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

[in] BytesAlreadyTransmittedToHardware

当前 PIO 传输事务期间已加载到传输 FIFO 中的字节数。此参数是以前调用 EvtSerCx2PioTransmitWriteBuffer 属于此事务的事件回调函数的所有字节的总和。

返回值

没有

言论

串行控制器驱动程序可以根据需要实现此函数。如果实现，驱动程序会在 SerCx2PioTransmitCreate 调用中注册该函数，该调用将创建 PIO 传输对象。

如果串行控制器具有硬件 FIFO（或类似缓冲机制）来保存传输数据，驱动程序应实现 EvtSerCx2PioTransmitPurgeFifo 函数。如果驱动程序实现此函数，则它还必须实现 EvtSerCx2PioTransmitDrainFifo 和 EvtSerCx2PioTransmitCancelDrainFifo 事件回调函数。

SerCx2 启动 PIO 传输事务，以响应来自客户端的写入（IRP_MJ_WRITE）请求。如果此请求在完成之前超时或取消，则 SerCx2 调用 EvtSerCx2PioTransmitPurgeFifo 函数（如果已实现），以清除可能保留传输 FIFO 的任何未发送数据。

清除传输 FIFO 后，EvtSerCx2PioTransmitPurgeFifo 函数必须调用 SerCx2PioTransmitPurgeFifoComplete 方法，以通知 SerCx2 已清除 FIFO，然后 SerCx2 完成写入请求。

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

例子

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

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

EVT_SERCX2_PIO_TRANSMIT_PURGE_FIFO  MyPioTransmitPurgeFifo;

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

_Use_decl_annotations_
VOID
  MyPioTransmitPurgeFifo(
    SERCX2PIOTRANSMIT  PioTransmit,
    ULONG  BytesAlreadyTransmittedToHardware

    )
  {...}

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