19 Error handling

Contents of this section

The functions open, ioctl, write and read can report errors. In this case their return value is -1 and the global variable errno is set to the error number (negative). The errno values are defined in /usr/include/errno.h. Possible negative values are:

Function | Error        | Description
=========|==============|=============================================
open     | -ENXIO       | not a valid device
         | -EACCES      | access mode is not read/write (O_RDWR)
         | -EBUSY       | device was requested for nonblocking access, 
         |              | but is busy now.
         | -ERESTARTSYS | this indicates an internal error. Try to 
         |              | make it reproducible and inform the SCSI 
         |              | channel (for details on bug reporting
         |              | see Drew Eckhardts SCSI-HOWTO).
ioctl    | -ENXIO       | not a valid device
read     | -EWOULDBLOCK | the device would block. Try again later.
write    | -EIO         | the length is too small (smaller than the 
         |              | generic header struct). Caution: Currently 
         |              | there is no overlength checking.
         | -EWOULDBLOCK | the device would block. Try again later.
         | -ERESTARTSYS | this indicates an internal error. Try to
         |              | make it reproducible and inform the SCSI
         |              | channel (for details on bug reporting
         |              | see Drew Eckhardts SCSI-HOWTO).
         | -ENOMEM      | memory required for this request could not be
         |              | allocated. Try later again unless you
         |              | exceeded the maximum transfer size (see above)

For read/write positive return values indicate as usual the amount of bytes that have been successfully transferred. This should equal the amount you requested.

19.1 Error status decoding

Furthermore a detailed reporting is done via the kernels hd_status and the devices reports in the sense_buffer (see section sec-sensebuff ) from the header structure.

The meaning of hd_status can be found in drivers/scsi/scsi.h: This unsigned int is composed out of different parts:

  lsb  |    ...    |    ...    | msb
=======|===========|===========|============
status | sense key | host code | driver byte

These macros from drivers/scsi/scsi.h can be used to separate the fields:

        Macro       | Description
====================|================================================
status_byte(result) | The SCSI device status. See above
msg_byte(result)    | The devices sense key. See above
host_byte(result)   | The host code from the kernel driver. See above
driver_byte(result) | The first byte from the device

19.2 Status codes

The following status codes from the SCSI device (defined in drivers/scsi/scsi.h) should be used with the macro status_byte (see section sec-stat-decoding ):

Value | Symbol
======|=====================
0x00  | GOOD
0x01  | CHECK_CONDITION
0x02  | CONDITION_GOOD
0x04  | BUSY
0x08  | INTERMEDIATE_GOOD
0x0a  | INTERMEDIATE_C_GOOD
0x0c  | RESERVATION_CONFLICT

Note that these symbol values have been shifted right once. From the SCSI-2 specification:


                           Table 27: Status Byte Code
+=================================-==============================+
|       Bits of Status Byte       |  Status                      |
|  7   6   5   4   3   2   1   0  |                              |
|---------------------------------+------------------------------|
|  R   R   0   0   0   0   0   R  |  GOOD                        |
|  R   R   0   0   0   0   1   R  |  CHECK CONDITION             |
|  R   R   0   0   0   1   0   R  |  CONDITION MET               |
|  R   R   0   0   1   0   0   R  |  BUSY                        |
|  R   R   0   1   0   0   0   R  |  INTERMEDIATE                |
|  R   R   0   1   0   1   0   R  |  INTERMEDIATE-CONDITION MET  |
|  R   R   0   1   1   0   0   R  |  RESERVATION CONFLICT        |
|  R   R   1   0   0   0   1   R  |  COMMAND TERMINATED          |
|  R   R   1   0   1   0   0   R  |  QUEUE FULL                  |
|                                 |                              |
|       All Other Codes           |  Reserved                    |
|----------------------------------------------------------------|
|  Key: R = Reserved bit                                         |
+================================================================+

A definition of the status byte codes is given below.

GOOD.  This status indicates that the target has successfully completed the
command.

CHECK CONDITION.  This status indicates that a contingent allegiance condition
has occurred (see 6.6).

CONDITION MET.  This status or INTERMEDIATE-CONDITION MET is returned whenever
the requested operation is satisfied (see the SEARCH DATA and PRE-FETCH
commands).

