Error Handling

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

To facilitate the use of device managers across a variety of adapter device drivers this specification defines a set of error codes that should be supplied in the ErrorCode field of the IORB in the event of a failed operation. The adapter device driver is responsible for translating device error data into these error codes.

Use the following guidelines:

  • Do not program an adapter device driver defensively; that is, an adapter device driver should use the services of the device manager and not implement excessive safeguards. On the other hand, an adapter device driver must be protected against commands outside of its implemented command set to permit upward compatibility.
  • Program an adapter device driver to protect against timeouts and hung devices, transient environmental factors, noise, and so forth.
  • Ensure that the adapter device driver has the capability to properly process any scatter/gather list it receives.
  • Device error information must be translated into the error codes listed in Summary of Error Codes for the OS/2 Device Manager.

Errors must be fully processed by the adapter device driver, as required by the DASD Device Manager. For example, using the IOERR_ADAPTER_REFER_TO_STATUS error code will result in incorrect operation.

  • For other device managers, the same error translation is recommended. If this translation does not produce a reliable error indication, the IOERR_ADAPTER_REFER_TO_STATUS code can be used.
  • An IOERR_RETRY flag is included on commands that must be retried by the adapter device driver. Device managers will ignore this flag because retries must be performed at the adapter device driver level. This flag must be ignored also if the device manager has set the IORB_DISABLE_RETRY bit in the IORB.
  • An IOCM_GET_UNIT_STATUS command is not expected to fail, regardless of the condition of the underlying devices.
  • The IOCM_GET_DEVICE_TABLE command addresses the entire adapter device driver rather than a specific unit; ALLOCATION checks should not be performed.

Summary of Error Codes

This section describes all the adapter device driver error codes. Upon abnormal termination of a direct call command, the adapter device driver sets the IORB_ERROR flag in the IORBH Status field, and sets the ErrorCode field in the IORBH with one of the error codes listed below. The error codes are grouped by error category. Where stated below, the adapter device driver is required to retry the function prior to returning the error code to the caller.

IOERR_CMD

This error category maps errors related to the IORB command an adapter device driver receives.

IOERR_CMD_NOT_SUPPORTED
This error indicates that the adapter device driver has not implemented the requested function, including commands that the adapter device driver does not understand.
IOERR_CMD_SYNTAX
This error indicates that the ADD has detected an inconsistency in the IORB that prevents successful execution of the requested function.
IOERR_CMD_SGLIST_BAD
This error indicates that the adapter device driver cannot accept the scatter/gather list passed, due to either a defect in the scatter/gather list (0-length segment) or an underlying hardware limitation.
IOERR_CMD_SW_RESOURCE
(retry required)
This error indicates that the adapter device driver could not perform the requested function due to the lack of a software resource (for example, buffer, selector, and so forth).
Note: The adapter device driver should attempt to recover from this condition (using a smaller buffer, for example) even if degraded performance results.
IOERR_CMD_ABORTED
This error is returned when an IOCM_ABORT is received for a device that is currently processing a command. This error code should be set regardless of SCSI sense datathat indicates a successful command completion.
IOERR_CMD_ADD_SOFTWARE_FAILURE
This error indicates that the adapter device driver has detected an internal consistency check that prevents it from executing the requested IORB.
IOERR_CMD_OS_SOFTWARE_FAILURE
This error indicates that the adapter device driver received an unexpected error return code from an operating system service. The adapter device driver might retry the operation, depending on the nature of the error.

IOERR_UNIT

This error category maps errors related to the condition of an addressed unit.

IOERR_UNIT_NOT_ALLOCATED
This error indicates that the unit has received an IORB command prior to being allocated. This error should be returned to all commands directed to a unit prior to its receiving an IOCM_ALLOCATE_UNIT command.
IOERR_UNIT_ALLOCATED
This error indicates that an attempt was made to allocate a unit that had been allocated previously. Normally, this error would be returned in response to IOCM_ALLOCATE_UNIT.
IOERR_UNIT_NOT_READY
This error indicates that a unit is unable to perform an otherwise valid operation, usually due to an unusual condition on a unit, such as incorrect spindle speed.
Note: The adapter device driver should not return this error as the result of normal start-up delays on devices.
IOERR_UNIT_PWR_OFF
As an option, the adapter device driver can return this error if it has access to backup configuration data (CMOS) indicating that a previously configured device is not available. If backup configuration data is not available, a powered-off unit normally would not appear in the Adapter Device Driver DEVICETABLE; thus, this error condition would not be possible.

IOERR_RBA

This error category pertains to problems accessing a relative block address (RBA) on a particular unit.

