IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

Artigo
02/26/2024

O código de controle IOCTL_SCSI_MINIPORT_HYBRID envia uma solicitação de controle de disco híbrido para um driver de miniporto específico do HBA. A solicitação IOCTL_SCSI_MINIPORT_HYBRID é um sub-IOCTL de IOCTL_SCSI_MINIPORT. Esse IOCTL é recebido e reformatado pelo StorPort e, em seguida, enviado para o miniporto como um SRB (STORAGE_REQUEST_BLOCK ) com um tipo de função de SRB_FUNCTION_IO_CONTROL. Os dados de entrada e saída estão contidos no bloco de dados SRB.

IOCTL_SCSI_MINIPORT_HYBRID destina-se ao uso por aplicativos de terceiros ou unidades de filtro que gerenciam recursos de segurança, como criptografia ou comportamento de gravação.

Aviso O uso de IOCTL_SCSI_MINIPORT_HYBRID para modificar o comportamento do cache híbrido entrará em conflito com a operação dos componentes do sistema Windows e não tem suporte.

Nota O driver de porta SCSI e os modelos de driver de miniporta SCSI podem ser alterados ou indisponíveis no futuro. Em vez disso, recomendamos usar os modelos de driver storport e driver de miniporto Storport .

Código principal

IRP_MJ_DEVICE_CONTROL

Buffer de entrada

O buffer especificado no membro DataBuffer do SRB deve conter uma estrutura SRB_IO_CONTROL e uma estrutura HYBRID_REQUEST_BLOCK . Dependendo do membro function de HYBRID_REQUEST_BLOCK, dados adicionais podem ser fornecidos.

Comprimento do buffer de entrada

DataTransferLength indica o tamanho, em bytes, do buffer, que deve ser pelo menos sizeof (SRB_IO_CONTROL) + sizeof(HYBRID_REQUEST_BLOCK), com armazenamento adicional para dados de função se o membro DataBufferLength do HYBRID_REQUEST_BLOCK for diferente de zero.

Buffer de saída

Uma estrutura de SRB_IO_CONTROL atualizada é retornada para o buffer de dados no SRB.

Comprimento do buffer de saída

Os membros DataBufferOffset e DataBufferLength de HYBRID_REQUEST_BLOCK são diferentes de zero quando os dados são retornados para a Função especificada. O membro DataTransferLength do SRB é atualizado quando os dados são retornados para a função de solicitação.

Bloco de status

O status resultante da solicitação de função é definido no membro ReturnCode do SRB_IO_CONTROL. Veja a seguir os códigos de status ioctl de disco híbrido.

Código de retorno	Descrição
HYBRID_STATUS_SUCCESS	A função foi concluída com êxito.
HYBRID_STATUS_ILLEGAL_REQUEST	A solicitação contém um código de função inválido.
HYBRID_STATUS_INVALID_PARAMETER	Os parâmetros de entrada ou saída são formatados incorretamente.
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL	O comprimento de dados dado em DataBufferLength é muito pequeno para conter a saída da solicitação.

Comentários

Uma estrutura HYBRID_REQUEST_BLOCK segue imediatamente a estrutura SRB_IO_CONTROL no buffer de dados. HYBRID_REQUEST_BLOCK é definido em ntddscsi.h como o seguinte.

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

Os requisitos de parâmetro dependem do código de função da solicitação de disco híbrido. A tabela a seguir lista os parâmetros necessários para cada função.

Função	Parâmetros de Entrada	Parâmetros de saída
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

A estrutura HYBRID_REQUEST_BLOCK está localizada após a estrutura SRB_IO_CONTROL no DataBuffer do SRB. Todos os dados de função incluídos na solicitação são encontrados no deslocamento em DataBufferOffset após o início da estrutura SRB_IO_CONTROL .

O exemplo a seguir demonstra a recuperação dos dados de função para uma solicitação de 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

A função HYBRID_FUNCTION_SET_DIRTY_THRESHOLD usa a estrutura HYBRID_DIRTY_THRESHOLDS para seus parâmetros de entrada. HYBRID_DIRTY_THRESHOLDS é definido em ntddscsi.h como o seguinte.

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

Version: A versão da estrutura. Defina como HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Tamanho: O tamanho da estrutura. Defina como sizeof(HYBRID_DIRTY_THRESHOLDS).
DirtyLowThreshold: O valor de limite baixo fracionário do cache de disco híbrido a ser sincronizado com o disco.
DirtyHighThreshold: O valor de limite alto fracionário para o cache de disco híbrido a ser sincronizado com o disco.

Os valores de DirtyLowThreshold e DirtyHighThreshold são expressos como a parte menor de uma taxa entre o valor limite e uma base de fração. A base de fração é determinada pelo membro FractionBase da estrutura HYBRID_INFORMATION .

HYBRID_DEMOTE_BY_SIZE

A função HYBRID_FUNCTION_DEMOTE_BY_SIZE usa a estrutura HYBRID_DEMOTE_BY_SIZE para seus parâmetros de entrada. HYBRID_DEMOTE_BY_SIZE é definido em ntddscsi.h como o seguinte.

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: A versão da estrutura. Defina como HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Tamanho: O tamanho da estrutura. Defina como sizeof(HYBRID_DEMOTE_BY_SIZE).
SourcePriority: O nível de prioridade original dos dados a serem rebaixada. Esse valor deve ser <= o valor no membro MaximumHybridPriorityLevel da estrutura HYBRID_INFORMATION retornada por de uma solicitação de função HYBRID_FUNCTION_GET_INFO . Esse valor deve ser > 0.
TargetPriority: O nível de prioridade de destino dos dados a serem rebaixados do nível SourcePriority . Esse valor deve ser < SourcePriority.
Reservado0: Reservado.
Reservado1: Reservado.
LbaCount: O número de LBAs a serem rebaixada para o novo nível de prioridade.

A estrutura SRB_IO_CONTROL para esse IOCTL contém IOCTL_MINIPORT_SIGNATURE_HYBRDISK em seu membro Signature e IOCTL_SCSI_MINIPORT_HYBRID no membro ControlCode .