USB Mass Storage Client Device Driver

A device can be opened in the Diagnostic mode only if the target device is not currently opened. If you open a device in the Diagnostic mode when the target device is already open, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES.

A device can be opened in the Exclusive Access mode only if the device is not currently open. If you open a device in the Exclusive Access mode and the device is already open, the subroutine returns a value of -1 and sets the errno global variable to a value of EBUSY. If the SC_DIAGNOSTIC flag is specified along with the SC_SINGLE flag, the device is placed in Diagnostic mode.

The DKIORDSE operation is provided for diagnostic use. It allows the limited use of the target device while operating in an active system environment. The arg parameter of the DKIORDSE operation contains the address of a sc_rdwrt structure. This structure is defined in the /usr/include/sys/scsi.h file.

The devinfo structure defines the maximum transfer size for a read operation. If you transfer more than the maximum limit, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL.

The SCSI status byte and the adapter status bytes are returned through the arg parameter that contains the address of a sc_iocmd structure, which is defined in the /usr/include/sys/scsi.h file. If the DKIOCMD operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller must evaluate the returned status bytes to determine the cause of operation failure and the recovery actions.

The devinfo structure defines the maximum transfer size for the command. If you transfer more than the maximum value, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL.

    char sense_data[255];
    char *data_buffer=NULL;
    struct sc_iocmd sciocmd;
....

    fd = open("/dev/usbms0", O_RDWR);
    if (fd == -1){
        printf("\niocmd: Open FAIL\n");
        exit(-1);
    }

    memset(&sciocmd, '\0', sizeof(struct scsi_iocmd));
    sciocmd.version = SCSI_VERSION_1;
    sciocmd.timeout_value = 30;
    sciocmd.command_length = 6;
    sciocmd.flags = B_READ;
    sciocmd.autosense_length = 255;
    sciocmd.autosense_buffer_ptr = &sense_data[0];

    sciocmd.data_length = 0xFF;
    sciocmd.buffer = inq_data;
    sciocmd.scsi_cdb[0] = SCSI_INQUIRY;
    sciocmd.scsi_cdb[1] = 0x00; /* Standard Inquiry*/
    sciocmd.scsi_cdb[2] = 0x00;
    sciocmd.scsi_cdb[3] = 0x00;
    sciocmd.scsi_cdb[4] = 0xFF;
    sciocmd.scsi_cdb[5] = 0x00;

    if ((rc=ioctl(fd, DKIOCMD, &sciocmd)) != 0){
        printf("iocmd: Ioctl FAIL errno %d\n",errno);
        printf("status_validity: %x, scsi_status: %x, adapter_status:%x\n",
               sciocmd.status_validity, sciocmd.scsi_bus_status,
               sciocmd.adapter_status);
        hexdump(sense_data, (long)20);
        close(fd);
        exit(-1);
    } else {
        printf("cdiocmd : Ioctl PASS\n");
        if (cmd = SCSI_INQUIRY)
            hexdump(inq_data,0x20);
    }

    close(fd);

This ioctl operation is similar to the DKIOCMD16 operation that is used to issue 16-byte SCSI commands to the USB mass storage device.

The SCSI status byte and the adapter status bytes are returned through the arg parameter that contains the address of a sc_iocmd16cdb structure. This structure is defined in the /usr/include/sys/scsi.h file. If the DKIOLCMD operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller must evaluate the returned status bytes to determine the cause of operation failure and the recovery actions.

On completion of the DKIOLCMD ioctl request, the residual field indicates the leftover data that the device did not fully satisfy for this request. On a successful completion, the residual field indicates that the device does not have all of the data that is requested or the device has less amount of data than requested. On a request failure, you must check the status_validity field to determine whether a valid SCSI bus problem exists. In this case, the residual field indicates the number of bytes that the device failed to complete for this request.

The devinfo structure defines the maximum transfer size for the command. If you transfer more than the maximum value, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL.

    char sense_data[255];
    char *data_buffer=NULL;
    struct sc_iocmd16cdb sciocmd;