IOERR_RBA_ADDRESSING_ERROR (retry required)
This error indicates that the requested RBA could not be located. This could be due to a failure to find the appropriate address marks on a particular device.
IOERR_RBA_LIMIT
This error indicates that the specified RBA exceeded the allowable maximum for the media currently in the device.
IOERR_RBA_CRC_ERROR (retry required)
This error indicates that the RBA was found; however, the data requested could not be read successfully.

IOERR_MEDIA

This error category pertains to problems relating to the media in a drive.

IOERR_MEDIA_NOT_FORMATTED
This error indicates that the requested operation could not be performed since the media in the drive requires low-level formatting. This includes requests to determine media capacity (IOCM_GET_MEDIA_GEOMETRY), if such requests require formatted media.
IOERR_MEDIA_NOT_SUPPORTED
This error indicates that the drive detected media that it cannot support. If the adapter device driver or device cannot make this determination directly, an I/O error can be returned in lieu of this error.
IOERR_MEDIA_WRITE_PROTECT
This error indicates that either the media or the drive is Write protected or that the media is not writable.
IOERR_MEDIA_CHANGED
This error indicates that the media in the drive might have been changed (for example, removal and/or insertion of the media has been detected since the last operation on the device).
IOERR_MEDIA_NOT_PRESENT
This error indicates that the requested operation, requiring media in the drive, failed because media was not in the drive.

IOERR_ADAPTER

This error category pertains to errors that are related to or detected by the host adapter.

IOERR_ADAPTER_HOSTBUSCHECK
This error pertains to problems caused by the adapter's inability to communicate with the host CPU. These errors can include incorrect parity on data received from the host. Frequently these errors are of a severe enough nature to cause shutdown of the host system. In such cases, normal host bus management procedures take precedence over the reporting of this error.
IOERR_ADAPTER_DEVICEBUSCHECK (retry required)
This error pertains to problems caused by the adapter's inability to communicate with an attached device. These errors include incorrect parity on data received from the attached device or incorrect bus protocols. These errors are recoverable and should be retried.
IOERR_ADAPTER_OVERRUN (retry required)
This error indicates either that the host adapter has lost data from a device due to its buffers being filled faster than they can be emptied by the host CPU or that a device attempted to supply more data than was expected by the host adapter.
IOERR_ADAPTER_UNDERRUN (retry required)
This error indicates either that the host adapter was unable to supply data on demand to a device, which caused device operation to fail, or that a device was expecting more data than the adapter was programmed to supply.
IOERR_ADAPTER_DIAGFAIL
This error indicates that the host adapter detected an internal consistency check, preventing its continued operation. Based on the severity of the error, the adapter device driver may or may not retry the requested operation.
IOERR_ADAPTER_TIMEOUT (retry required)
This error indicates that the adapter device driver timeout for an adapter to respond has been exceeded. Normally, the device initiates a retry sequence if this error occurs.
IOERR_ADAPTER_DEVICE_TIMEOUT (retry required)
This error indicates the failure of a device to respond to the host adapter.
IOERR_ADAPTER_REQ_NOT_SUPPORTED
This error indicates that the requested operation or function is not supported by this adapter.
IOERR_ADAPTER_REFER_TO_STATUS
This error indicates that the reported error could not be classified. Additional information can be provided in the IORB StatusBlock field if requested by the device manager. The ADD should retry the operation unless the IORB_DISABLE_RETRY bit is set.
IOERR_ADAPTER_NONSPECIFIC (retry required)
This error should be reported when an ADD cannot classify an adapter-related error condition and an IORB StatusBlock value is not provided. If an IORB StatusBlock value is provided, IOERR_ADAPTER_REFER_TO_STATUS should be returned.

IOERR_DEVICE

This error category pertains to errors detected by and relating to devices connected to a host adapter.

IOERR_DEVICE_DEVICEBUSCHECK (retry required)
This error pertains to a problem in communications between a host adapter and a device that was detected by the device. This would include incorrect parity on data received by the host adapter or a breakdown in bus protocols between the device and the host adapter.
IOERR_DEVICE_REQ_NOT_SUPPORTED
This error indicates that the requested operation or function is not supported by this device.
IOERR_DEVICE_DIAGFAIL
This error indicates that the device detected an internal consistency check that prevents its correct operation. Depending on the severity of the problem, the ADD might or might not retry the operation.
IOERR_DEVICE_BUSY (retry required)
This error indicates that the device is busy and cannot accept the requested operation. This error includes, but is not limited to, SCSI Contingent Allegiance conditions.
IOERR_DEVICE_OVERRUN (retry required)
This error indicates either that the device has lost data due to its buffers being filled faster than they can be emptied by the host adapter or that the device attempted to supply more data than the host adapter could accept.
IOERR_DEVICE_UNDERRUN (retry required)
This error indicates either that the device was unable to obtain data on demand, which caused device operation to fail, or that device operation required more data than was supplied by the host adapter.
IOERR_DEVICE_RESET (retry required)
This error indicates that an unexpected device reset occurred that caused device operation to fail. The ADD should retry the failed operation and report this condition as a recovered error.
IOERR_DEVICE_NONSPECIFIC (retry required)
This error should be returned when the ADD cannot classify a device-related error and an IORB StatusBlock value was not supplied. If an IORB StatusBlock value is supplied, IOERR_ADAPTER_REFER_TO_STATUS should be returned.

