usr/src/man/man9f/scsi_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_ERRMSG 9F "Jan 16, 2006"
   7 .SH NAME
   8 scsi_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_errmsg\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBstruct scsi_pkt *\fR\fIpktp\fR,
  17      \fBchar *\fR\fIdrv_name\fR, \fBint\fR \fIseverity\fR, \fBdaddr_t\fR \fIblkno\fR, \fBdaddr_t\fR \fIerr_blkno\fR,
  18      \fBstruct scsi_key_strings *\fR\fIcmdlist\fR, \fBstruct scsi_extended_sense *\fR\fIsensep\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIdevp\fR\fR
  30 .ad
  31 .RS 13n
  32 Pointer to the  \fBscsi_device\fR(9S) structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIpktp\fR\fR
  39 .ad
  40 .RS 13n
  41 Pointer to a \fBscsi_pkt\fR(9S) structure.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIdrv_name\fR\fR
  48 .ad
  49 .RS 13n
  50 String used by \fBscsi_log\fR(9F).
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIseverity\fR\fR
  57 .ad
  58 .RS 13n
  59 Error severity level, maps to severity strings below.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIblkno\fR\fR
  66 .ad
  67 .RS 13n
  68 Requested block number.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIerr_blkno\fR\fR
  75 .ad
  76 .RS 13n
  77 Error block number.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fIcmdlist\fR\fR
  84 .ad
  85 .RS 13n
  86 An array of \fBSCSI \fRcommand description strings.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fIsensep\fR\fR
  93 .ad
  94 .RS 13n
  95 A pointer to a \fBscsi_extended_sense\fR(9S) structure.
  96 .RE
  97
  98 .SH DESCRIPTION
  99 .sp
 100 .LP
 101 The \fBscsi_errmsg()\fR function interprets the request sense information in
 102 the \fIsensep\fR pointer and generates a standard message that is displayed
 103 using \fBscsi_log\fR(9F). The first line of the message is always a
 104 \fBCE_WARN\fR, with the continuation lines being \fBCE_CONT\fR. \fIsensep\fR
 105 may be \fINULL\fR, in which case no sense key or vendor information is
 106 displayed.
 107 .sp
 108 .LP
 109 The driver should make the determination as to when to call this function based
 110 on the severity of the failure and the severity level that the driver wants to
 111 report.
 112 .sp
 113 .LP
 114 The \fBscsi_device\fR(9S) structure denoted by \fIdevp\fR supplies the
 115 identification of the device that requested the display. \fIseverity\fR selects
 116 which string is used in the "Error Level:" reporting, according to the
 117 following table:
 118 .sp
 119
 120 .sp
 121 .TS
 122 c c c
 123 l l l .
 124 \fBSeverity Value:\fR   \fBString:\fR
 125 \fBSCSI_ERR_ALL\fR      \fBAll\fR
 126 \fBSCSI_ERR_UNKNOWN\fR  \fBUnknown\fR
 127 \fBSCSI_ERR_INFO\fR     \fBInformational\fR
 128 \fBSCSI_ERR_RECOVERE\fR \fBRecovered\fR
 129 \fBSCSI_ERR_RETRYABL\fR \fBRetryable\fR
 130 \fBSCSI_ERR_FATAL\fR    \fBFatal\fR
 131 .TE
 132
 133 .sp
 134 .LP
 135 \fIblkno\fR is the block number of the original request that generated the
 136 error. \fIerr_blkno\fR is the block number where the error occurred.
 137 \fIcmdlist\fR is a mapping table for translating the \fBSCSI \fRcommand code in
 138 \fIpktp\fR to the actual command string.
 139 .sp
 140 .LP
 141 The \fIcmdlist\fR is described in the structure below:
 142 .sp
 143 .in +2
 144 .nf
 145 struct scsi_key_strings {
 146         int key;
 147         char *message;
 148 };
 149 .fi
 150 .in -2
 151
 152 .sp
 153 .LP
 154 For a basic \fBSCSI\fR disk, the following list is appropriate:
 155 .sp
 156 .in +2
 157 .nf
 158 static struct scsi_key_strings scsi_cmds[] = {
 159         0x00, "test unit ready",
 160         0x01, "rezero/rewind",
 161         0x03, "request sense",
 162         0x04, "format",
 163         0x07, "reassign",
 164         0x08, "read",
 165         0x0a, "write",
 166         0x0b, "seek",
 167         0x12, "inquiry",
 168         0x15, "mode select",
 169         0x16, "reserve",
 170         0x17, "release",
 171         0x18, "copy",
 172         0x1a, "mode sense",
 173         0x1b, "start/stop",
 174         0x1e, "door lock",
 175         0x28, "read(10)",
 176         0x2a, "write(10)",
 177         0x2f, "verify",
 178         0x37, "read defect data",
 179         0x3b, "write buffer",
 180         -1, NULL
 181 };
 182 .fi
 183 .in -2
 184
 185 .SH CONTEXT
 186 .sp
 187 .LP
 188 The \fBscsi_errmsg()\fR function may be called from user, interrupt, or kernel
 189 context.
 190 .SH EXAMPLES
 191 .LP
 192 \fBExample 1 \fRGenerating error information.
 193 .sp
 194 .LP
 195 This entry:
 196
 197 .sp
 198 .in +2
 199 .nf
 200 scsi_errmsg(devp, pkt, "sd", SCSI_ERR_INFO, bp->b_blkno,
 201          err_blkno, sd_cmds, rqsense);
 202 .fi
 203 .in -2
 204
 205 .sp
 206 .LP
 207 Generates:
 208
 209 .sp
 210 .in +2
 211 .nf
 212 \fBWARNING: /sbus@1,f8000000/esp@0,800000/sd@1,0 (sd1):
 213 Error for Command: read Error Level: Informational
 214 Requested Block: 23936 Error Block: 23936
 215 Vendor: QUANTUM Serial Number: 123456
 216 Sense Key:  Unit Attention
 217 ASC: 0x29 (reset), ASCQ: 0x0, FRU: 0x0\fR
 218 .fi
 219 .in -2
 220
 221 .SH SEE ALSO
 222 .sp
 223 .LP
 224 \fBcmn_err\fR(9F), \fBscsi_log\fR(9F), \fBscsi_device\fR(9S),
 225 \fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S)
 226 .sp
 227 .LP
 228 \fIWriting Device Drivers\fR