....

    fd = open("/dev/usbms0", O_RDWR);
    if (fd == -1){
        printf("\niocmd: Open FAIL\n");
        exit(-1);
    }

    memset(&sciocmd, '\0', sizeof(struct scsi_iocmd));
    sciocmd.version = SCSI_VERSION_1;
    sciocmd.timeout_value = 30;
    sciocmd.command_length = 6;
    sciocmd.flags = B_READ;
    sciocmd.autosense_length = 255;
    sciocmd.autosense_buffer_ptr = &sense_data[0];

    sciocmd.data_length = 0xFF;
    sciocmd.buffer = inq_data;
    sciocmd.scsi_cdb[0] = SCSI_INQUIRY;
    sciocmd.scsi_cdb[1] = 0x00; /* Standard Inquiry*/
    sciocmd.scsi_cdb[2] = 0x00;
    sciocmd.scsi_cdb[3] = 0x00;
    sciocmd.scsi_cdb[4] = 0xFF;
    sciocmd.scsi_cdb[5] = 0x00;

    if ((rc=ioctl(fd, DKIOCMD, &sciocmd)) != 0){
        printf("iocmd: Ioctl FAIL errno %d\n",errno);
        printf("status_validity: %x, scsi_status: %x, adapter_status:%x\n",
               sciocmd.status_validity, sciocmd.scsi_bus_status,
               sciocmd.adapter_status);
        hexdump(sense_data, (long)20);
        close(fd);
        exit(-1);
    } else {
        printf("cdiocmd : Ioctl PASS\n");
        if (cmd = SCSI_INQUIRY)
            hexdump(inq_data,0x20);
    }

    close(fd);

The SCSI status byte and the adapter status bytes are returned through the arg parameter that contains the address of a sc_passthru structure. This structure is defined in the /usr/include/sys/scsi.h file. If the DK_PASSTHRU operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller must evaluate the returned status bytes to determine the cause of operation failure and the recovery actions.

If a DK_PASSTHRU operation fails because a field in the sc_passthru structure has an invalid value, the subroutine returns a value of -1 and set the errno global variable to EINVAL. The einval_arg field is set to the field number (starting with 1 for the version field) of the field that had an invalid value. A value of 0 for the einval_arg field indicates that no additional information about the failure is available.

On completion of the DK_PASSTHRU request, the residual field indicates the leftover data that the device did not fully satisfy for this request. On a successful completion, the residual field indicates that the device does not have all of the data that is requested or the device has less amount of data than requested. On a request failure, you must check the status_validity field to determine if a valid SCSI bus problem exists. In this case, the residual field indicates the number of bytes that the device failed to complete for this request.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum transfer size, the subroutine returns a value of -1, sets the errno global variable to a value of EINVAL, and sets the einval_arg field to a value of SC_PASSTHRU_INV_D_LEN. These values are defined in the /usr/include/sys/scsi.h file.

    char sense_data[255];
    char *data_buffer=NULL;
    struct sc_passthru sciocmd;
....

    fd = open("/dev/usbms0", O_RDWR);
    if (fd == -1){
        printf("\npassthru: Open FAIL\n");
        exit(-1);
    }

    memset(&sciocmd, '\0', sizeof(struct sc_passthru));
    sciocmd.version = SCSI_VERSION_1;
    sciocmd.timeout_value = 30;
    sciocmd.command_length = 6;
    sciocmd.autosense_length = 255;
    sciocmd.autosense_buffer_ptr = &sense_data[0];

    sciocmd.data_length = 0xFF;
    sciocmd.buffer = inq_data;

    sciocmd.flags = B_READ;

    sciocmd.scsi_cdb[0] = SCSI_INQUIRY;
    sciocmd.scsi_cdb[1] = 0x00; /* Standard Inquiry*/
    sciocmd.scsi_cdb[2] = 0x00;
    sciocmd.scsi_cdb[3] = 0x00;
    sciocmd.scsi_cdb[4] = 0xFF;
    sciocmd.scsi_cdb[5] = 0x00;

    if ((rc=ioctl(fd, DK_PASSTHRU, &sciocmd)) != 0){
        if (sciocmd.adap_set_flags & SC_AUTOSENSE_DATA_VALID) {
            /* look at sense data */
        } /* end SC_AUTOSENSE_DATA_VALID */

        printf("passthru: Ioctl FAIL errno %d\n",errno);
        printf("status_validity: %x, scsi_status: %x, adapter_status:%x\n",
               sciocmd.status_validity, sciocmd.scsi_bus_status,
               sciocmd.adapter_status);
        printf("Residual: %x\n", sciocmd.residual);
        exit(-1);
    } else {
        printf("passthru: Ioctl PASS\n");
        printf("status_validity: %x, scsi_status: %x, adapter_status:%x\n",
               sciocmd.status_validity, sciocmd.scsi_bus_status,
               sciocmd.adapter_status);
        printf("Residual: %x\n", sciocmd.residual);
        /* inq_data buffer has valid Standard Inquiry data */
    }

devinfo.devtype = DD_SCDISK;
devinfo.flags =(uchar)DF_RAND;
devinfo.devsubtype = 0x00;
devinfo.un.scdk.max_request = Maximum_transfer_supported_by_usbcd_driver;
devinfo.un.scdk.numblks = Largest_LBA_supported_by_device+1;
devinfo.un.scdk.blksize = Block_size_set_for_the_USB_Disk/Flash/RDX_Device;