IORB Status Block

The IORB Status Block allows an .ADD driver to provide additional information describing an error condition reported in the IORB ErrorCode field.

Currently, only ADD drivers controlling SCSI devices are required to return a StatusBlock when requested to do so. When an ADD driver does return a StatusBlock, it must set the IORB_REQ_STATUSBLOCK bit in the RequestControl flags to indicate that the StatusBlock has been updated.

SCSI Status Block Format (SCSI_STATUS_BLOCK)

Field Name C Type Length Description
Flags USHORT DW Flags
AdapterErrorCode USHORT DW Adapter related error code
TargetStatus UCHAR DB SCSI Target status
ResidualLength ULONG DD Residual byte count
AdapterDiagInfo UCHAR DB(8) Adapter specific info
ReqSenseLen USHORT DW Request Sense Data allocation
SenseData PSCSI_REQSENSE_DATA DD Request Sense Buffer pointer

Flags

Flags contain bit flags indicating the validity of other fields within the SCSI Status Block.

Flag Description
STATUS_SENSEDATA_VALID Set by the ADD driver to indicate that SCSI Sense Data was recovered from the target and placed in the buffer indicated by SenseData.
STATUS_RESIDUAL_VALID Set by the ADD driver to indicate that the target did not transfer the number of bytes requested. If set the ADD driver is required to return a correct ResidualCount.
STATUS_DIAGINFO_VALID Set by the ADD driver if it returned adapter specific diagnostic information.
STATUS_DISABLE_REQEST_SENSE Set by the client to indicate that the ADD driver must not issue a Request Sense Command to the target regardless of the SCSI status reported.

Note: (SCSI_DISABLE_REQUEST_SENSE 0x0008)

This is a proposed addition to the current ADD/DM specification to simplify the implementation of Device Managers which have clients that explicitly issue their own Request Sense operation. When this bit is set, the ADD driver will not be able to accurately determine an IORB ErrorCode. In this case, the ADD driver must return IOERR_DEVICE_NON_SPECIFIC in the IORB ErrorCode field if the target reports other than "GOOD" status.

AdapterErrorCode

An AdapterErrorCode indicates that an adapter related error condition occurred. For example, a SCSI operation which completed successfully but resulted in an adapter detected underrun/overrun would report this condition in this field. The error codes used are defined by the IOERR_* codes in the previous section. If no adapter error condition was detected, then this field must be cleared by the ADD driver.

Note: It is possible for a SCSI operation to fail, but this field would be zero. This would be the usual case for target generated error conditions.

Conversely, it is possible for a SCSI operation to succeed at the IORB level, for example, no IORB Error code reported, but this field would non- zero. This would be the case when the SCSI adapter detected an overrun/ underrun on an otherwise successful SCSI operation.

TargetStatus

TargetStatus indicates the SCSI status byte returned by the target during the SCSI status bus phase.

ResidualLength

ResidualLength indicates the difference between the requested data transfer length in the IORB and the actual number of bytes transferred by the target. This field must always be set to as a non-negative number. The specific error condition Overrun vs Underrun should be indicated by setting the appropriate error code in AdapterErrorCode. If the ADD driver is able to return an accurate ResidualLength, it must set the STATUS_RESIDUAL_VALID bit in the Flags field.

AdapterDiagInfo

The AdapterDiagInfo field consists of eight bytes the ADD supplier may use to report vendor specific information to assist in local problem determination. If this information is returned the ADD driver must set the bit STATUS_DIAGINFO_VALID in the Flags field.

ReqSenseLen

The ReqSenseLen field indicates the size of the SenseData buffer available. If the target indicates a SCSI status of CHECK_CONDITION then the ADD driver should issue a SCSI Request_Sense command with a data transfer length indicate by ReqSenseLen.

Note: ADD drivers are required to obtain Sense Data whether or not a Status Block is present. In the absence of a StatusBlock, this would usually be done using internal storage of the ADD driver.

However, if a status block is present, then the ADD driver must transfer no less than the number of bytes indicated by the ReqSenseLen field and provide this data in the SenseData buffer.

SenseData

The SenseData field points to a data buffer to receive SenseData returned by the SCSI target as a result of a REQUEST SENSE operation issued by the ADD driver.