HW_BUILDIO回调函数 (storport.h)

项目
05/23/2024

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

语法

HW_BUILDIO HwBuildio;

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

参数

DeviceExtension

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

Srb

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

返回值

如果 StorPort 认为 LUN 已准备好接收 I/O，则 HwStorBuildIo 返回 TRUE 以通知调用方 StorPort 应调用 HwStorStartIo 例程。 HwStorBuildIo 返回 FALSE 以通知调用方不应将 SRB 传递给 HwStorStartIo。在这种情况下，微型端口驱动程序必须通过使用通知类型 RequestComplete 调用 StorPortNotification 来完成 SRB。只要在 SRB 结构的 TimeOutValue 字段中指定的超时之前完成 SRB，就可以在 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 的 Function 字段中的函数标识符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的信息，请参阅批注函数行为。