usr/src/man/man9e/tran_reset.9e

   1 '\" te
   2 .\" Copyright (c) 2005, 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 TRAN_RESET 9E "Aug 17, 2005"
   7 .SH NAME
   8 tran_reset \- reset a SCSI bus or target
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14
  15
  16 \fB int prefix\fR\fBtran_reset\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIlevel\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris architecture specific (Solaris DDI).
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIap\fR \fR
  28 .ad
  29 .RS 10n
  30 Pointer to the \fBscsi_address\fR(9S) structure.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIlevel\fR \fR
  37 .ad
  38 .RS 10n
  39 The level of reset required.
  40 .RE
  41
  42 .SH DESCRIPTION
  43 .sp
  44 .LP
  45 The \fBtran_reset()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must be
  46 initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an
  47 \fBHBA\fR entry point to be called when a target driver calls
  48 \fBscsi_reset\fR(9F).
  49 .sp
  50 .LP
  51 \fBtran_reset()\fR must reset either the \fBSCSI\fR bus, a \fBSCSI\fR target
  52 device, or a \fBSCSI\fR logical unit as specified by \fIlevel\fR.
  53 .sp
  54 .LP
  55 \fIlevel\fR must be one of the following:
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBRESET_ALL\fR \fR
  60 .ad
  61 .RS 17n
  62 Reset the \fBSCSI\fR bus.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBRESET_TARGET\fR \fR
  69 .ad
  70 .RS 17n
  71 Reset the target specified by \fIap\fR.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBRESET_LUN\fR \fR
  78 .ad
  79 .RS 17n
  80 Reset the logical unit specified by \fIap\fR.
  81 .RE
  82
  83 .sp
  84 .LP
  85 \fBtran_reset\fR should set the \fBpkt_reason\fR field of all outstanding
  86 packets in the transport layer associated with each target or logical unit that
  87 was successfully reset to \fBCMD_RESET\fR and the \fBpkt_statistics\fR field
  88 must be \fBOR\fR'ed with either \fBSTAT_BUS_RESET\fR (if the SCSI bus was
  89 reset) or \fBSTAT_DEV_RESET\fR (if the target or logical unit was reset).
  90 .sp
  91 .LP
  92 The \fBHBA\fR driver should use a \fBSCSI\fR Bus Device Reset Message to reset
  93 a target device. The HBA driver should use a  SCSI Logical Unit Reset Message
  94 to reset a logical unit.
  95 .sp
  96 .LP
  97 Packets that are in the transport layer but not yet active on the bus should be
  98 returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR and \fBpkt_statistics\fR
  99 \fBOR\fR'ed with \fBSTAT_ABORTED\fR.
 100 .sp
 101 .LP
 102 Support for \fBRESET_LUN\fR is optional but strongly encouraged for new and
 103 updated HBA drivers. If an HBA driver provides \fBRESET_LUN\fR support, it must
 104 also create the \fBlun-reset\fR capability with a value of zero for each target
 105 device instance represented by a valid \fIap\fR. The HBA is also required to
 106 provide the means to return the current value of the \fBlun-reset\fR capability
 107 in its \fBtran_getcap\fR(9E) routine, as well as the means to change the value
 108 of the \fBlun_reset\fR capability in its \fBtran_getcap\fR(9E) routine.
 109 .SH RETURN VALUES
 110 .sp
 111 .LP
 112 \fBtran_reset()\fR should return:
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fB1\fR \fR
 117 .ad
 118 .RS 6n
 119 on success.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB0\fR \fR
 126 .ad
 127 .RS 6n
 128 on failure.
 129 .RE
 130
 131 .SH CONTEXT
 132 .sp
 133 .LP
 134 The \fBtran_reset()\fR function can be called from user or interrupt context.
 135 This requirement comes from \fBscsi_reset()\fR.
 136 .SH SEE ALSO
 137 .sp
 138 .LP
 139 \fBattach\fR(9E), \fBddi_dma_buf_setup\fR(9F), \fBscsi_hba_attach\fR(9F),
 140 \fBscsi_reset\fR(9F), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S)
 141 .sp
 142 .LP
 143 \fIWriting Device Drivers\fR
 144 .SH NOTES
 145 .sp
 146 .LP
 147 If \fBpkt_reason\fR already indicates that an earlier error had occurred for a
 148 particular \fIpkt\fR, \fBtran_reset()\fR should not overwrite \fBpkt_reason\fR
 149 with \fBCMD_RESET\fR.