IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

项目
08/07/2023

IOCTL_SCSI_MINIPORT_HYBRID控制代码将混合磁盘控制请求发送到特定于 HBA 的微型端口驱动程序。 IOCTL_SCSI_MINIPORT_HYBRID请求是IOCTL_SCSI_MINIPORT的子 IOCTL。此 IOCTL 由 StorPort 接收并重新格式化，然后作为函数类型为 SRB_FUNCTION_IO_CONTROL (SRB) STORAGE_REQUEST_BLOCK发送到微型端口。输入和输出数据包含在 SRB 数据块中。

IOCTL_SCSI_MINIPORT_HYBRID 适用于管理安全功能（如加密或写通行为）的第三方应用程序或筛选器驱动器。

警告使用 IOCTL_SCSI_MINIPORT_HYBRID 修改混合缓存行为将与 Windows 系统组件的操作冲突，并且不受支持。

注意 SCSI 端口驱动程序和 SCSI 微型端口驱动程序模型将来可能会更改或不可用。相反，我们建议使用 Storport 驱动程序和 Storport 微型端口驱动程序模型。

主要代码

IRP_MJ_DEVICE_CONTROL

输入缓冲区

在 SRB 的 DataBuffer 成员中指定的缓冲区必须包含 SRB_IO_CONTROL 结构和 HYBRID_REQUEST_BLOCK 结构。根据 HYBRID_REQUEST_BLOCK 的 Function 成员，可以提供其他数据。

输入缓冲区长度

DataTransferLength 指示缓冲区的大小（以字节为单位），缓冲区的大小必须至少为 (SRB_IO_CONTROL) + sizeof (HYBRID_REQUEST_BLOCK) ，如果HYBRID_REQUEST_BLOCK的 DataBufferLength 成员为非零值，则函数数据的附加存储。

输出缓冲区

更新的SRB_IO_CONTROL 结构将返回到 SRB 中的数据缓冲区。

输出缓冲区长度

返回指定函数的数据时，HYBRID_REQUEST_BLOCK的 DataBufferOffset 和 DataBufferLength 成员为非零。为请求函数返回数据时，将更新 SRB 的 DataTransferLength 成员。

状态块

函数请求的结果状态在 SRB_IO_CONTROL 的 ReturnCode 成员中设置。下面是混合磁盘 IOCTL 状态代码。

返回代码	说明
HYBRID_STATUS_SUCCESS	函数已成功完成。
HYBRID_STATUS_ILLEGAL_REQUEST	请求包含无效的函数代码。
HYBRID_STATUS_INVALID_PARAMETER	输入或输出参数的格式不正确。
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL	DataBufferLength 中给出的数据长度太小，无法包含请求输出。

注解

HYBRID_REQUEST_BLOCK 结构紧跟在数据缓冲区中的 SRB_IO_CONTROL 结构之后。 HYBRID_REQUEST_BLOCK 在 ntddscsi.h 中定义如下。

typedef struct _HYBRID_REQUEST_BLOCK {
    ULONG   Version;
    ULONG   Size;
    ULONG   Function;
    ULONG   Flags;
    ULONG   DataBufferOffset;
    ULONG   DataBufferLength;
} HYBRID_REQUEST_BLOCK, *PHYBRID_REQUEST_BLOCK;

参数要求取决于混合磁盘请求的函数代码。下表列出了每个函数所需的参数。

函数	输入参数	输出参数
HYBRID_FUNCTION_GET_INFO	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK + HYBRID_INFORMATION
HYBRID_FUNCTION_DISABLE_CACHING_MEDIUM	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK	SRB_IO_CONTROL
HYBRID_FUNCTION_ENABLE_CACHING_MEDIUM	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK	SRB_IO_CONTROL
HYBRID_FUNCTION_SET_DIRTY_THRESHOLD	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK + HYBRID_DIRTY_THRESHOLDS	SRB_IO_CONTROL
HYBRID_FUNCTION_DEMOTE_BY_SIZE	SRB_IO_CONTROL + HYBRID_REQUEST_BLOCK + HYBRID_DEMOTE_BY_SIZE	SRB_IO_CONTROL

