scsi_vu_errmsg(9F)					   Kernel Functions for Drivers 					scsi_vu_errmsg(9F)

NAME

       scsi_vu_errmsg - display a SCSI request sense message

SYNOPSIS

       #include <sys/scsi/scsi.h>

       void scsi_vu_errmsg(struct scsi_pkt *pktp, char *drv_name, int severity,
	    int err_blkno, struct scsi_key_strings *cmdlist,
	    struct scsi_extended_sense *sensep,
	    struct scsi_asq_key_strings *asc_list,
	    char **decode_fru struct scsi_device*, char *, int, char);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

PARAMETERS

       The following parameters are supported:

       devp	     Pointer to the scsi_device(9S) structure.

       pktp	     Pointer to a scsi_pkt(9S) structure.

       drv_name      String used by scsi_log(9F).

       severity      Error severity level, maps to severity strings below.

       blkno	     Requested block number.

       err_blkno     Error block number.

       cmdlist	     An array of SCSI command description strings.

       sensep	     A pointer to a scsi_extended_sense(9S) structure.

       asc_list      A pointer to a array of asc and ascq message list.The list must be terminated with -1 asc value.

       decode_fru    This  is  a  function pointer that will be called after the entire sense information has been decoded. The parameters will be
		     the scsi_device structure to identify the device. Second argument will be a pointer to a buffer of length specified by  third
		     argument.	The  fourth argument will be the FRU byte. decode_fru might be NULL if no special decoding is required. decode_fru
		     is expected to return pointer to a char string if decoding possible and NULL if no decoding is possible.

DESCRIPTION

       This function is very similar to scsi_errmsg(9F) but allows decoding of vendor-unique ASC/ASCQ and FRU information.

       The scsi_vu_errmsg() function interprets the request sense information in the sensep pointer and generates a standard message that is  dis-
       played  using  scsi_log(9F). It first searches the list array for a matching vendor unique code if supplied. If it does not find one in the
       list then the standard list is searched. The first line of the message is always a CE_WARN, with  the  continuation  lines  being  CE_CONT.
       sensep may be NULL, in which case no sense key or vendor information is displayed.

       The  driver should make the determination as to when to call this function based on the severity of the failure and the severity level that
       the driver wants to report.

       The scsi_device(9S) structure denoted by devp supplies the identification of the device that requested the display. severity selects  which
       string is used in the Error Level: reporting, according to the table below:

	      Severity Value:	   String:
	      SCSI_ERR_ALL	   All
	      SCSI_ERR_UNKNOWN	   Unknown
	      SCSI_ERR_INFO	   Information
	      SCSI_ERR_RECOVERED   Recovered
	      SCSI_ERR_RETRYABLE   Retryable
	      SCSI_ERR_FATAL	   Fatal

       blkno is the block number of the original request that generated the error. err_blkno is the block number where the error occurred. cmdlist
       is a mapping table for translating the SCSI command code in pktp to the actual command string.

       The cmdlist is described in the structure below:

	 struct scsi_key_strings {
	     int key;
	     char *message;
	 };

       For a basic SCSI disk, the following list is appropriate:

	      static struct scsi_key_strings scsi_cmds[] = {
		      0x00, "test unit ready",
		      0x01, "rezero/rewind",
		      0x03, "request sense",
		      0x04, "format",
		      0x07, "reassign",
		      0x08, "read",
		      0x0a, "write",
		      0x0b, "seek",
		      0x12, "inquiry",
		      0x15, "mode select",
		      0x16, "reserve",
		      0x17, "release",
		      0x18, "copy",
		      0x1a, "mode sense",
		      0x1b, "start/stop",
		      0x1e, "door lock",
		      0x28, "read(10)",
		      0x2a, "write(10)",
		      0x2f, "verify",
		      0x37, "read defect data",
		      0x3b, "write buffer",
		      -1, NULL
	      };

CONTEXT

       The scsi_vu_errmsg() function may be called from user, interrupt, or kernel context.

EXAMPLES

       Example 1 Using scsi_vu_errmsg()

	      struct scsi_asq_key_strings cd_slist[] = {
		      0x81, 0, "Logical Unit is inaccessable",
		      -1, 0, NULL,
	      };

	      scsi_vu_errmsg(devp, pkt, "sd",
			     SCSI_ERR_INFO, bp->b_blkno, err_blkno,
			     sd_cmds, rqsense, cd_list,
			     my_decode_fru);

       This generates the following console warning:

	 WARNING: /sbus@1,f8000000/esp@0,800000/sd@1,0 (sd1):
		   Error for Command: read	  Error Level: Informational
		   Requested Block: 23936	  Error Block: 23936
		   Vendor: XYZ		      Serial Number: 123456
		   Sense Key:  Unit Attention
		   ASC: 0x81 (Logical Unit is inaccessable), ASCQ: 0x0
		   FRU: 0x11 (replace LUN 1, located in slot 1)

SEE ALSO

       cmn_err(9F),  scsi_errmsg(9F),	scsi_log(9F),	scsi_errmsg(9F),   scsi_asc_key_strings(9S),   scsi_device(9S),   scsi_extended_sense(9S),
       scsi_pkt(9S)

       Writing Device Drivers

       STREAMS Programming Guide

SunOS 5.11							    16 Jan 2006 						scsi_vu_errmsg(9F)