HW_STARTIO回调函数 (storport.h)

项目
02/29/2024

Storport 驱动程序为每个传入的 I/O 请求调用 一次 HwStorStartIo 例程。

语法

HW_STARTIO HwStartio;

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

参数

DeviceExtension

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

Srb

指向要启动的 SCSI 请求块的指针。

返回值

如果请求已成功启动，则 HwStorStartIo 返回 TRUE。否则，它将返回 FALSE。

注解

HwStorStartIo 启动 I/O 操作。 StorPort 旨在使用在 HwStorBuildIo 中准备并存储在 DeviceExtension 或 Srb-SrbExtension> 中的微型端口专用数据。由于在不使用旋转锁的情况下调用 HwStorBuildIo ，因此可以通过在 HwStorBuildIo 中准备尽可能多的数据来实现最佳驱动程序性能。

Storport 通过以下方式调用 HwStorStartIo ：

对于存储非虚拟微型端口驱动程序，根据 PORT_CONFIGURATION_INFORMATION 中设置的 SynchronizationModel 值，Storport 始终在同一 IRQL 中调用 HwStorStartIo，并使用内部旋转锁来确保按顺序启动 I/O 请求。 IRQL 是DISPATCH_LEVEL (全双工模式) 或 DIRQL (半双工模式) 。

在半双工模式下处理 I/O 时， HwStorStartIo 例程不必获取自己的旋转锁。此外，HwStorStartIo 例程中不允许使用 StorPortAllocatePool 的内存分配和通过 StorPortAcquireSpinLock 相互排除。在全双工模式下，可以在 HwStorStartIo 例程中使用 StorPortAllocatePool 和 StorPortAcquireSpinLock。

如果非虚拟微型端口支持 StorPortInitializePerfOpts) 设置的并发通道优化 (STOR_PERF_CONCURRENT_CHANNELS，则可能会同时多次调用 HwStorStartIo 。在这种情况下，微型端口需要确保任何共享资源都受锁的保护。通过此性能优化，Storport 在调用 HwStorStartIo 之前不会获取 StartIo 锁，并且微型端口必须根据需要提供自己的锁。
对于存储虚拟微型端口驱动程序，Storport 在任意 IRQL <= DISPATCH_LEVEL调用 HwStorStartIo，并且不使用内部旋转锁。 HwStorStartIo 例程可以通过调用 StorPortAcquireSpinLock 获取自己的旋转锁。此外，在存储虚拟微型端口驱动程序的 HwStorStartIo 例程中，允许调用 StorPortAllocatePool。

收到 SCSI 状态时，应完成 SRB。当 Storport 驱动程序使用 RequestComplete的 NotificationType 调用 StorPortNotification 完成 SRB 时，SRB 应在 Srb 的 SrbStatus 字段中返回以下值之一：

SRB_STATUS_SUCCESS
- 指示已发送 Srb，SCSI 状态 (可能返回数据) 。
- Storport 将数据和状态返回给调用方。
- 微型端口操作不是，除了使用 StorPortNotification for RequestComplete（可能来自 HwStorDpcRoutine）来完成请求。
SRB_STATUS_BUSY
- 指示发送 Srb (存在暂时性问题，例如，适配器寄存器或缓冲区) 繁忙。
- Storport 放弃 Srb-SrbExtension> 指向的原始 Srb 扩展，并颁发新扩展。 Storport 在后续调用 HwStorBuildIo 和 HwStorStartIo 时，将原始 Srb 与新颁发的 Srb 扩展一起发送。原始 Srb 扩展中的所有数据都将丢失。
- 微型端口不应更新 Srb 的 DataTransferLength。
- 由于颁发了新的 Srb 扩展，因此微型端口必须确保它永远不会在 SCSI 事务中间发出SRB_STATUS_BUSY。事务启动后，必须完成或取消该事务。事务期间的硬件繁忙状态必须由微型端口驱动程序处理。

名称 HwStorStartIo 是一个占位符，用于描述 HW_INITIALIZATION_DATA 结构的 HwStartIo 成员中设置的微型端口例程。此结构在 StorPortInitialize 的 HwInitializationData 参数中传递。此例程的实际原型在 Storport.h 中定义，如下所示：

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

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

示例

若要定义 HwStorStartIo 回调例程，必须先提供静态驱动程序验证程序 (SDV) 和其他验证工具所需的函数声明，如以下代码示例所示：

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

例如，若要定义名为 MyHwStartIo 的 HwStorStartIo 回调例程，请使用 HW_STARTIO 类型并实现回调例程，如下所示：

HW_STARTIO MyHwStartIo

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

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