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.

       scsi_vu_errmsg()  interprets  the  request sense information in the sensep pointer and generates a standard message that is displayed 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

       scsi_vu_errmsg() may be called from user or interrupt 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.10							    2 Feb 1998							scsi_vu_errmsg(9F)