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  iden-
           tify  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  gen-
     erated  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  con-
     text.

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