IOCTL_SCSI_MINIPORT_HYBRID IOCTL (ntddscsi.h)

Artículo
08/07/2023

El código de control IOCTL_SCSI_MINIPORT_HYBRID envía una solicitud de control de disco híbrido a un controlador de miniport específico de HBA. La solicitud de IOCTL_SCSI_MINIPORT_HYBRID es un sub-IOCTL de IOCTL_SCSI_MINIPORT. StorPort recibe y vuelve a formatear este IOCTL y, a continuación, se envía al minipuerto como un STORAGE_REQUEST_BLOCK (SRB) con un tipo de función de SRB_FUNCTION_IO_CONTROL. Los datos de entrada y salida se encuentran en el bloque de datos SRB.

IOCTL_SCSI_MINIPORT_HYBRID está pensado para que lo usen aplicaciones de terceros o unidades de filtro que administran características de seguridad como el cifrado o el comportamiento de escritura a través.

Advertencia El uso de IOCTL_SCSI_MINIPORT_HYBRID para modificar el comportamiento de la caché híbrida entrará en conflicto con el funcionamiento de los componentes del sistema de Windows y no se admite.

Nota Los modelos del controlador de puerto SCSI y del controlador de miniporte SCSI pueden modificarse o no estar disponibles en el futuro. En su lugar, se recomienda usar el controlador Storport y los modelos de controlador de miniport storport .

Código principal

IRP_MJ_DEVICE_CONTROL

Búfer de entrada

El búfer especificado en el miembro DataBuffer del SRB debe contener una estructura de SRB_IO_CONTROL y una estructura de HYBRID_REQUEST_BLOCK . Dependiendo del miembro Function de HYBRID_REQUEST_BLOCK, se pueden proporcionar datos adicionales.

Longitud del búfer de entrada

DataTransferLength indica el tamaño, en bytes, del búfer, que debe ser al menos sizeof (SRB_IO_CONTROL) + sizeof(HYBRID_REQUEST_BLOCK), con almacenamiento adicional para los datos de función si el miembro DataBufferLength del HYBRID_REQUEST_BLOCK es distinto de cero.

Búfer de salida

Se devuelve una estructura SRB_IO_CONTROL actualizada al búfer de datos en la SRB.

Longitud del búfer de salida

Los miembros DataBufferOffset y DataBufferLength de HYBRID_REQUEST_BLOCK no son cero cuando se devuelven datos para la función especificada. El miembro DataTransferLength del SRB se actualiza cuando se devuelven datos para la función de solicitud.

Bloque de estado

El estado resultante de la solicitud de función se establece en el miembro ReturnCode de SRB_IO_CONTROL. A continuación se muestran los códigos de estado de IOCTL del disco híbrido.

Código de retorno	Descripción
HYBRID_STATUS_SUCCESS	Si se devuelve este valor, significa que la función se completó correctamente.
HYBRID_STATUS_ILLEGAL_REQUEST	La solicitud contiene un código de función no válido.
HYBRID_STATUS_INVALID_PARAMETER	Los parámetros de entrada o salida tienen un formato incorrecto.
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL	La longitud de datos especificada en DataBufferLength es demasiado pequeña para contener la salida de la solicitud.

Comentarios

Una estructura de HYBRID_REQUEST_BLOCK sigue inmediatamente la estructura de SRB_IO_CONTROL en el búfer de datos. HYBRID_REQUEST_BLOCK se define en ntddscsi.h como se indica a continuación.

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

Los requisitos de parámetro dependen del código de función de la solicitud de disco híbrido. En la tabla siguiente se enumeran los parámetros necesarios para cada función.

Función	Parámetros de entrada	Parámetros de salida
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 estructura HYBRID_REQUEST_BLOCK se encuentra después de la estructura de SRB_IO_CONTROL en DataBuffer de la SRB. Los datos de función incluidos con la solicitud se encuentran en el desplazamiento en DataBufferOffset después del principio de la estructura de SRB_IO_CONTROL .

En el ejemplo siguiente se muestra la recuperación de los datos de función para una solicitud 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

La función HYBRID_FUNCTION_SET_DIRTY_THRESHOLD usa la estructura HYBRID_DIRTY_THRESHOLDS para sus parámetros de entrada. HYBRID_DIRTY_THRESHOLDS se define en ntddscsi.h como se indica a continuación.

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

Version: Versión de la estructura. Establezca en HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Size: Tamaño de la estructura. Establezca en sizeof(HYBRID_DIRTY_THRESHOLDS).
DirtyLowThreshold: Valor de umbral de baja fracción para que la caché de disco híbrida se sincronice con el disco.
DirtyHighThreshold: Valor de umbral alto fraccionaria para que la caché de disco híbrida se sincronice con el disco.

Los valores de DirtyLowThreshold y DirtyHighThreshold se expresan como la parte más pequeña de una relación entre el valor de umbral y una base de fracción. La base de fracción viene determinada por el miembro FractionBase de la estructura HYBRID_INFORMATION .

HYBRID_DEMOTE_BY_SIZE

La función HYBRID_FUNCTION_DEMOTE_BY_SIZE usa la estructura HYBRID_DEMOTE_BY_SIZE para sus parámetros de entrada. HYBRID_DEMOTE_BY_SIZE se define en ntddscsi.h como se indica a continuación.

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: Versión de la estructura. Establezca en HYBRID_REQUEST_INFO_STRUCTURE_VERSION.
Size: Tamaño de la estructura. Establezca en sizeof(HYBRID_DEMOTE_BY_SIZE).
SourcePriority: Nivel de prioridad original de los datos que se van a degradar. Este valor debe ser <= el valor del miembro MaximumHybridPriorityLevel de la estructura de HYBRID_INFORMATION devuelta por desde una solicitud de función de HYBRID_FUNCTION_GET_INFO . Este valor debe ser > 0.
TargetPriority: Nivel de prioridad de destino de los datos que se van a degradar desde el nivel SourcePriority . Este valor debe ser < SourcePriority.
Reserved0: Reservado.
Reserved1: Reservado.
LbaCount: Número de LBA que se degradan al nuevo nivel de prioridad.

La estructura SRB_IO_CONTROL para este IOCTL contiene IOCTL_MINIPORT_SIGNATURE_HYBRDISK en su miembro Signature y IOCTL_SCSI_MINIPORT_HYBRID en el miembro ControlCode .