BUSY.  This status indicates that the target is busy.  This status shall be
returned whenever a target is unable to accept a command from an otherwise
acceptable initiator (i.e., no reservation conflicts).  The recommended
initiator recovery action is to issue the command again at a later time.

INTERMEDIATE.  This status or INTERMEDIATE-CONDITION MET shall be returned for
every successfully completed command in a series of linked commands (except
the last command), unless the command is terminated with CHECK CONDITION,
RESERVATION CONFLICT, or COMMAND TERMINATED status.  If INTERMEDIATE or
INTERMEDIATE-CONDITION MET status is not returned, the series of linked
commands is terminated and the I/O process is ended.

INTERMEDIATE-CONDITION MET.  This status is the combination of the CONDITION
MET and INTERMEDIATE statuses.

RESERVATION CONFLICT.  This status shall be returned whenever an initiator
attempts to access a logical unit or an extent within a logical unit that is
reserved with a conflicting reservation type for another SCSI device (see the
RESERVE and RESERVE UNIT commands).  The recommended initiator recovery action
is to issue the command again at a later time.

COMMAND TERMINATED.  This status shall be returned whenever the target
terminates the current I/O process after receiving a TERMINATE I/O PROCESS
message (see 5.6.22).  This status also indicates that a contingent allegiance
condition has occurred (see 6.6).

QUEUE FULL.  This status shall be implemented if tagged queuing is
implemented.  This status is returned when a SIMPLE QUEUE TAG, ORDERED QUEUE
TAG, or HEAD OF QUEUE TAG message is received and the command queue is full.
The I/O process is not placed in the command queue.

19.3 SCSI Sense Keys

The sense key from the result should be retrieved with the macro msg_byte (see section sec-stat-decoding ). These kernel symbols (from drivers/scsi/scsi.h) are predefined:

Value | Symbol
======|================
0x00  | NO_SENSE
0x01  | RECOVERED_ERROR
0x02  | NOT_READY
0x03  | MEDIUM_ERROR
0x04  | HARDWARE_ERROR
0x05  | ILLEGAL_REQUEST
0x06  | UNIT_ATTENTION
0x07  | DATA_PROTECT
0x08  | BLANK_CHECK
0x0a  | COPY_ABORTED
0x0b  | ABORTED_COMMAND
0x0d  | VOLUME_OVERFLOW
0x0e  | MISCOMPARE

A verbatim list from the SCSI-2 doc follows (from section 7.2.14.3):

                    Table 69: Sense Key (0h-7h) Descriptions
+========-====================================================================+
| Sense  |  Description                                                       |
|  Key   |                                                                    |
|--------+--------------------------------------------------------------------|
|   0h   |  NO SENSE.  Indicates that there is no specific sense key          |
|        |  information to be reported for the designated logical unit.  This |
|        |  would be the case for a successful command or a command that      |
|        |  received CHECK CONDITION or COMMAND TERMINATED status because one |
|        |  of the filemark, EOM, or ILI bits is set to one.                  |
|--------+--------------------------------------------------------------------|
|   1h   |  RECOVERED ERROR.  Indicates that the last command completed       |
|        |  successfully with some recovery action performed by the target.   |
|        |  Details may be determinable by examining the additional sense     |
|        |  bytes and the information field.  When multiple recovered errors  |
|        |  occur during one command, the choice of which error to report     |
|        |  (first, last, most severe, etc.) is device specific.              |
|--------+--------------------------------------------------------------------|
|   2h   |  NOT READY.  Indicates that the logical unit addressed cannot be   |
|        |  accessed.  Operator intervention may be required to correct this  |
|        |  condition.                                                        |
|--------+--------------------------------------------------------------------|
|   3h   |  MEDIUM ERROR.  Indicates that the command terminated with a non-  |
|        |  recovered error condition that was probably caused by a flaw in   |
|        |  the medium or an error in the recorded data.  This sense key may  |
|        |  also be returned if the target is unable to distinguish between a |
|        |  flaw in the medium and a specific hardware failure (sense key 4h).|
|--------+--------------------------------------------------------------------|
|   4h   |  HARDWARE ERROR.  Indicates that the target detected a non-        |
|        |  recoverable hardware failure (for example, controller failure,    |
|        |  device failure, parity error, etc.) while performing the command  |
|        |  or during a self test.                                            |
|--------+--------------------------------------------------------------------|
|   5h   |  ILLEGAL REQUEST.  Indicates that there was an illegal parameter in|
|        |  the command descriptor block or in the additional parameters      |
|        |  supplied as data for some commands (FORMAT UNIT, SEARCH DATA,     |
|        |  etc.).  If the target detects an invalid parameter in the command |
|        |  descriptor block, then it shall terminate the command without     |
|        |  altering the medium.  If the target detects an invalid parameter  |
|        |  in the additional parameters supplied as data, then the target may|
|        |  have already altered the medium.  This sense key may also indicate|
|        |  that an invalid IDENTIFY message was received (5.6.7).            |
|--------+--------------------------------------------------------------------|
|   6h   |  UNIT ATTENTION.  Indicates that the removable medium may have been|
|        |  changed or the target has been reset.  See 6.9 for more detailed  |
|        |  information about the unit attention condition.                   |
|--------+--------------------------------------------------------------------|
|   7h   |  DATA PROTECT.  Indicates that a command that reads or writes the  |
|        |  medium was attempted on a block that is protected from this       |
|        |  operation.  The read or write operation is not performed.         |
+=============================================================================+

                    Table 70: Sense Key (8h-Fh) Descriptions
