IOCTL_SCSI_PASS_THROUGH_DIRECT_EX IOCTL (ntddscsi.h)

Article
05/18/2021

The IOCTL_SCSI_PASS_THROUGH_DIRECT_EX control code request is the extended version of the IOCTL_SCSI_PASS_THROUGH_DIRECT request. This request provides support for bidirectional data transfers and allows a command data block (CDB) > 16 bytes.

Allows an application to send almost any SCSI command to a target device, with the following restrictions:

Multitarget commands, such as COPY, are not allowed.
If a class driver for the target type of device exists, the request must be sent to that class driver. Thus, an application can send this request directly to the system port driver for a target logical unit only if there is no class driver for the type of device connected to that LU.
This request must be made if the input CDB might require the underlying miniport driver to access memory directly.

The calling application creates the SCSI command descriptor block, which can include a request for request-sense data if a CHECK CONDITION occurs. If the CDB requests a data transfer operation, the caller must set up an adapter device aligned buffer from which or into which the miniport driver can transfer data directly. This request is typically used for transferring larger amounts of data (>16K).

Applications can send this request by means of an IRP_MJ_DEVICE_CONTROL request.

Storage class drivers set the minor IRP number to IRP_MN_SCSI_CLASS to indicate that the request has been processed by a storage class driver.

Note The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Instead, we recommend using the Storport driver and Storport miniport driver models.

Major code

IRP_MJ_DEVICE_CONTROL

Input buffer

Parameters.DeviceIoControl.InputBufferLength indicates the size, in bytes, of the buffer at Irp->AssociatedIrp.SystemBuffer, which must be at least (sense data size + sizeof(SCSI_PASS_THROUGH_DIRECT_EX)). The size of the SCSI_PASS_THROUGH_DIRECT_EX structure is fixed.

This structure includes a SCSI CDB, which must be initialized by the caller except for the path, target ID, and LUN, which are filled in by the port driver. For a data-out command, the data to be transferred must be in an adapter device aligned buffer. The DataInBuffer member of SCSI_PASS_THROUGH_DIRECT_EX is a pointer to this adapter device aligned buffer. The caller must allocate additional storage, following the SCSI_PASS_THROUGH_DIRECT_EX structure, if the caller asks for request-sense data.

Input buffer length

Output buffer

The port driver returns any request-sense data and the SCSI_PASS_THROUGH_DIRECT_EX structure to the buffer at Irp->AssociatedIrp.SystemBuffer.

Output buffer length

SenseInfoLength and DataOutTransferLength are updated to indicate the amount of data transferred. The port driver returns any data transferred from the device to the supplied cache-aligned buffer at DataOutBuffer.

Status block

The Information field is set to the number of bytes returned in the output buffer at Irp->AssociatedIrp.SystemBuffer. The Status field is set to STATUS_SUCCESS, or possibly to STATUS_BUFFER_TOO_SMALL or STATUS_INVALID_PARAMETER if the input Length value in SCSI_PASS_THROUGH_DIRECT_EX is improperly set or the buffer specified in DataInBuffer is not properly device aligned.

Remarks

For data transfer operations, a buffer with alignment matching the adapter device is required. Applications can retrieve the device alignment mask by issuing an IOCTL_STORAGE_QUERY_PROPERTY control code request with a query type of PropertyStandardQuery and property id of StorageAdapterProperty. The alignment mask is found in the AlignmentMask member of the STORAGE_ADAPTER_DESCRIPTOR structure that is returned. Drivers may also use the value in the AlignmentMask member of the adapter's DeviceObject.

In the following example function, a buffer is prepared as a device aligned data transfer buffer.


PVOID AllocateAlignedBuffer(ULONG size, ULONG AlignmentMask, PVOID *pUnAlignedBuffer)
{
    PVOID AlignedBuffer;
    ULONG_PTR FullWordMask = (ULONG_PTR)AlignmentMask;

    if (AlignmentMask == 0)
    {
        AlignedBuffer = malloc(size);
        // return the original buffer to free later
        *pUnAlignedBuffer = AlignedBuffer;
    }
    else
    {
        // expand the size for the alignment window
        size += AlignmentMask;
        AlignedBuffer = malloc(size);
        // return the original buffer to free later
        *pUnAlignedBuffer = AlignedBuffer;
        // adjust buffer pointer for the desired alignment
        AlignedBuffer = (PVOID)(((ULONG_PTR)AlignedBuffer + FullWordMask) & ~FullWordMask);
    }

    return AlignedBuffer;
}

In order to issue an IOCTL_SCSI_PASS_THROUGH_DIRECT_EX request, the underlying storage device must support extended SRBs. This means that the supported SRB type is SRB_TYPE_STORAGE_REQUEST_BLOCK. An application can query for SRB support with the IOCTL_STORAGE_QUERY_PROPERTY request with a query type of PropertyStandardQuery and a property type of StorageDeviceProperty. The SrbType member returned in the STORAGE_ADAPTER_DESCRIPTIOR structure will indicate either SRB_TYPE_SCSI_REQUEST_BLOCK or SRB_TYPE_STORAGE_REQUEST_BLOCK.

Requirements

Requirement	Value
Header	ntddscsi.h (include Ntddscsi.h)