IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

Artikel
02/07/2025

Der IOCTL_SCSI_MINIPORT_HYBRID Steuercode sendet eine Hybrid-Datenträgersteuerungsanforderung an einen HBA-spezifischen Miniporttreiber. Die IOCTL_SCSI_MINIPORT_HYBRID-Anforderung ist eine unter-IOCTL von IOCTL_SCSI_MINIPORT. Diese IOCTL wird von StorPort empfangen und neu formatiert und dann als STORAGE_REQUEST_BLOCK (SRB) mit einem Funktionstyp von SRB_FUNCTION_IO_CONTROL an den Miniport gesendet. Die Eingabe- und Ausgabedaten sind im SRB-Datenblock enthalten.

IOCTL_SCSI_MINIPORT_HYBRID ist für die Verwendung durch Drittanbieteranwendungen oder Filterlaufwerke vorgesehen, die Sicherheitsfeatures wie Verschlüsselung oder Schreibverhalten verwalten.

Warnung Verwendung von IOCTL_SCSI_MINIPORT_HYBRID zum Ändern des Hybridcacheverhaltens steht im Konflikt mit dem Betrieb von Windows-Systemkomponenten und wird nicht unterstützt.

Hinweis Der SCSI-Porttreiber und die SCSI-Miniporttreibermodelle können in Zukunft geändert oder nicht mehr verfügbar sein. Stattdessen empfehlen wir die Verwendung des Storport-Treibers und Storport Miniport Treibermodelle.

Hauptcode

IRP_MJ_DEVICE_CONTROL

Eingabepuffer

Der im DataBuffer Member des SRB angegebene Puffer muss eine SRB_IO_CONTROL Struktur und eine HYBRID_REQUEST_BLOCK Struktur enthalten. Je nach Function Member von HYBRID_REQUEST_BLOCKkönnen zusätzliche Daten bereitgestellt werden.

Eingabepufferlänge

DataTransferLength- gibt die Größe des Puffers in Byte an, die mindestens Größe (SRB_IO_CONTROL) + Sizeof(HYBRID_REQUEST_BLOCK) mit zusätzlichem Speicher für Funktionsdaten sein muss, wenn das DataBufferLength Mitglied der HYBRID_REQUEST_BLOCK ungleich Null ist.

Ausgabepuffer

Eine aktualisierte SRB_IO_CONTROL Struktur wird an den Datenpuffer im SRB zurückgegeben.

Länge des Ausgabepuffers

Die DataBufferOffset- und DataBufferLength- Elemente HYBRID_REQUEST_BLOCK sind nicht null, wenn Daten für die angegebene Function-zurückgegeben werden. Das DataTransferLength Mitglied des SRB wird aktualisiert, wenn Daten für die Anforderungsfunktion zurückgegeben werden.

Statusblock

Der resultierende Status der Funktionsanforderung wird im ReturnCode Member von SRB_IO_CONTROLfestgelegt. Im Folgenden finden Sie die IOCTL-Statuscodes für Hybriddatenträger.

Rückgabecode	Beschreibung
HYBRID_STATUS_SUCCESS	Die Funktion wurde erfolgreich abgeschlossen.
HYBRID_STATUS_ILLEGAL_REQUEST	Die Anforderung enthält einen ungültigen Funktionscode.
HYBRID_STATUS_INVALID_PARAMETER	Die Eingabe- oder Ausgabeparameter sind falsch formatiert.
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL	Die in DataBufferLength- angegebene Datenlänge ist zu klein, um die Anforderungsausgabe zu enthalten.

Bemerkungen

Eine HYBRID_REQUEST_BLOCK Struktur folgt unmittelbar der SRB_IO_CONTROL Struktur im Datenpuffer. HYBRID_REQUEST_BLOCK wird in ntddscsi.h wie folgt definiert.

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

Die Parameteranforderungen hängen vom Funktionscode der Hybriddatenträgeranforderung ab. In der folgenden Tabelle sind die parameter aufgeführt, die für jede Funktion erforderlich sind.

Funktion	Eingabeparameter	Ausgabeparameter
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

Die HYBRID_REQUEST_BLOCK-Struktur befindet sich nach der SRB_IO_CONTROL Struktur im DataBuffer- des SRB. Alle Funktionsdaten, die in der Anforderung enthalten sind, werden im Offset in DataBufferOffset nach dem Anfang der SRB_IO_CONTROL Struktur gefunden.

Das folgende Beispiel veranschaulicht das Abrufen der Funktionsdaten für eine HYBRID_FUNCTION_SET_DIRTY_THRESHOLD Anforderung.

    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

Die HYBRID_FUNCTION_SET_DIRTY_THRESHOLD-Funktion verwendet die HYBRID_DIRTY_THRESHOLDS Struktur für die Eingabeparameter. HYBRID_DIRTY_THRESHOLDS wird in ntddscsi.h wie folgt definiert.

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

Version: Die Version der Struktur. Auf HYBRID_REQUEST_INFO_STRUCTURE_VERSION festgelegt.
Größe: Die Größe der Struktur. Auf Größe(HYBRID_DIRTY_THRESHOLDS) festgelegt.
DirtyLowThreshold: Der bruchteilale niedrige Schwellenwert für den Hybriddatenträgercache, der mit dem Datenträger synchronisiert werden soll.
DirtyHighThreshold: Der Bruchwert mit hohem Schwellenwert für den Hybriddatenträgercache, der mit dem Datenträger synchronisiert werden soll.

Die Werte von DirtyLowThreshold und DirtyHighThreshold werden als kleinerer Teil eines Verhältnisses zwischen dem Schwellenwert und einer Bruchbasis ausgedrückt. Die Bruchbasis wird durch das FractionBase Member der HYBRID_INFORMATION-Struktur bestimmt.

HYBRID_DEMOTE_BY_SIZE

Die HYBRID_FUNCTION_DEMOTE_BY_SIZE-Funktion verwendet die HYBRID_DEMOTE_BY_SIZE Struktur für die Eingabeparameter. HYBRID_DEMOTE_BY_SIZE wird in ntddscsi.h wie folgt definiert.

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;

Version: Die Version der Struktur. Auf HYBRID_REQUEST_INFO_STRUCTURE_VERSION festgelegt.
Größe: Die Größe der Struktur. Auf Größe(HYBRID_DEMOTE_BY_SIZE) festgelegt.
SourcePriority: Die ursprüngliche Prioritätsebene der zu tiefer stufenden Daten. Dieser Wert muss <= der Wert in der MaximumHybridPriorityLevel Member der HYBRID_INFORMATION Struktur sein, die von einer HYBRID_FUNCTION_GET_INFO Funktionsanforderung zurückgegeben wird. Dieser Wert muss > 0 sein.
TargetPriority: Die Zielprioritätsebene der Daten, die von der SourcePriority-ebene tiefer stufen sollen. Dieser Wert muss < SourcePriority-sein.
Reserviert0: Reserviert.
Reserviert1: Reserviert.
LbaCount: Die Anzahl der LBAs, die auf die neue Prioritätsebene herabstufen sollen.

Die SRB_IO_CONTROL Struktur für diese IOCTL enthält IOCTL_MINIPORT_SIGNATURE_HYBRDISK in seinem Signature Member und IOCTL_SCSI_MINIPORT_HYBRID im ControlCode Member.