Error Conditions for USB Mass Storage Client Device Driver

Possible errno values for ioctl, open, read, and write subroutines when you use the scsidisk device driver include the following values:

Value	Description
EACCES	Indicates one of the following conditions: An attempt was made to open a device that is currently open in the `Diagnostic` or `Exclusive Access` mode. An attempt was made to open a `Diagnostic` mode session on a device that is already open. You attempted to run a subroutine other than an `ioctl` or `close` subroutine while in `Diagnostic` mode. A `DKIOLCMD` operation was attempted on a device that is not in the `Diagnostic` mode. A `DK_CD_MODE` `ioctl` subroutine operation was attempted on a device that is not in the `Exclusive Access` mode.
EBUSY	Indicates one of the following conditions: An attempt was made to open a session in the `Exclusive Access` mode on a device that is already opened. The target device is reserved by another initiator.
EFAULT	Indicates an invalid user address.
EFORMAT	Indicates that the target device has unformatted media or the media is in an incompatible format.
EINPROGRESS	Indicates that a CD-ROM drive has a play-audio operation in progress.
EINVAL	Indicates one of the following circumstances: A `DKAUDIO` (play-audio) operation was attempted for a device that is not configured to use the SCSI-2 play-audio commands. The `read` or `write` subroutine supplied an `n`byte parameter that is not an even multiple of the block size. A sense data buffer length of greater than 255 bytes is not valid for a `DKIORDSE` `ioctl` subroutine operation. The data buffer length exceeded the maximum value that is defined in the `devinfo` structure for a `DKIORDSE` or `DKIOLCMD` `ioctl` subroutine operation. An unsupported `ioctl` subroutine operation was attempted. An attempt was made to configure a device that is still open. An invalid configuration command is provided. A `DKPMR` (prevent media removal), `DKAMR` (allow media removal), or `DKEJECT` (eject media) command was sent to a device that does not support removable media. A `DKEJECT` (eject media) command was sent to a device that currently has its media locked in the drive. The data buffer length exceeded the maximum value that is defined for a strategy operation.
EIO	Indicates one of the following circumstances: The target device cannot be located or is not responding. The target device indicates an unrecoverable hardware error.
EMEDIA	Indicates one of the following circumstances: The target device indicates an unrecoverable media error. The media was changed.
EMFILE	Indicates that an `open` operation was attempted for an adapter that already has the maximum permissible number of opened devices.
ENODEV	Indicates one of the following circumstances: An attempt was made to access an undefined device. An attempt was made to close an undefined device.
ENOTREADY	Indicates that there is no media in the drive.
ENXIO	Indicates one of the following circumstances: The `ioctl` subroutine supplied an invalid parameter. A `read` or `write` operation was attempted beyond the end of the hard disk.
EPERM	Indicates that the attempted subroutine requires appropriate authority.
ESTALE	Indicates that a read-only optical disk was ejected (without first being closed by the user) and then either reinserted or replaced with a second optical disk.
ETIMEDOUT	Indicates that an I/O operation exceeded the specified timer value.
EWRPROTECT	Indicates one of the following circumstances: An `open` operation that requires read/write mode was attempted on a read-only media. A `write` operation was attempted to a read-only media.

Reliability and serviceability information

USB hard disk, flash drive, RDX devices, CD-ROM drives, and read/write optical drives return the following errors:

Error	Description
ABORTED COMMAND	Indicates that the device ended the command.
ADAPTER ERRORS	Indicates that the adapter returned an error.
GOOD COMPLETION	Indicates that the command completed successfully.
HARDWARE ERROR	Indicates that an unrecoverable hardware failure occurred when the command was run or during a self-test.
ILLEGAL REQUEST	Indicates an invalid command or command parameter.
MEDIUM ERROR	Indicates that the command ended with an unrecoverable media error condition.
NOT READY	Indicates that the logical unit is offline or the media is missing.
RECOVERED ERROR	Indicates that the command was successful after some recovery was applied.
UNIT ATTENTION	Indicates that the device is reset or the power is turned on.

