HW_BUILDIO回调函数 (storport.h)

项目
02/26/2024

HwStorBuildIo 例程在将 SRB 传递给 HwStorStartIo 之前，先对共享系统数据结构进行非同步访问。

语法

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

参数

DeviceExtension

指向微型端口驱动程序的每个 HBA 存储区域的指针。

Srb

指向 SCSI 请求块的指针 (要处理的 SRB) 。

返回值

HwStorBuildIo 返回 TRUE 以通知调用方，如果 StorPort 认为 LUN 已准备好接收 I/O，则 StorPort 应调用 HwStorStartIo 例程。 HwStorBuildIo 返回 FALSE 以通知调用方不应将 SRB 传递给 HwStorStartIo。在这种情况下，微型端口驱动程序必须通过使用通知类型 RequestComplete 调用 StorPortNotification 来完成 SRB。只要 SRB 在 SRB 结构的 TimeOutValue 字段中指定的超时之前完成，就可以在 HwStorBuildIo 或微型端口驱动程序中的其他位置完成此操作。

注解

名称 HwStorBuildIo 只是HW_INITIALIZATION_DATA结构中 HwBuildIo 成员指向的微型端口函数的占位符。此例程的实际原型在 Storport.h 中定义，如下所示：

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

端口驱动程序在 DISPATCH IRQL 中调用 HwStorBuildIo 例程，而无需保留任何旋转锁。因此，HwStorBuildIo 中允许使用 StorPortAllocatePool 的内存分配和通过 StorPortAcquireSpinLock 相互排除。在多处理器环境中，一次可以有多个 HwStorBuildIo 处于活动状态，因此需要微型端口驱动程序来同步对系统资源的访问，如果 HwStorBuildIo 的多个实例在任何给定时间处于活动状态，则系统资源可能会发生争用。

通过完成 HwStorBuildIo 而不是 HwStorStartIo 中耗时的 I/O 设置活动，微型端口驱动程序可实现更高的 I/O 并发性，从而提高 I/O 吞吐量。为了获得最高性能，微型端口驱动程序应在 HwStorBuildIo 中执行尽可能多的预处理，以便它可以在尽可能短的时间内通过 HwStorStartIo 将请求发送到 HBA。预处理的数据和状态可以存储在 DeviceExtension 或 SrbExtension 结构中。只有对 DeviceExtension 的唯一部分进行修改，因为不会保留任何锁。 HwStorBuildIo 和 HwStorStartIo 接收以下 Srb 函数类型：

SRB_FUNCTION_EXECUTE_SCSI：将 CDB 发送到指定的总线/目标/lun。
- Srb-DataTransferLength> 对所有 Cdbs 有效。
- Srb-DataBuffer> 对于读取和写入请求为 NULL 。若要访问关联的数据，请使用 StorPortGetScatterGatherList (进行 Dma 传输) 或 StorPortGetSystemAddress (（用于程序控制的 I/O ) ）以获取散点收集列表或缓冲区的虚拟地址。对于其他请求，Srb-Databuffer> 指向与 Srb 关联的数据。
- Srb-PathId> 有效，表示在 StorPortNotification (BusChange) 中提供给 Storport 的 pathid。微型端口驱动程序的编写者需要使用 pathid 作为微型端口内总线表中的索引。
- Srb-TargetId> 和 Srb-Lun> 有效。
SRB_FUNCTION_IO_CONTROL：已定义微型端口。
- 如果请求者设置 Srb-DataTransferLength> 和 Srb-DataBuffer> 有效。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。
SRB_FUNCTION_RESET_LOGICAL_UNIT：如果设备支持) ， (重置指定的逻辑单元。
- Srb-DataTransferLength> 和 Srb-DataBuffer> 无效。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。
SRB_FUNCTION_RESET_DEVICE：重置指定的 Scsi 目标。
- Srb-DataTransferLength> 和 Srb-DataBuffer>、Srb-Lun> 无效。
- Srb-PathId> 和 Srb-TargetId> 有效。
SRB_FUNCTION_RESET_BUS：重置指定 SCSI 总线上的所有目标。
- 只有 Srb-PathId> 有效。
SRB_FUNCTION_FLUSH：指示微型端口驱动程序刷新所有缓存的数据。
- 仅当微型端口驱动程序在 PORT_CONFIGURATION_INFORMATION 结构中设置 CachesData == TRUE 时，才执行该驱动程序。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。
SRB_FUNCTION_SHUTDOWN：指示微型端口驱动程序刷新所有准备关闭的缓存数据。
- 仅当微型端口驱动程序在 PORT_CONFIGURATION_INFORMATION 结构中设置 CachesData == TRUE 时，才执行该驱动程序。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。
SRB_FUNCTION_DUMP_POINTERS：提供微型端口驱动程序支持故障转储和休眠所需的信息。
- 此请求将发送到 Storport 虚拟微型端口驱动程序，该驱动程序用于控制保存故障转储数据的磁盘。从Windows 8开始，非虚拟微型端口驱动程序可以选择性地接收此请求。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。
SRB_FUNCTION_FREE_DUMP_POINTERS：从Windows 8开始，此请求将发送到微型端口，以释放在SRB_FUNCTION_DUMP_POINTERS请求期间分配的资源。
- Srb-PathId>、Srb-TargetId> 和 Srb-Lun> 均有效。

从 Windows 8 开始，Srb 参数可能指向 SCSI_REQUEST_BLOCK 或 STORAGE_REQUEST_BLOCK。如果 Srb 的“函数”字段中的函数标识符SRB_FUNCTION_STORAGE_REQUEST_BLOCK，则 SRB 是STORAGE_REQUEST_BLOCK请求结构。

有关在此微型端口驱动程序例程中可以和不能安全地执行哪些操作的详细信息，请参阅未同步的 HwStorBuildIo 例程。

示例

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

例如，若要定义名为 MyHwBuildIo 的 HwStorBuildIo 回调例程，请使用 HW_BUILDIO 类型，如以下代码示例所示：

HW_BUILDIO MyHwBuildIo;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

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