通过

EVT_SPB_CONTROLLER_SEQUENCE回调函数 (spbcx.h)

  • 项目

SPB 控制器驱动程序的 EvtSpbControllerIoSequence 事件回调函数在指定目标设备和随序列请求提供的缓冲区之间执行一系列数据传输。

语法

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

参数

[in] Controller

表示 SPB 控制器的 框架设备对象的 WDFDEVICE 句柄。

[in] Target

此 I/O 请求的目标的 SPBTARGET 句柄。 目标是连接到总线的外围设备或端口。 SPB 框架扩展 (SpbCx) 以前将此句柄分配给了打开与目标的连接的 EvtSpbTargetConnect 回调中的目标。

[in] Request

I/O 请求的 SPBREQUEST 句柄。 SPB 控制器驱动程序必须通过执行请求的操作或返回错误状态来完成此请求。 有关更多信息，请参见备注。

[in] TransferCount

此 I/O 传输序列中的单个传输数。 每个单独的传输都是一个简单的读取或写入操作。

返回值

无

备注

SpbCx 管理 SPB 控制器的 I/O 队列。 当 SPB 控制器的客户端 (外设驱动程序) 向附加到总线的目标设备发送IOCTL_SPB_EXECUTE_SEQUENCE请求时，SpbCx 调用 SPB 控制器驱动程序的 EvtSpbControllerIoSequence 回调函数。 Request 参数值是封装此请求的句柄。

EvtSpbControllerIoSequence 回调不返回状态值。 相反，SPB 控制器驱动程序指示 I/O 请求的完成状态中的序列操作的状态。

EvtSpbControllerIoSequence 回调是异步的。 也就是说，回调函数应启动请求的序列 (或序列) 操作的第一部分，然后返回而不等待操作完成。 稍后，SPB 控制器驱动程序继续处理请求或在中断 DPC 或计时器 DPC 期间完成请求。

SPB 控制器驱动程序可以从 I/O 请求中检索参数值，以确定序列中传输的最大长度。 驱动程序可以使用此长度分配 DMA 资源，可在序列中的每个传输中重复使用这些资源。

SPB 控制器驱动程序可以调用 SpbRequestGetTransferParameters 方法，以检索序列中每次传输的控制参数和数据缓冲区。 缓冲区是 WDFMEMORY 对象，在当前实现中封装链接 MDL。 有关链接的 MDL 的详细信息，请参阅 使用 MDL。

SPB 控制器应为整个序列操作选择目标设备。 如果目标由设备选择行选择，则可以从序列中的第一个传输开始到最后一个传输结束为止连续断言该行。 此行最早可以断言为序列开头的锁定操作，并且可以一直断言到序列末尾的解锁操作。

可以为序列中的每个传输指定可选延迟。 SPB 控制器驱动程序负责在开始传输之前至少延迟该微秒数。 如果序列中的第一次传输具有关联的延迟，则驱动程序应首先传输地址或断言目标设备的设备选择行，然后在开始数据传输之前延迟指定时间。 在此延迟期间，目标应保持选中状态，但控制器不应在总线上运行时钟。

如果目标设备在序列中的传输期间发出 NACK 信号，SPB 控制器将停止该序列。 (也就是说，控制器不会重试失败的传输，也不会尝试执行序列中的剩余传输。) 如果发生这种情况，SPB 控制器驱动程序应将 I/O 请求的完成状态设置为STATUS_SUCCESS，将 I/O 状态块中的 “信息” 字段设置为实际传输的字节数， (不计算在接收 NACK) 的传输中丢失的数据， 并完成请求。

仅当出现以下情况之一时，SPB 控制器驱动程序才应使用错误状态代码完成 I/O 请求：

  • SPB 控制器无法 (选择目标设备，例如，当控制器) 传输地址字节时，I2C 总线上的目标设备会向 NACK 发出信号。
  • SPB 控制器驱动程序在处理序列操作时从调用 WDF 或 WDM 服务获取错误状态。

若要注册 EvtSpbControllerIoSequence 回调函数，请调用 SpbDeviceInitialize 方法。

示例

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

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

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

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

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

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

要求

要求 值
最低受支持的客户端 支持从Windows 8开始。
目标平台 桌面
标头 spbcx.h
IRQL 在 IRQL <= DISPATCH_LEVEL 调用。

另请参阅