share/man/man9f/scsi_ext_sense_fields.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_EXT_SENSE_FIELDS 9F "Jun 29, 2006"
   7 .SH NAME
   8 scsi_ext_sense_fields, scsi_sense_info_uint64, scsi_sense_cmdspecific_uint64 \-
   9 retrieve fields from SCSI sense data
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/scsi/scsi.h>
  14
  15
  16
  17 \fBvoid\fR \fBscsi_ext_sense_fields\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint *\fR\fIsense_buf_len\fR,
  18      \fBuint8_t **\fR\fIinformation\fR, \fBuint8_t **\fR\fIcmd_spec_info\fR, \fBuint8_t **\fR\fIfru_code\fR,
  19      \fBuint8_t **\fR\fIsk_specific\fR, \fBuint8_t **\fR\fIstream_flags\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBboolean_t\fR \fBscsi_sense_info_uint64\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint\fR \fIsense_buf_len\fR,
  25      \fBuint64_t *\fR\fIinformation\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBboolean_t\fR \fBscsi_sense_cmdspecific_uint64\fR(\fBuint8_t *\fR\fIsense_buffer\fR,
  31      \fBint\fR \fIsense_buf_len\fR, \fBuint64_t *\fR\fIcmd_spec_info\fR);
  32 .fi
  33
  34 .SH INTERFACE LEVEL
  35 .sp
  36 .LP
  37 Solaris DDI specific (Solaris DDI).
  38 .SH PARAMETERS
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIsense_buffer\fR\fR
  43 .ad
  44 .RS 17n
  45 Pointer to a buffer containing \fBSCSI\fR sense data. The sense data is
  46 expected in wire format starting at the response code. It can be in either a
  47 fixed or descriptor format.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIinformation\fR\fR
  54 .ad
  55 .RS 17n
  56 For \fBscsi_ext_sense_fields()\fR, this is a call-by-reference pointer to
  57 \fBuint8_t\fR. A pointer to the \fBINFORMATION\fR field in the sense data may
  58 be returned in this parameter.
  59 .sp
  60 The \fBscsi_sense_info_uint64()\fR function requires a pointer to
  61 \fBuint64_t\fR. The data in the information field is returned as a 64 bit
  62 integer. If the sense data information field is 32 bits, fixed format, the most
  63 significant 32-bits are \fB\fR0.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIcmd_spec_info\fR\fR
  70 .ad
  71 .RS 17n
  72 For \fBscsi_ext_sense_fields()\fR, this is a call-by-reference pointer to
  73 \fBuint8_t\fR. A pointer to the \fBCOMMAND_SPECIFIC INFORMATION\fR field in the
  74 sense data can be returned in this parameter.
  75 .sp
  76 The \fBscsi_sense_cmdspecific_uint64()\fR function requires a pointer to
  77 \fBuint64_t\fR. The data in the command specific information field is returned
  78 as a 64 bit integer. If the sense data command specific information field is 32
  79 bits, fixed format, the most significant 32-bits are \fB0\fR.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIfru_code\fR\fR
  86 .ad
  87 .RS 17n
  88 Call-by-reference pointer to \fBuint8_t\fR. A pointer to the \fBFIELD
  89 REPLACEABLE UNIT CODE\fR field in the sense data can be returned in this
  90 parameter.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fIsk_specific\fR\fR
  97 .ad
  98 .RS 17n
  99 Call-by-reference pointer to \fBuint8_t\fR. A pointer to the \fBSENSE KEY
 100 SPECIFIC\fR field in the sense data can be returned in this parameter.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIstream_flags\fR\fR
 107 .ad
 108 .RS 17n
 109 Call-by-reference pointer to \fBuint8_t\fR. A pointer to the byte containing
 110 the \fBILI\fR, \fBEOM\fR, and \fBFILEMARK\fR flags can be returned in this
 111 parameter.
 112 .RE
 113
 114 .SH DESCRIPTION
 115 .sp
 116 .LP
 117 The \fBscsi_ext_sense_fields()\fR function can be used to retrieve any of the
 118 extended sense data fields from a sense data buffer, regardless of whether the
 119 sense data is in fixed format or in descriptor format.
 120 .sp
 121 .LP
 122 The \fIinformation\fR, \fIcmd_spec_info\fR, \fIfru_code\fR, \fIsk_specific\fR,
 123 and \fIstream_specific\fR parameters are all call-by-reference output
 124 parameters. Each parameter corresponds to one or more of the extended sense
 125 data fields. Any of these parameters can be passed as \fINULL\fR if the caller
 126 is not interested in the associated data.
 127 .sp
 128 .LP
 129 If the requested data is present and valid for each output parameter, the
 130 pointer passed in is set to point to the relevant location in the sense buffer.
 131 If the data is not present or invalid, the pointer is set to \fINULL\fR. For
 132 example, a caller that requests a pointer to the information field would get
 133 \fINULL\fR when an information descriptor is not present for descriptor format
 134 sense data or when the valid bit is not set for fixed format sense data.
 135 .sp
 136 .LP
 137 The information and command specific information fields can be 4 bytes or 8
 138 bytes in length, depending on whether the sense data is in fixed or descriptor
 139 format respectively. Drivers can use \fBscsi_validate_sense\fR(9F) to determine
 140 the sense data format and, by extension, the length of the information and
 141 command specific information fields.
 142 .sp
 143 .LP
 144 A driver can determine whether integer data is included in the information or
 145 command specific information fields based on the \fBasc\fR and \fBascq\fR sense
 146 keys, such as the \fBLBA\fR of a failed disk request. The
 147 \fBscsi_sense_info_uint64()\fR function retrieves the contents of the
 148 information field as a 64 bit integer and the
 149 \fBscsi_sense_cmdspecific_uint64()\fR retrieves the command specific
 150 information field as a 64 bit integer.
 151 .sp
 152 .LP
 153 Drivers should use \fBscsi_validate_sense\fR(9F) to ensure that the sense
 154 buffer contains valid sense data.
 155 .SH RETURN VALUES
 156 .sp
 157 .LP
 158 The \fBscsi_sense_info_uint64()\fR function returns \fBTRUE\fR if the
 159 information field is present and valid. Otherwise it returns \fBFALSE\fR.
 160 .sp
 161 .LP
 162 The \fBscsi_sense_cmdspecific_uint64()\fR function returns \fBTRUE\fR if the
 163 command specific information field is present and valid. Otherwise it returns
 164 \fBFALSE\fR.
 165 .SH CONTEXT
 166 .sp
 167 .LP
 168 The \fBscsi_ext_sense_fields()\fR, \fBscsi_sense_info_uint64()\fR and
 169 \fBscsi_sense_cmdspecific_uint64()()\fR functions can be called from user or
 170 interrupt context.
 171 .SH SEE ALSO
 172 .sp
 173 .LP
 174 \fBscsi_find_sense_descr\fR(9F), \fBscsi_sense_asc\fR(9F),
 175 \fBscsi_sense_ascq\fR(9F), \fBscsi_sense_key\fR(9F),
 176 \fBscsi_validate_sense\fR(9F)