'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH TRAN_RESET 9E "Aug 17, 2005"
.SH NAME
tran_reset \- reset a SCSI bus or target
.SH SYNOPSIS
.nf
#include <sys/scsi/scsi.h>



\fB int prefix\fR\fBtran_reset\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIlevel\fR);
.fi

.SH INTERFACE LEVEL
illumos architecture specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIap\fR \fR
.ad
.RS 10n
Pointer to the \fBscsi_address\fR(9S) structure.
.RE

.sp
.ne 2
.na
\fB\fIlevel\fR \fR
.ad
.RS 10n
The level of reset required.
.RE

.SH DESCRIPTION
The \fBtran_reset()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must be
initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an
\fBHBA\fR entry point to be called when a target driver calls
\fBscsi_reset\fR(9F).
.sp
.LP
\fBtran_reset()\fR must reset either the \fBSCSI\fR bus, a \fBSCSI\fR target
device, or a \fBSCSI\fR logical unit as specified by \fIlevel\fR.
.sp
.LP
\fIlevel\fR must be one of the following:
.sp
.ne 2
.na
\fB\fBRESET_ALL\fR \fR
.ad
.RS 17n
Reset the \fBSCSI\fR bus.
.RE

.sp
.ne 2
.na
\fB\fBRESET_TARGET\fR \fR
.ad
.RS 17n
Reset the target specified by \fIap\fR.
.RE

.sp
.ne 2
.na
\fB\fBRESET_LUN\fR \fR
.ad
.RS 17n
Reset the logical unit specified by \fIap\fR.
.RE

.sp
.LP
\fBtran_reset\fR should set the \fBpkt_reason\fR field of all outstanding
packets in the transport layer associated with each target or logical unit that
was successfully reset to \fBCMD_RESET\fR and the \fBpkt_statistics\fR field
must be \fBOR\fR'ed with either \fBSTAT_BUS_RESET\fR (if the SCSI bus was
reset) or \fBSTAT_DEV_RESET\fR (if the target or logical unit was reset).
.sp
.LP
The \fBHBA\fR driver should use a \fBSCSI\fR Bus Device Reset Message to reset
a target device. The HBA driver should use a  SCSI Logical Unit Reset Message
to reset a logical unit.
.sp
.LP
Packets that are in the transport layer but not yet active on the bus should be
returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR and \fBpkt_statistics\fR
\fBOR\fR'ed with \fBSTAT_ABORTED\fR.
.sp
.LP
Support for \fBRESET_LUN\fR is optional but strongly encouraged for new and
updated HBA drivers. If an HBA driver provides \fBRESET_LUN\fR support, it must
also create the \fBlun-reset\fR capability with a value of zero for each target
device instance represented by a valid \fIap\fR. The HBA is also required to
provide the means to return the current value of the \fBlun-reset\fR capability
in its \fBtran_getcap\fR(9E) routine, as well as the means to change the value
of the \fBlun_reset\fR capability in its \fBtran_getcap\fR(9E) routine.
.SH RETURN VALUES
\fBtran_reset()\fR should return:
.sp
.ne 2
.na
\fB\fB1\fR \fR
.ad
.RS 6n
on success.
.RE

.sp
.ne 2
.na
\fB\fB0\fR \fR
.ad
.RS 6n
on failure.
.RE

.SH CONTEXT
The \fBtran_reset()\fR function can be called from user or interrupt context.
This requirement comes from \fBscsi_reset()\fR.
.SH SEE ALSO
\fBattach\fR(9E), \fBddi_dma_buf_setup\fR(9F), \fBscsi_hba_attach\fR(9F),
\fBscsi_reset\fR(9F), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
If \fBpkt_reason\fR already indicates that an earlier error had occurred for a
particular \fIpkt\fR, \fBtran_reset()\fR should not overwrite \fBpkt_reason\fR
with \fBCMD_RESET\fR.