EVT_SERCX2_PIO_RECEIVE_ENABLE_READY_NOTIFICATION回调函数 (sercx.h)

项目
02/26/2024

串行框架扩展版本 2 (SerCx2) 调用 EvtSerCx2PioReceiveEnableReadyNotification 事件回调函数，使串行控制器驱动程序能够在串行控制器收到新数据时通知 SerCx2。

语法

EVT_SERCX2_PIO_RECEIVE_ENABLE_READY_NOTIFICATION EvtSercx2PioReceiveEnableReadyNotification;

void EvtSercx2PioReceiveEnableReadyNotification(
  [in] SERCX2PIORECEIVE PioReceive
)
{...}

参数

[in] PioReceive

PIO 接收对象的 SERCX2PIORECEIVE 句柄。串行控制器驱动程序以前调用 SerCx2PioReceiveCreate 方法来创建此对象。

返回值

无

备注

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

调用 EvtSerCx2PioReceiveEnableReadyNotification 函数以启用 PIO 接收事务的就绪通知后，串行控制器驱动程序必须调用 SerCx2PioReceiveReady 方法，以便在驱动程序检测到一个或多个数据字节可供从串行控制器硬件中的接收 FIFO 读取时通知 SerCx2。如果启用就绪通知后，接收 FIFO 中的数据已可用，驱动程序会立即调用此方法来通知 SerCx2。

PIO 接收事务的就绪通知是一次性通知。向 SerCx2 发送就绪通知后，在 SerCx2 调用 EvtSerCx2PioReceiveEnableReadyNotification 函数以启用另一个通知之前，串行控制器驱动程序不会发送进一步的通知。

EvtSerCx2PioReceiveReadBuffer 事件回调函数调用可能仅部分完成 PIO 接收事务，因为无法立即从接收 FIFO 读取更多数据。在这种情况下，SerCx2 调用 EvtSerCx2PioReceiveEnableReadyNotification 函数以启用就绪通知，在这种情况下，当接收 FIFO 包含更多数据时，串行控制器驱动程序必须通知 SerCx2。为了响应此通知，SerCx2 通过再次调用 EvtSerCx2PioReceiveReadBuffer 函数来恢复部分完成的接收事务。

通常， EvtSerCx2PioReceiveEnableReadyNotification 函数支持在串行控制器具有更多可供读取的数据时发生的中断。为了响应此中断，串行控制器驱动程序调用 SerCx2PioReceiveReady。

一次不能有一个以上的就绪通知处于挂起状态。在 SerCx2 调用 EvtSerCx2PioReceiveEnableReadyNotification 函数以启用就绪通知后，在控制器驱动程序调用 SerCx2PioReceiveReady 之前，SerCx2 不会再次调用此函数。

启用就绪通知时，SerCx2 从不调用 EvtSerCx2PioReceiveReadBuffer 函数。

如果关联的读取请求超时或已取消，则可以取消挂起的就绪通知。若要取消 PIO 接收事务的就绪通知，SerCx2 调用 EvtSerCx2PioReceiveCancelReadyNotification 事件回调函数。

SerCx2 使用就绪通知有效地管理在处理作为 PIO 接收事务处理的读取请求期间发生的间隔超时。

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

示例

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

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

EVT_SERCX2_PIO_RECEIVE_ENABLE_READY_NOTIFICATION  MyPioReceiveEnableReadyNotification;

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

_Use_decl_annotations_
VOID
  MyPioReceiveEnableReadyNotification(
    SERCX2PIORECEIVE  PioReceive
    )
  {...}

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