Export (0) Print
Expand All

IOCTL_SCSI_MINIPORT_HYBRID control code

The IOCTL_SCSI_MINIPORT_HYBRID control code sends a hybrid disk control request to an HBA-specific miniport driver. The IOCTL_SCSI_MINIPORT_HYBRID request is a sub-IOCTL of IOCTL_SCSI_MINIPORT. This IOCTL is received and reformatted by StorPort, then sent to the miniport as a STORAGE_REQUEST_BLOCK (SRB) with a function type of SRB_FUNCTION_IO_CONTROL. The input and output data is contained in the SRB data block.

IOCTL_SCSI_MINIPORT_HYBRID is intended for use by third-party applications or filter drives which manage security features such as encryption or write-through behavior.

Warning  Use of IOCTL_SCSI_MINIPORT_HYBRID to modify hybrid cache behavior will conflict with the operation of Windows system components and is not supported.

Input Parameters

The buffer specified in the DataBuffer member of the SRB must contain an SRB_IO_CONTROL structure and a HYBRID_REQUEST_BLOCK structure. Depending on the Function member of HYBRID_REQUEST_BLOCK, additional data can be supplied. DataTransferLength indicates the size, in bytes, of the buffer, which must be at least sizeof (SRB_IO_CONTROL) + sizeof(HYBRID_REQUEST_BLOCK), with additional storage for function data if the DataBufferLength member of the HYBRID_REQUEST_BLOCK is nonzero.

Output Parameters

An updated SRB_IO_CONTROL structure is returned to the data buffer in the SRB. The DataBufferOffset and DataBufferLength members of HYBRID_REQUEST_BLOCK are nonzero when data is returned for the specified Function. The DataTransferLength member of the SRB is updated when data is returned for the request function.

Return Codes

The resulting status of the function request is set in the ReturnCode member of SRB_IO_CONTROL. The following are the hybrid disk IOCTL status codes.

Return CodeDescription
HYBRID_STATUS_SUCCESSThe function completed successfully.
HYBRID_STATUS_ILLEGAL_REQUESTThe request contains an invalid function code.
HYBRID_STATUS_INVALID_PARAMETEREither the input or output parameters are formatted incorrectly.
HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALLThe data length given in DataBufferLength is too small to contain the request output.

 

Remarks

A HYBRID_REQUEST_BLOCK structure immediately follows the SRB_IO_CONTROL structure in the data buffer. HYBRID_REQUEST_BLOCK is defined in ntddscsi.h as the following.


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

Version

The version of the structure. Set to HYBRID_REQUEST_BLOCK_STRUCTURE_VERSION.

Size

The size of the structure. Set to sizeof(HYBRID_REQUEST_BLOCK).

Function

The hybrid disk request function. The function code is one of the following.

HYBRID_FUNCTION_GET_INFO

Returns information about the capabilities and attributes of a hybrid devices, such as supported priority levels, command set support, and cache size in a HYBRID_INFORMATION structure. On input, the DataBuffer specified in the SRB must contain the SRB_IO_CONTROL and HYBRID_REQUEST_BLOCK structures. The DataBufferLength must be large enough to include the HYBRID_INFORMATION structure returned. The DataBufferOffset points to the output data containing HYBRID_INFORMATION. If the buffer is too small to return the data, the ReturnCode member of SRB_IO_CONTROL is set to HYBRID_STATUS_OUTPUT_BUFFER_TOO_SMALL and DataBufferLength of the HYBRID_REQUEST_BLOCK is set to indicate the required length.

HYBRID_FUNCTION_DISABLE_CACHING_MEDIUM

Disables the hybrid cache. Disabling the cache can take several minutes. If queried during this operation, the NV_CACHE_STATUS member of the HYBRID_INFORMATION structure is set to NvCacheStatusDisabling until the cache is completely disabled. The caller should check the status of NV_CACHE_STATUS to verify that the caching medium is disabled. Once the cache is fully disabled, the status is NvCacheStatusDisabled. For this function, the DataBufferOffset member of HYBRID_REQUEST_BLOCK is set 0. This function has no output parameters.

HYBRID_FUNCTION_ENABLE_CACHING_MEDIUM

Sets the caching medium to its default state, which is “enabled”. The DataBufferOffset member of HYBRID_REQUEST_BLOCK is set to 0. When this function completes, when queried, the NV_CACHE_STATUS member of the HYBRID_INFORMATION structure is set to NvCacheStatusEnabled. For this function, the DataBufferOffset member of HYBRID_REQUEST_BLOCK is set 0. This function has no output parameters.

