Error notification

Proper handling of error conditions in drivers is essential to preserve the integrity of the operating system. A number of facilities are provided for reporting error conditions; see ``Error handling'' for a listing. Consider the following:

• Drivers should anticipate and react appropriately to any error condition that could arise. See ``Error handling''.

• Drivers should not generate unnecessary error messages. These can degrade system performance and obscure important error messages that are printed on the console or logged to system files.

• Production drivers should generate few error messages. In general, they should be silent except during initialization or when a serious error occurs.

• Any messages issued from a driver with the cmn_err(D3), cmn_err(D3oddi), mdi_printcfg(D3mdi), sdi_errmsg(D3sdi), or printcfg(D3oddi) function should be informative and as brief as possible. The text of each message should be preceded by a string that identifies the source file that generated the error. For example:

     cmn_err (CE_WARN, "mydriv.c: Fatal error reading device %x" , device);
  

• Informational messages used for tracing driver activity during the debugging process should be defined only for debugging kernel:

     #ifdef MY_DEBUG
     	cmn_err(CE_NOTE, " xxioctl routine called - device number = %x", device);
     #endif
  

  Note that MY_DEBUG is prefixed to avoid conflicts with other kernel modules. See ``Conditional compiler statements''.

• cmn_err( ) messages in production drivers that do not require immediate action by the administrator should use the ! format character so the message is not displayed on the console. The message will be written to the putbuf and appropriate log files.

• Drivers should not print out informational messages (such as copyright notification) from the driver's init( ), _load( ), or open( ) routine.

• Production drivers must never call cmn_err(D3) or cmn_err(D3oddi) with CE_PANIC as the first argument to panic the system.

  For debugging purposes, DDI 8 and later versions drivers should use the call_demon(D3) function to invoke the current kernel debugger at a specific point rather than panicking the system. ODDI 3 and later drivers can use the calldebug(D3oddi) function for the same purpose.

  For DDI versions prior to DDI 8 and ODDI versions prior to version 3, drivers may make cmn_err( ) calls with the CE_PANIC mode, but only in #ifdef DEBUG sections, which execute only for debugging. This practice is used to freeze the kernel so it can be analyzed with a kernel debugger.