IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

發行項
02/29/2024

IOCTL_SCSI_MINIPORT_HYBRID控制程式代碼會將混合式磁碟控制要求傳送至 HBA 特定的迷你埠驅動程式。 IOCTL_SCSI_MINIPORT_HYBRID要求是IOCTL_SCSI_MINIPORT的子 IOCTL。 StorPort 會接收並重新格式化此 IOCTL，然後以 STORAGE_REQUEST_BLOCK ( SRB) 的形式傳送至迷你埠，且函式類型為 SRB_FUNCTION_IO_CONTROL。輸入和輸出數據包含在 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 表示緩衝區的大小，其大小必須至少為 sizeof (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 狀態代碼。

傳回碼	Description
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。
大小: 結構的大小。設定為 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_INFO函數要求傳回之HYBRID_INFORMATION結構的 MaximumHybridPriorityLevel 成員中的值。此值必須 > 0。
TargetPriority: 要從 SourcePriority 層級降級的數據目標優先順序層級。此值必須是 < SourcePriority。
Reserved0: 保留的。
Reserved1: 保留的。
LbaCount: 要降級為新優先順序層級的 LBA 數目。