IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

Articolo
02/27/2024

Il codice di controllo IOCTL_SCSI_MINIPORT_HYBRID invia una richiesta di controllo del disco ibrido a un driver miniport specifico di HBA. La richiesta di IOCTL_SCSI_MINIPORT_HYBRID è un IOCTL secondario di IOCTL_SCSI_MINIPORT. Questo IOCTL viene ricevuto e riformattato da StorPort, quindi inviato al miniport come STORAGE_REQUEST_BLOCK (SRB) con un tipo di funzione di SRB_FUNCTION_IO_CONTROL. I dati di input e output sono contenuti nel blocco di dati SRB.

IOCTL_SCSI_MINIPORT_HYBRID è destinato all'uso da parte di applicazioni di terze parti o unità di filtro che gestiscono funzionalità di sicurezza come la crittografia o il comportamento write-through.

Avviso L'uso di IOCTL_SCSI_MINIPORT_HYBRID per modificare il comportamento della cache ibrida sarà in conflitto con il funzionamento dei componenti di sistema di Windows e non è supportato.

Nota I modelli di driver di porta SCSI e miniport SCSI potrebbero essere modificati o non disponibili in futuro. È invece consigliabile usare il driver Storport e i modelli di driver miniport Storport .

Codice principale

IRP_MJ_DEVICE_CONTROL

Buffer di input

Il buffer specificato nel membro DataBuffer di SRB deve contenere una struttura SRB_IO_CONTROL e una struttura HYBRID_REQUEST_BLOCK . A seconda del membro Function di HYBRID_REQUEST_BLOCK, è possibile fornire dati aggiuntivi.

Lunghezza del buffer di input

DataTransferLength indica le dimensioni, in byte, del buffer, che deve essere almeno sizeof (SRB_IO_CONTROL) + sizeof(HYBRID_REQUEST_BLOCK), con spazio di archiviazione aggiuntivo per i dati della funzione se il membro DataBufferLength del HYBRID_REQUEST_BLOCK è diverso da zero.

Buffer di output

Una struttura SRB_IO_CONTROL aggiornata viene restituita al buffer dei dati in SRB.

Lunghezza del buffer di output

I membri DataBufferOffset e DataBufferLength di HYBRID_REQUEST_BLOCK sono diversi da zero quando i dati vengono restituiti per la funzione specificata. Il membro DataTransferLength di SRB viene aggiornato quando vengono restituiti i dati per la funzione di richiesta.

Blocco dello stato

Lo stato risultante della richiesta di funzione viene impostato nel membro ReturnCode di SRB_IO_CONTROL. Di seguito sono riportati i codici di stato IOCTL del disco ibrido.

Codice restituito	Descrizione
HYBRID_STATUS_SUCCESS	La funzione è stata completata correttamente.
HYBRID_STATUS_ILLEGAL_REQUEST	La richiesta contiene un codice di funzione non valido.
HYBRID_STATUS_INVALID_PARAMETER	I parametri di input o di output vengono formattati in modo non corretto.
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL	La lunghezza dei dati specificata in DataBufferLength è troppo piccola per contenere l'output della richiesta.

Commenti

Una struttura HYBRID_REQUEST_BLOCK segue immediatamente la struttura SRB_IO_CONTROL nel buffer dei dati. HYBRID_REQUEST_BLOCK è definito in ntddscsi.h come indicato di seguito.

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

I requisiti dei parametri dipendono dal codice della funzione della richiesta del disco ibrido. Nella tabella seguente sono elencati i parametri necessari per ogni funzione.

Funzione	Parametri di input	Parametri di output
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

La struttura HYBRID_REQUEST_BLOCK si trova dopo la struttura SRB_IO_CONTROL nel DataBuffer di SRB. Tutti i dati di funzione inclusi nella richiesta vengono trovati in corrispondenza dell'offset in DataBufferOffset dopo l'inizio della struttura SRB_IO_CONTROL .

Nell'esempio seguente viene illustrato il recupero dei dati della funzione per una richiesta di 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

La funzione HYBRID_FUNCTION_SET_DIRTY_THRESHOLD usa la struttura HYBRID_DIRTY_THRESHOLDS per i parametri di input. HYBRID_DIRTY_THRESHOLDS è definito in ntddscsi.h come indicato di seguito.

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

Versione: Versione della struttura. Impostare su HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Dimensione: Dimensioni della struttura. Impostare su sizeof(HYBRID_DIRTY_THRESHOLDS).
DirtyLowThreshold: Valore soglia minimo frazionaria per la cache del disco ibrido da sincronizzare con il disco.
DirtyHighThreshold: Valore soglia massimo frazionaria per la cache del disco ibrido da sincronizzare con il disco.

I valori di DirtyLowThreshold e DirtyHighThreshold sono espressi come parte inferiore di un rapporto tra il valore soglia e una base fra frazioni. La base frazionaria è determinata dal membro FractionBase della struttura HYBRID_INFORMATION .

HYBRID_DEMOTE_BY_SIZE

La funzione HYBRID_FUNCTION_DEMOTE_BY_SIZE usa la struttura HYBRID_DEMOTE_BY_SIZE per i parametri di input. HYBRID_DEMOTE_BY_SIZE è definito in ntddscsi.h come indicato di seguito.

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;

Versione: Versione della struttura. Impostare su HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Dimensione: Dimensioni della struttura. Impostare su sizeof(HYBRID_DEMOTE_BY_SIZE).
SourcePriority: Livello di priorità originale dei dati da abbassare di livello. Questo valore deve essere <= il valore nel membro MaximumHybridPriorityLevel della struttura HYBRID_INFORMATION restituito da una richiesta di funzione HYBRID_FUNCTION_GET_INFO . Questo valore deve essere > 0.
TargetPriority: Livello di priorità di destinazione dei dati da abbassare dal livello SourcePriority . Questo valore deve essere < SourcePriority.
Riservato0: Riservato.
Riservato1: Riservato.
LbaCount: Numero di LBA da abbassare di livello al nuovo livello di priorità.

La struttura SRB_IO_CONTROL per questo IOCTL contiene IOCTL_MINIPORT_SIGNATURE_HYBRDISK nel membro Signature e IOCTL_SCSI_MINIPORT_HYBRID nel membro ControlCode .