devinfo.devtype = DD_CDROM;
devinfo.flags = (uchar)DF_RAND;
devinfo.devsubtype = 0x00;
devinfo.un.idecd.numblks = 
  Largest logical block addressing (LBA) supported by device + 1;
devinfo.un.idecd.blksize = Block size set for the USB Disk, flash, or RDX device;

The AT Attachment (ATA) status bytes and the ATA error bytes are returned through the arg parameter. This parameter contains the address of an ide_ata_passthru structure that is defined in the /usr/include/sys/ide.h file. If the IDEPASSTHRU operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller evaluates the returned status bytes to determine the cause of operation failure and the recovery actions.

If the IDEPASSTHRU operation fails, the device driver performs limited error recovery. If this operation fails because a field in the ide_ata_passthru structure has an invalid value, the subroutine returns a value of -1 and sets the errno global variable to EINVAL.

On successful completion of the IDEPASSTHRU request, the residual field indicates that the device does not have all of the data that is requested, or the device has less than the amount of data that is requested. If the IDEPASSTHRU request fails, the residual field indicates the number bytes that the device failed to complete for this request.

The following example code issues an SCSI inquiry command that uses the IDEPASSTHRU operation:

    struct ide_atapi_passthru atapicmd;
    char inq_buffer[255];
    uchar sense_data[255];
 
    /* set up the arg parameter block */
    memset(&atapicmd, '\0', sizeof(struct ide_atapi_passthru));
    memset(sense_data, '\0', 255);

    atapicmd.ide_device = 0;
    atapicmd.flags = IDE_PASSTHRU_READ;
    atapicmd.timeout_value    = 30;
    atapicmd.rsv0             = IDE_PASSTHRU_VERSION_01;
    atapicmd.rsv1             = 0;
    atapicmd.atapi_cmd.length = 12;
    atapicmd.atapi_cmd.resvd  = 0;
    atapicmd.atapi_cmd.resvd1 = 0;
    atapicmd.atapi_cmd.resvd2 = 0;

    atapicmd.data_ptr = inq_buffer;
    atapicmd.buffsize = 0xFF;

    atapicmd.atapi_cmd.packet.opcode  = SCSI_INQUIRY;
    atapicmd.atapi_cmd.packet.byte[0] = (0x00 | vpd)  ;  /*Standard Inquiry */
    atapicmd.atapi_cmd.packet.byte[1] = page_code;  /*Page Code–Valid if vpd=1 */
    atapicmd.atapi_cmd.packet.byte[2] = 0x00;
    atapicmd.atapi_cmd.packet.byte[3] = 0xFF;
    atapicmd.atapi_cmd.packet.byte[4] = 0x00;

    atapicmd.sense_data        = sense_data;
    atapicmd.sense_data_length = 255;

    fd = openx(“/dev/cd0”, O_RDWR, NULL, SC_DIAGNOSTIC);
    if (fd == -1) {
         printf("IDEPASSTHRU: Openx failed with errno %x \n", errno);
         exit(-1);
    }

   if ((rc = ioctl(fd, IDEPASSTHRU, &atapicmd) != 0)) {
         printf("IDEPASSTHRU: IOCTL Failed");
         printf("errno %d\n",errno);
         printf("ata_status: %x, ata_error:%x\n",
                atapicmd.ata_status, atapicmd.ata_error);
         close(fd);
         exit(-1);
     } else {
         printf("IDEPASSTHRU : Ioctl PASS\n");
         printf("ata_status: %x, ata_error: %x\n",
                atapicmd.ata_status, atapicmd.ata_error);
     }
     close(fd);

If the DKAUDIO operation is attempted when the device's audio-supported attribute is set to No, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. If the DKAUDIO operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller must evaluate the returned status bytes to determine the cause of operation failure and recovery actions.

CD_GET_MODE

Returns the current CD-ROM data mode in the cd_mode_form field of the mode_form_op structure when the device is successfully opened.

CD_CHG_MODE

Changes the CD-ROM data mode to the mode that is specified in the cd_mode_form field of the mode_form_op structure when the device is successfully opened in the exclusive access mode.

If a CD-ROM is not configured for different data modes by using the mode-select density codes, and if you change the CD-ROM data mode by setting the action field of the change_mode_form structure to the CD_CHG_MODE command, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Attempts to change the CD-ROM mode to any of the DVD modes also results in a return value of -1 and the errno global variable is set to EINVAL. If the DK_CD_MODE operation for the CD_CHG_MODE command is attempted when the device is not in exclusive access mode, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES. For any other cause of operation failure, the subroutine returns a value of -1 and sets the errno global variable to a value of EIO.