The fields that are defined in the error record template for hard disk, flash drive, RDX, CD-ROM, and read/write optical media errors are logged as per the following structure:

/* Bulk transfer cmd and status blocks */
typedef struct mstor_cbw {
    uint32_t cbw_signature;     /* Always "USBC" little endian */
    uint32_t cbw_tag;              /* Command identification  */
    fld32_t cbw_dlen;              /* Data length  */
    uchar cbw_flags;               /* Indicates data in or data out */
    uchar cbw_lun;                 /* Logical unit number, 0-15  */
    uchar cbw_cblen;               /* Significant bytes of the cmd blk */
    uchar cbw_cb[16];              /* Command block itself  */
    uchar cbw_rsvd;
} mstor_cbw_t;
 
/* For error logging */
struct mstor_err_rec {
    struct err_rec0 log;
    uint cmd_error;
    mstor_cbw_t cbw;
    char sense_data[128];
};
 
LABEL:          DISK_ERRx
IDENTIFIER:     xxxxxxxx
 
Date/Time:       Wed Aug  4 11:40:43 CDT 2010
Sequence Number: 80
Machine Id:      00000A2AD400
Node Id:         node10
Class:           H
Type:            PERM
Resource Name:   usbms0
Resource Class:  usbms
Resource Type:   0806500b
Location:        U78A5.001.WIH00AD-P1-T1-L1-L2-L3
 
Description
Probable Causes
User Causes
Failure Causes
 
SENSE DATA
1111 2222 2222 3333 3333 4444 4444 5566 LLCC CCCC CCCC CCCC CCCC CCCC CCCC CCCC
CCRR SSSS KKSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS
SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS
SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS
SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSSS SSOO SSNN
 
Data Representation Legend
--------------------------
   cmd_error              1    Command Error Value 
  (cmd_error values can be negative which are logged as 2's complement. 
   For these USB specific error values refer below or /usr/include/sys/usbdi.h.
  For error values which are positive Please refer to /usr/include/sys/errno.h file for error description)
 
Bulk transfer Command and Status Blocks
   cbw_signature         2    Always .USBC. in ASCII – “5553 4243”
   cbw_tag                  3    Command Identification
   cbw_dlen                4    Data Length
   cbw_flags               5    Indicates Data IN or OUT
   cbw_lun                  6    LUN Id
   cbw_cblen               L    CDB (Command Descriptor Bytes) length
   cbw_cb                  C    CDB – SCSI/ATAPI Command Set
   cbw_rsvd                R    Reserved
 
Sense data
   Sense data             S
   Sense key              K
   ASC                    c
   ASCQ                   q
   Driver Open Count      O
   Location               N   Device Driver log location

Error record values for media errors

Value	Description
Comment	Indicates hard disk, flash drive, RDX, CD-ROM, or read/write optical media error.
Class	Equals a value of `H` that indicates a hardware error.
Report	Equals a value of True that indicates this error must be included when an error report is generated.
Log	Equals a value of True that indicates an error log entry must be created when this error occurs.
Alert	Equals a value of False that indicates this error cannot have an alert.
Err_Type	Equals a value of Perm that indicates a permanent failure.
Err_Desc	Equals a value of 1312 that indicates a disk operation failure.
Prob_Causes	Equals a value of 5000 that indicates media.
User_Causes	Equals a value of 5100 that indicates the media is defective.
User_Actions	Equals the following values: 1601, which indicates the removable media must be replaced and tried again. 00E1, which instructs to perform problem determination procedures.
Inst_Causes	None.
Inst_Actions	None.
Fail_Causes	Equals the following values: 5000, which indicates a media failure. 6310, which indicates a disk drive failure.
Fail_Actions	Equals the following values: 1601, which indicates that the removable media must be replaced and tried again. 00E1, which instructs to perform problem determination procedures.
Detail_Data	Equals a value of 156, 11, HEX. This value indicates hexadecimal format. Note: The `Detail_Data` field in the `err_rec` structure contains the `mstor_err_rec` structure. The `err_rec` field is defined in the /usr/include/sys/errids.h file. The `Detail_Data` field follows the same legend as mentioned in the preceding structure example.

