IOCTL_SCSI_MINIPORT_HYBRID IOCTL （ntddscsi.h）

發行項
02/07/2025

IOCTL_SCSI_MINIPORT_HYBRID 控件程式代碼會將混合式磁碟控制要求傳送至 HBA 特定的迷你埠驅動程式。 IOCTL_SCSI_MINIPORT_HYBRID 要求是 IOCTL_SCSI_MINIPORT的子 IOCTL。 StorPort 會接收並重新格式化此 IOCTL，然後以函式類型為 SRB_FUNCTION_IO_CONTROL 的 STORAGE_REQUEST_BLOCK （SRB）傳送至迷你埠。輸入和輸出數據包含在 SRB 數據區塊中。

IOCTL_SCSI_MINIPORT_HYBRID 適用於第三方應用程式或篩選磁碟驅動器，這些磁碟驅動器會管理加密或寫入行為等安全性功能。

警告使用 IOCTL_SCSI_MINIPORT_HYBRID 修改混合式快取行為將會與 Windows 系統元件的作業衝突，且不受支援。

注意 SCSI 連接埠驅動程式和 SCSI 迷你埠驅動程式模型未來可能會改變或無法使用。相反地，我們建議使用 Storport 驅動程式和 Storport miniport 驅動程式模型。

主要程序代碼

IRP_MJ_DEVICE_CONTROL

輸入緩衝區

SRB DataBuffer 成員中指定的緩衝區必須包含 SRB_IO_CONTROL 結構和 HYBRID_REQUEST_BLOCK 結構。根據 HYBRID_REQUEST_BLOCK函式成員而定，可以提供其他數據。

輸入緩衝區長度

DataTransferLength 表示緩衝區的大小，其大小至少必須是 sizeof （SRB_IO_CONTROL） + sizeof（HYBRID_REQUEST_BLOCK），如果 DataBufferLengthHYBRID_REQUEST_BLOCK 成員為非零，則為函式數據的額外記憶體。

輸出緩衝區

更新 SRB_IO_CONTROL 結構會傳回 SRB 中的數據緩衝區。

輸出緩衝區長度

DataBufferOffset 和 DataBufferLength 成員 HYBRID_REQUEST_BLOCK 為非零值，當指定之函式傳回數據時。當要求函式傳回數據時，會更新 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 結構之後。在 SRB_IO_CONTROL 結構開頭之後，DataBufferOffset 的位移中找到要求中包含的任何函式數據。

下列範例示範如何擷取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。
大小: 結構的大小。設定為 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。
大小: 結構的大小。設定為 sizeof（HYBRID_DEMOTE_BY_SIZE）。
SourcePriority: 要降級之數據的原始優先順序。此值必須 <= HYBRID_FUNCTION_GET_INFOMaximumHybridPriorityLevel 中HYBRID_INFORMATION 函式要求所傳回之 HYBRID_INFORMATION 結構成員中的值。此值必須 > 0。
TargetPriority: 要從 SourcePriority 層級降級的數據目標優先順序層級。此值必須 < SourcePriority。
Reserved0: 保留。
Reserved1: 保留。
LbaCount: 降級至新優先順序層級的 LBA 數目。