HDK Technical Reference

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 SVR5 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:

   	if (operation is successful);
   		return 0;
   		return ENOMEM;
Note that this error-reporting paradigm is quite different than that used in SCO OpenServer 5 and many other UNIX operating systems where errno values are returned to the calling process by directly setting the u.u_error member of the user structure or the b_error member of the buf(D4) structure. Code that attempts to access u.u_error will corrupt the SVR5 kernel.

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 and other administrative tools.

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

The following functions are used to handle error conditions:

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

Write error message to console, putbuf, or both

Retrieve error number from buffer header

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.

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

ODDI implementation

The SCO OpenServer 5 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.

© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005