Refer to the Small Computer System Interface (SCSI) specifications for the format of the request-sense data for a particular device.

Error record values for hardware errors

The fields that are defined in the error record template for hard disk, CD-ROM, and read/write optical hardware errors and for hard-aborted command errors are listed in the following table:

Value	Description
Comment	Indicates hard disk, flash drive, RDX, CD-ROM, or read/write optical hardware error.
Class	Equals a value of H that indicates a hardware error.
Report	Equals a value of True that indicates this error must be included when an error report is generated.
Log	Equals a value of True that indicates an error log entry must be created when this error occurs.
Alert	Equals a value of False that indicates this error cannot be alerted.
Err_Type	Equals a value of Perm that indicates a permanent failure.
Err_Desc	Equals a value of 1312 that indicates a disk operation failure.
Prob_Causes	Equals a value of 6310 that indicates disk drive.
User_Causes	None.
User_Actions	None.
Inst_Causes	None.
Inst_Actions	None.
Fail_Causes	Equals the following values: 6310, which indicates a disk drive failure. 6330, which indicates a disk drive electronics failure.
Fail_Actions	Equals a value of 00E1 that indicates problem-determination procedures must be performed.
Detail_Data	Equals a value of 156, 11, HEX. This value indicates hexadecimal format. Note: The `Detail_Data` field in the `err_rec` structure contains the `mstor_err_rec` structure. The `err_rec` field is defined in the /usr/include/sys/errids.h file. It follows the same legend as mentioned in the preceding structure example.

Error record values for adapter-detected hardware failures

The following fields are defined in the error record template for hard disk, CD-ROM, and read/write optical media errors and for adapter-detected hardware errors:

Value	Description
Comment	Indicates adapter-detected hard disk, flash drive, RDX, CD-ROM, or read/write optical hardware failure.
Class	Equals a value of H that indicates a hardware error.
Report	Equals a value of True that indicates that this error must be included when an error report is generated.
Log	Equals a value of True that indicates that an error-log entry must be created when this error occurs.
Alert	Equals a value of False that indicates this error cannot be alerted.
Err_Type	Equals a value of Perm that indicates a permanent failure.
Err_Desc	Equals a value of 1312 that indicates a disk operation failure.
Prob_Causes	Equals the following values: 3452, which indicates a device cable failure 6310, which indicates a disk drive failure
User_Causes	None.
User_Actions	None.
Inst_Causes	None.
Inst_Actions	None.
Fail_Causes	Equals the following values: 3452, which indicates a storage device cable failure 6310, which indicates a disk drive failure 6330, which indicates a disk-drive electronics failure
Fail_Actions	Equals a value of 0000 that indicates that the problem-determination procedures must be performed.
Detail_Data	Equals a value of 156, 11, HEX. This value indicates hexadecimal format. Note: The `Detail_Data` field in the `err_rec` structure contains the `mstor_err_rec` structure. The `err_rec` field is defined in the /usr/include/sys/errids.h file. It follows the same legend as mentioned in the preceding structure example.

Error record values for recovered errors

The following fields are defined in the error record template for hard disk, CD-ROM, and read/write optical media recovered errors:

