Error handling

Device drivers and other kernel-level code must properly return information about any error conditions that occur during execution. Error handling is one of the most important functions required in a device driver. Drivers must handle any error condition, or the consequences might be severe. For example, a stray interrupt should be a trivial event, but could panic the system if the driver is not prepared to handle it. A system panic can cause data corruption and interfere with the use of the system.

See ``Error notification'' for guideliness about reporting error conditions.

DDI implementation

On SCO UnixWare systems, each entry-point routine must be coded to return 0 to the calling process when it is successful or an error number from the list on the errnos(D5) manual page if a failure occurs. For example:

   xxopen();
   {
   	if (operation is successful);
   		return 0;
   	else
   		return ENOMEM;
   }

Drivers and other kernel-level code can use the cmn_err(D3) function to write a message to the console and/or the putbuf kernel buffer. All messages that are written to the console are also written to the /usr/adm/log/osmlog file. Messages that are written to the putbuf buffer can be viewed through crash(1M) and other administrative tools.

When an error occurs, the driver can do one or more of the following:

• Write the error condition to a structure so the system knows about it. For buffer I/O, the error is recorded in the buf(D4) structure.

• Retry the job. The error might be a transient problem. Some hardware device boards have retry capabilities; let these boards perform the retry. However, if the error is software related, the driver must decide how many times to retry.

• Ignore the error and continue.

• Report the error to a system error log. If the error is severe, take the faulty hardware out of service to minimize the damage and keep the system running more or less normally.

• Send a signal to the user process.

The following functions are used to handle error conditions:

bioerror(D3)

Store error number in a buffer header; used as an return value for the biostart(D2) and strategy(D2) routines.

cmn_err(D3)

Write error message to console, putbuf, or both

geterror(D3)

Retrieve error number from buffer header

proc_signal(D3)

Send signal to a single process

In code that executes only for debugging the driver, the following can be used for error conditions. The driver must have a #include <sys/debug.h> line and be compiled with the -DDEBUG flag to implement these:

call_demon(D3) (DDI 8 only)

Call the current debugger when debugging the driver.

cmn_err(D3) with CE_PANIC level

Panic the system so the kernel can be examined with a debugger.

ASSERT(D3)

Verify an assertion and panic the system if it fails so the kernel can be examined with a debugger.

ODDI implementation

The SCO OpenServer kernel provides a number of facilities for handling error conditions that may arise:

seterror(D3oddi)	populate u.u_error to notify user-level process of an error condition.
update b_errno	notify user-level process of an error condition during a block I/O data transfer.
printcfg(D3oddi)	display error messages during driver's init(D2oddi) routine. All drivers should use this function to issue a ``board not present'' message as well as any other serious configuration errors that occur when the driver is initialized.
print(D2oddi) routine	display message about errors that occur during the transfer of data by the strategy(D2oddi) routine for a block device. This is an obsolete method that is retained for backward compatibility; new drivers should use deverr(D3oddi) instead.
deverr(D3oddi)	display formatted message about errors that occur during the transfer of data by the strategy(D2oddi) routine for a block device.
pr_intr_adderr(D3oddi)	print message for error that occurs when dynamically registering an interrupt handler with add_intr_handler(D3oddi).
pr_intr_rmerr(D3oddi)	print message for error that occurs when dynamically removing an interrupt handler with remove_intr_handler(D3oddi).
strlog(D3str)	register an error message for a STREAMS-based driver.
cmn_err(D3oddi)	display error messages in other portions of driver.

 seterror(D3oddi)         populate u.u_error to notify user-level process of
                          an error condition.
 update  b_errno          notify user-level process of an error condition
                          during a block I/O data transfer.
 printcfg(D3oddi)         display error messages during driver's init(D2oddi)
                          routine.  All drivers should use this function to
                          issue a ``board not present'' message as well as
                          any other serious configuration errors that occur
                          when the driver is initialized.
 print(D2oddi) routine    display message about errors that occur during the
                          transfer of data by the strategy(D2oddi) routine
                          for a block device.  This is an obsolete method
                          that is retained for backward compatibility; new
                          drivers should use deverr(D3oddi) instead.
 deverr(D3oddi)           display formatted message about errors that occur
                          during the transfer of data by the strategy(D2oddi)
                          routine for a block device.
 pr_intr_adderr(D3oddi)   print message for error that occurs when
                          dynamically registering an interrupt handler with
                          add_intr_handler(D3oddi)
 pr_intr_rmerr(D3oddi)    print message for error that occurs when
                          dynamically removing an interrupt handler with
                          remove_intr_handler(D3oddi)
 strlog(D3str)            register an error message for a STREAMS-based
                          driver.
 cmn_err(D3oddi)          display error messages in other portions of driver.