HYBRID_REQUEST_BLOCK 结构位于 SRB 的 DataBuffer 中的 SRB_IO_CONTROL 结构之后。请求中包含的任何函数数据都位于 dataBufferOffset 中 SRB_IO_CONTROL 结构开始后的偏移量处。

以下示例演示如何检索HYBRID_FUNCTION_SET_DIRTY_THRESHOLD请求的函数数据。

    PSRB_IO_CONTROL srbIoCtl = (PSRB_IO_CONTROL)srb->DataBuffer;
    PHYBRID_REQUEST_BLOCK hybridRequest = (PHYBRID_REQUEST_BLOCK)(srbIoCtl + 1);
    PHYBRID_DIRTY_THRESHOLDS hybridDirtyThresholds = NULL;

    if (hybridRequest->DataBufferOffset >= sizeof(SRB_IO_CONTROL) + sizeof(HYBRID_REQUEST_BLOCK))
    {
        if (hybridRequest->DataBufferLength >= sizeof(HYBRID_FUNCTION_SET_DIRTY_THRESHOLD))
        {
            hybridDirtyThresholds = (PHYBRID_DIRTY_THRESHOLDS)((PUCHAR)srbIoCtl + hybridRequest->DataBufferOffset);
        }
        else
        {
            srbIoCtl->ReturnCode = HYBRID_STATUS_INVALID_PARAMETER;
        }
    }

HYBRID_DIRTY_THRESHOLDS

HYBRID_FUNCTION_SET_DIRTY_THRESHOLD函数使用 HYBRID_DIRTY_THRESHOLDS 结构进行输入参数。 HYBRID_DIRTY_THRESHOLDS 在 ntddscsi.h 中定义如下。

typedef struct _HYBRID_DIRTY_THRESHOLDS {
    ULONG   Version;
    ULONG   Size;
    ULONG   DirtyLowThreshold;
    ULONG   DirtyHighThreshold;
} HYBRID_DIRTY_THRESHOLDS, *PHYBRID_DIRTY_THRESHOLDS;

版本: 结构的版本。设置为 HYBRID_REQUEST_INFO_STRUCTURE_VERSION。
Size: 结构的大小。将设置为 sizeof (HYBRID_DIRTY_THRESHOLDS) 。
DirtyLowThreshold: 要同步到磁盘的混合磁盘缓存的低小数阈值。
DirtyHighThreshold: 要同步到磁盘的混合磁盘缓存的小数部分高阈值。

DirtyLowThreshold 和 DirtyHighThreshold 的值表示为阈值与分数基之间的比率的较小部分。分数基数由HYBRID_INFORMATION结构的 FractionBase 成员决定。

HYBRID_DEMOTE_BY_SIZE

HYBRID_FUNCTION_DEMOTE_BY_SIZE函数使用 HYBRID_DEMOTE_BY_SIZE 结构进行输入参数。 HYBRID_DEMOTE_BY_SIZE 在 ntddscsi.h 中定义如下。

typedef struct _HYBRID_DEMOTE_BY_SIZE {
    ULONG       Version;
    ULONG       Size;
    UCHAR       SourcePriority;
    UCHAR       TargetPriority;
    USHORT      Reserved0;
    ULONG       Reserved1;
    ULONGLONG   LbaCount;
} HYBRID_DEMOTE_BY_SIZE, *PHYBRID_DEMOTE_BY_SIZE;

版本: 结构的版本。设置为 HYBRID_REQUEST_INFO_STRUCTURE_VERSION。
Size: 结构的大小。将设置为 sizeof (HYBRID_DEMOTE_BY_SIZE) 。
SourcePriority: 要降级的数据的原始优先级。此值必须 <= 从HYBRID_FUNCTION_GET_INFO函数请求返回的 HYBRID_INFORMATION 结构的 MaximumHybridPriorityLevel 成员中的值。此值必须 > 0。
TargetPriority: 要从 SourcePriority 级别降级的数据的目标优先级级别。此值必须为 < SourcePriority。
Reserved0: 保留。
Reserved1: 保留。
LbaCount: 要降级到新优先级的 LBA 数。