Item	Description
Comment	Indicates hard disk, CD-ROM, or read/write optical recovered error.
Class	Equals a value of H that indicates a hardware error.
Report	Equals a value of True that indicates this error must be included when an error report is generated.
Log	Equals a value of True that indicates an error log entry must be created when this error occurs.
Alert	Equal to a value of False that indicates this error cannot be alerted.
Err_Type	Equals a value of Temp that indicates a temporary failure.
Err_Desc	Equals a value of 1312 that indicates a physical volume operation failure.
Prob_Causes	Equals the following values: 5000, which indicates a media failure 6310, which indicates a disk drive failure
User_Causes	Equals a value of 5100 that indicates that the media is defective.
User_Actions	Equals the following values: 0000, which indicates that the problem-determination procedures must be performed 1601, which indicates that the removable media must be replaced and tried again
Inst_Causes	None.
Inst_Actions	None.
Fail_Causes	Equals the following values: 5000, which indicates a media failure 6310, which indicates a disk drive failure
Fail_Actions	Equals the following values: 1601, which indicates that the removable media must be replaced and tried again 00E1, which performs problem determination procedures
Detail_Data	Equals a value of 156, 11, HEX. This value indicates hexadecimal format. Note: The `Detail_Data` field in the `err_rec` structure contains the `mstor_err_rec` structure. The `err_rec` field is defined in the /usr/include/sys/errids.h file. It follows the same legend as other errors.

Error record values for unknown errors

The following fields are defined in the error record template for hard disk, CD-ROM, and read/write optical media unknown errors:

Value	Description
Comment	Indicates hard disk, CD-ROM, or read/write optical unknown failure.
Class	Equals a value of H that indicates a hardware error.
Report	Equals a value of True that indicates this error must be included when an error report is generated.
Log	Equals a value of True that indicates an error log entry must be created when this error occurs.
Alert	Equal to a value of False that indicates this error cannot be alerted.
Err_Type	Equals a value of Unkn that indicates the type of error is unknown.
Err_Desc	Equals a value of FE00 that indicates an undetermined error.
Prob_Causes	Equals the following values: 3300, which indicates an adapter failure 5000, which indicates a media failure 6310, which indicates a disk drive failure
User_Causes	None.
User_Actions	None.
Inst_Causes	None.
Inst_Actions	None.
Fail_Causes	Equals a value of FFFF that indicates the failure causes are unknown.
Fail_Actions	Equals the following values: 00E1, which performs problem determination procedures 1601, which indicates the removable media must be replaced and tried again
Detail_Data	Equals a value of 156, 11, HEX. This value indicates hexadecimal format. Note: The `Detail_Data` field in the `err_rec` structure contains the `mstor_err_rec` structure. The `err_rec` field is defined in the /usr/include/sys/errids.h file. It follows the same legend as other errors.

Special Files

The usbcd USB client device driver uses raw and block special files for its functions. The special files that are used by the usbcd device driver are listed by the type of device in the following table:

Table 1. Special files for the usbcd device driver
Device	Special file	Description
Hard disk, flash drive, RDX devices	/dev/rusbms0, /dev/rusbms1, ..., /dev/rusbms`n`	Provides an interface for USB client device drivers to access character (raw I/O access and control functions).
Hard disk, flash drive, RDX devices	/dev/usbms0, /dev/usbms1, ..., /dev/usbms`n`	Provides an interface for USB client device drivers to access block I/O.
CD-ROM, DVD-RAM, Blu-ray read-only devices:	/dev/rcd0, /dev/rcd1, ..., /dev/rcd`n`	Provides an interface for USB client device drivers to access character (raw I/O access and control functions).
CD-ROM, DVD-RAM, Blu-ray read-only devices:	/dev/cd0, /dev/cd1, ..., /dev/cd`n`	Provides an interface for USB client device drivers to access block I/O.

Note: The prefix r on a special file name indicates that the drive is accessed as a raw device rather than a block device. Performing raw I/O with a hard disk, flash drive, RDX, CD-ROM, or read/write optical drive requires all data transfers to be in multiples of the device block size. Also, all the lseek subroutines that are made to the raw device driver must result in a file pointer value that is a multiple of the device block size.