+========-====================================================================+
| Sense  |  Description                                                       |
|  Key   |                                                                    |
|--------+--------------------------------------------------------------------|
|   8h   |  BLANK CHECK.  Indicates that a write-once device or a sequential- |
|        |  access device encountered blank medium or format-defined end-of-  |
|        |  data indication while reading or a write-once device encountered a|
|        |  non-blank medium while writing.                                   |
|--------+--------------------------------------------------------------------|
|   9h   |  Vendor Specific.  This sense key is available for reporting vendor|
|        |  specific conditions.                                              |
|--------+--------------------------------------------------------------------|
|   Ah   |  COPY ABORTED.  Indicates a COPY, COMPARE, or COPY AND VERIFY      |
|        |  command was aborted due to an error condition on the source       |
|        |  device, the destination device, or both.  (See 7.2.3.2 for        |
|        |  additional information about this sense key.)                     |
|--------+--------------------------------------------------------------------|
|   Bh   |  ABORTED COMMAND.  Indicates that the target aborted the command.  |
|        |  The initiator may be able to recover by trying the command again. |
|--------+--------------------------------------------------------------------|
|   Ch   |  EQUAL.  Indicates a SEARCH DATA command has satisfied an equal    |
|        |  comparison.                                                       |
|--------+--------------------------------------------------------------------|
|   Dh   |  VOLUME OVERFLOW.  Indicates that a buffered peripheral device has |
|        |  reached the end-of-partition and data may remain in the buffer    |
|        |  that has not been written to the medium.  A RECOVER BUFFERED DATA |
|        |  command(s) may be issued to read the unwritten data from the      |
|        |  buffer.                                                           |
|--------+--------------------------------------------------------------------|
|   Eh   |  MISCOMPARE.  Indicates that the source data did not match the data|
|        |  read from the medium.                                             |
|--------+--------------------------------------------------------------------|
|   Fh   |  RESERVED.                                                         |
+=============================================================================+

19.4 Hostcodes

The following host codes are defined in drivers/scsi/scsi.h. They are set by the kernel driver and should be used with the macro host_byte (see section sec-stat-decoding ):

Value | Symbol         | Description
======|================|========================================
0x00  | DID_OK         | No error
0x01  | DID_NO_CONNECT | Couldn't connect before timeout period
0x02  | DID_BUS_BUSY   | BUS stayed busy through time out period
0x03  | DID_TIME_OUT   | TIMED OUT for other reason
0x04  | DID_BAD_TARGET | BAD target
0x05  | DID_ABORT      | Told to abort for some other reason
0x06  | DID_PARITY     | Parity error
0x07  | DID_ERROR      | internal error
0x08  | DID_RESET      | Reset by somebody
0x09  | DID_BAD_INTR   | Got an interrupt we weren't expecting

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter