share/man/man9f/scsi_vu_errmsg.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SCSI_VU_ERRMSG 9F "April 9, 2016"
   7 .SH NAME
   8 scsi_vu_errmsg \- display a SCSI request sense message
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14
  15
  16 \fBvoid\fR \fBscsi_vu_errmsg\fR(\fBstruct scsi_pkt\fR \fI*pktp\fR, \fBchar\fR \fI*drv_name\fR, \fBint severity,\fR
  17      \fBint err_blkno,\fR \fBstruct scsi_key_strings\fR \fI*cmdlist\fR,
  18      \fBstruct scsi_extended_sense\fR \fI*sensep\fR,
  19      \fBstruct scsi_asq_key_strings\fR \fI*asc_list\fR,
  20      \fBchar **decode_fru struct scsi_device\fR\fI*\fR, char \fI*\fR, int, char);
  21 .fi
  22
  23 .SH INTERFACE LEVEL
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .LP
  28 The following parameters are supported:
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIdevp\fR\fR
  33 .ad
  34 .RS 14n
  35 Pointer to the \fBscsi_device\fR(9S) structure.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIpktp\fR\fR
  42 .ad
  43 .RS 14n
  44 Pointer to a \fBscsi_pkt\fR(9S) structure.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIdrv_name\fR\fR
  51 .ad
  52 .RS 14n
  53 String used by \fBscsi_log\fR(9F).
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIseverity\fR\fR
  60 .ad
  61 .RS 14n
  62 Error severity level, maps to severity strings below.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIblkno\fR\fR
  69 .ad
  70 .RS 14n
  71 Requested block number.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIerr_blkno\fR\fR
  78 .ad
  79 .RS 14n
  80 Error block number.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fIcmdlist\fR\fR
  87 .ad
  88 .RS 14n
  89 An array of SCSI command description strings.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIsensep\fR\fR
  96 .ad
  97 .RS 14n
  98 A pointer to a \fBscsi_extended_sense\fR(9S) structure.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIasc_list\fR\fR
 105 .ad
 106 .RS 14n
 107 A pointer to a array of asc and ascq message list.The list must be terminated
 108 with \fB-1\fR asc value.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fIdecode_fru\fR\fR
 115 .ad
 116 .RS 14n
 117 This is a function pointer that will be called after the entire sense
 118 information has been decoded. The parameters will be the scsi_device structure
 119 to identify the device. Second argument will be a pointer to a buffer of length
 120 specified by third argument. The fourth argument will be the FRU byte.
 121 \fIdecode_fru\fR might be \fINULL\fR if no special decoding is required.
 122 \fIdecode_fru\fR is expected to return pointer to a char string if decoding
 123 possible and \fINULL\fR if no decoding is possible.
 124 .RE
 125
 126 .SH DESCRIPTION
 127 .LP
 128 This function is very similar to \fBscsi_errmsg\fR(9F) but allows decoding of
 129 vendor-unique ASC/ASCQ and FRU information.
 130 .sp
 131 .LP
 132 The \fBscsi_vu_errmsg()\fR function interprets the request sense information in
 133 the \fIsensep\fR pointer and generates a standard message that is displayed
 134 using \fBscsi_log\fR(9F). It first searches the list array for a matching
 135 vendor unique code if supplied. If it does not find one in the list then the
 136 standard list is searched. The first line of the message is always a
 137 \fBCE_WARN\fR, with the continuation lines being \fBCE_CONT\fR. \fIsensep\fR
 138 may be \fINULL\fR, in which case no sense key or vendor information is
 139 displayed.
 140 .sp
 141 .LP
 142 The driver should make the determination as to when to call this function based
 143 on the severity of the failure and the severity level that the driver wants to
 144 report.
 145 .sp
 146 .LP
 147 The \fBscsi_device\fR(9S) structure denoted by \fIdevp\fR supplies the
 148 identification of the device that requested the display. \fIseverity\fR selects
 149 which string is used in the Error Level: reporting, according to the table
 150 below:
 151 .sp
 152 .in +2
 153 .nf
 154      Severity Value:      String:
 155      SCSI_ERR_ALL         All
 156      SCSI_ERR_UNKNOWN     Unknown
 157      SCSI_ERR_INFO        Information
 158      SCSI_ERR_RECOVERED   Recovered
 159      SCSI_ERR_RETRYABLE   Retryable
 160      SCSI_ERR_FATAL       Fatal
 161 .fi
 162 .in -2
 163
 164 .sp
 165 .LP
 166 \fIblkno\fR is the block number of the original request that generated the
 167 error. \fIerr_blkno\fR is the block number where the error occurred.
 168 \fIcmdlist\fR is a mapping table for translating the SCSI command code in pktp
 169 to the actual command string.
 170 .sp
 171 .LP
 172 The \fIcmdlist\fR is described in the structure below:
 173 .sp
 174 .in +2
 175 .nf
 176 struct scsi_key_strings {
 177     int key;
 178     char *message;
 179 };
 180 .fi
 181 .in -2
 182
 183 .sp
 184 .LP
 185 For a basic SCSI disk, the following list is appropriate:
 186 .sp
 187 .in +2
 188 .nf
 189      static struct scsi_key_strings scsi_cmds[] = {
 190              0x00, "test unit ready",
 191              0x01, "rezero/rewind",
 192              0x03, "request sense",
 193              0x04, "format",
 194              0x07, "reassign",
 195              0x08, "read",
 196              0x0a, "write",
 197              0x0b, "seek",
 198              0x12, "inquiry",
 199              0x15, "mode select",
 200              0x16, "reserve",
 201              0x17, "release",
 202              0x18, "copy",
 203              0x1a, "mode sense",
 204              0x1b, "start/stop",
 205              0x1e, "door lock",
 206              0x28, "read(10)",
 207              0x2a, "write(10)",
 208              0x2f, "verify",
 209              0x37, "read defect data",
 210              0x3b, "write buffer",
 211              -1, NULL
 212      };
 213 .fi
 214 .in -2
 215
 216 .SH CONTEXT
 217 .LP
 218 The \fBscsi_vu_errmsg()\fR function may be called from user, interrupt, or
 219 kernel context.
 220 .SH EXAMPLES
 221 .LP
 222 \fBExample 1 \fRUsing \fBscsi_vu_errmsg()\fR
 223 .sp
 224 .in +2
 225 .nf
 226      struct scsi_asq_key_strings cd_slist[] = {
 227              0x81, 0, "Logical Unit is inaccessible",
 228              -1, 0, NULL,
 229      };
 230
 231
 232      scsi_vu_errmsg(devp, pkt, "sd",
 233                     SCSI_ERR_INFO, bp->b_blkno, err_blkno,
 234                     sd_cmds, rqsense, cd_list,
 235                     my_decode_fru);
 236 .fi
 237 .in -2
 238
 239 .sp
 240 .LP
 241 This generates the following console warning:
 242
 243 .sp
 244 .in +2
 245 .nf
 246 WARNING: /sbus@1,f8000000/esp@0,800000/sd@1,0 (sd1):
 247           Error for Command: read        Error Level: Informational
 248           Requested Block: 23936         Error Block: 23936
 249           Vendor: XYZ                Serial Number: 123456
 250           Sense Key:  Unit Attention
 251           ASC: 0x81 (Logical Unit is inaccessible), ASCQ: 0x0
 252           FRU: 0x11 (replace LUN 1, located in slot 1)
 253 .fi
 254 .in -2
 255
 256 .SH SEE ALSO
 257 .LP
 258 \fBcmn_err\fR(9F), \fBscsi_errmsg\fR(9F), \fBscsi_log\fR(9F),
 259 \fBscsi_errmsg\fR(9F), \fBscsi_asc_key_strings\fR(9S), \fBscsi_device\fR(9S),
 260 \fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S)
 261 .sp
 262 .LP
 263 \fIWriting Device Drivers\fR
 264 .sp
 265 .LP
 266 \fISTREAMS Programming Guide\fR