HYBRID_FUNCTION_SET_DIRTY_THRESHOLD

Sets the thresholds for dirty data synchronization on the device. In addition to SRB_IO_CONTROL and HYBRID_REQUEST_BLOCK, this function requires a HYBRID_DIRTY_THRESHOLDS structure included as input. The DataBufferOffset member is set to the beginning of the HYBRID_DIRTY_THRESHOLDS structure. This function has no output parameters.

HYBRID_FUNCTION_DEMOTE_BY_SIZE

This function demotes the priority of a given amount of cache contents to a lower priority. It can be used to achieve a soft reset of the cache by demoting all cache contents to priority 0. In addition to SRB_IO_CONTROL and HYBRID_REQUEST_BLOCK, this function requires a HYBRID_DEMOTE_BY_SIZE structure included as input. The DataBufferOffset member is set to the beginning of the HYBRID_DEMOTE_BY_SIZE structure. This function has no output parameters.

Flags

Reserved. Set to 0.

DataBufferOffset

The offset for additional data that was sent or is returned for the function specified in Function. This value varies on the data required for Function. This value is the offset from the beginning the DataBuffer of the SRB which contains a SRB_IO_CONTROL structure and other required data structures. It should point to the first location after SRB_IO_CONTROL and HYBRID_REQUEST_BLOCK. This value is aligned at a multiple of sizeof(PVOID). If there is no buffer then DataBufferOffset is set to 0.

DataBufferLength

The size the data block found at DataBufferOffset.

The parameter requirements depend on the function code of the hybrid disk request. The following table lists the parameters required for each function.

FunctionInput ParametersOutput Parameters
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

 

The HYBRID_REQUEST_BLOCK structure is located after the SRB_IO_CONTROL structure in the DataBuffer of the SRB. Any function data included with the request is found at the offset in DataBufferOffset after the beginning of the SRB_IO_CONTROL structure.

The following example demonstrates retrieval of the function data for a HYBRID_FUNCTION_SET_DIRTY_THRESHOLD request.


    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

The HYBRID_FUNCTION_SET_DIRTY_THRESHOLD function uses the HYBRID_DIRTY_THRESHOLDS structure for its input parameters. HYBRID_DIRTY_THRESHOLDS is defined in ntddscsi.h as the following.


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

Version

The version of the structure. Set to HYBRID_REQUEST_INFO_STRUCTURE_VERSION.

Size

The size of the structure. Set to sizeof(HYBRID_DIRTY_THRESHOLDS).

DirtyLowThreshold

The fractional low threshold value for the hybrid disk cache to synchronize to disk.

DirtyHighThreshold

The fractional high threshold value for the hybrid disk cache to synchronize to disk.

The values of DirtyLowThreshold and DirtyHighThreshold are expressed as the smaller part of a ratio between the threshold value and a fraction base. The fraction base is determined by the FractionBase member of the HYBRID_INFORMATION structure.

HYBRID_DEMOTE_BY_SIZE

The HYBRID_FUNCTION_DEMOTE_BY_SIZE function uses the HYBRID_DEMOTE_BY_SIZE structure for its input parameters. HYBRID_DEMOTE_BY_SIZE is defined in ntddscsi.h as the following.


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

The version of the structure. Set to HYBRID_REQUEST_INFO_STRUCTURE_VERSION.

Size

The size of the structure. Set to sizeof(HYBRID_DEMOTE_BY_SIZE).

SourcePriority

The original priority level of the data to demote. This value must be <= the value in the MaximumHybridPriorityLevel member of the HYBRID_INFORMATION structure returned by from a HYBRID_FUNCTION_GET_INFO function request. This value must be > 0.

TargetPriority

The target priority level of the data to demote from the SourcePriority level. This value must be < SourcePriority.

Reserved0

Reserved.

Reserved1

Reserved.

LbaCount

The number of LBAs to demote to the new priority level.

The SRB_IO_CONTROL structure for this IOCTL contains IOCTL_MINIPORT_SIGNATURE_HYBRDISK in its Signature member and IOCTL_SCSI_MINIPORT_HYBRID in the ControlCode member.

Requirements

Version

Available starting with Windows 8.1.

Header

Ntddscsi.h (include Ntddscsi.h)

See also

HYBRID_INFORMATION
IOCTL_SCSI_MINIPORT
SRB_IO_CONTROL
STORAGE_REQUEST_BLOCK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft