6953d22b15
After FreeBSD SVN revision 236814, the pass(4) driver changed from
only doing error recovery when the CAM_PASS_ERR_RECOVER flag was
set on a CCB to sometimes doing error recovery if the passed in
retry count was non-zero.
Error recovery would happen if two conditions were met:
1. The error recovery action was simply a retry. (Which is most
cases.)
2. The retry_count is non-zero. (Which happened a lot because of
cut-and-pasted code.)
This explains a bug I noticed in with camcontrol:
# camcontrol tur da34 -v
Unit is ready
# camcontrol reset da34
Reset of 1:172:0 was successful
At this point, there should be a Unit Attention:
# camcontrol tur da34 -v
Unit is ready
No Unit Attention.
Try it again:
# camcontrol reset da34
Reset of 1:172:0 was successful
Now set the retry_count to 0 for the TUR:
# camcontrol tur da34 -v -C 0
Unit is not ready
(pass42:mps1:0:172:0): TEST UNIT READY. CDB: 00 00 00 00 00 00
(pass42:mps1:0:172:0): CAM status: SCSI Status Error
(pass42:mps1:0:172:0): SCSI status: Check Condition
(pass42:mps1:0:172:0): SCSI sense: UNIT ATTENTION asc:29,2 (SCSI bus reset occurred)
(pass42:mps1:0:172:0): Field Replaceable Unit: 2
There is the unit attention. camcontrol(8) has a default
retry_count of 1, in case someone sets the -E flag without
setting -C.
The CAM_PASS_ERR_RECOVER behavior was only broken with the
CAMIOCOMMAND ioctl, which is the synchronous pass(4) API. It has
worked as intended (error recovery is only done when the flag
is set) in the asynchronous API (CAMIOQUEUE ioctl).
sys/cam/scsi/scsi_pass.c:
In passsendccb(), when calling cam_periph_runccb(), only
specify the error routine when CAM_PASS_ERR_RECOVER is set.
share/man/man4/pass.4:
Document that CAM_PASS_ERR_RECOVER is needed to enable
error recovery.
Reported by: Terry Kennedy <TERRY@glaver.org>
PR: kern/218572
MFC after: 1 week
Sponsored by: Spectra Logic
243 lines
7.2 KiB
Groff
243 lines
7.2 KiB
Groff
.\"
|
|
.\" Copyright (c) 1998, 1999 Kenneth D. Merry.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 3, 2017
|
|
.Dt PASS 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pass
|
|
.Nd CAM application passthrough driver
|
|
.Sh SYNOPSIS
|
|
.Cd device pass
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides a way for userland applications to issue CAM CCBs to the
|
|
kernel.
|
|
.Pp
|
|
Since the
|
|
.Nm
|
|
driver allows direct access to the CAM subsystem, system administrators
|
|
should exercise caution when granting access to this driver.
|
|
If used
|
|
improperly, this driver can allow userland applications to crash a machine
|
|
or cause data loss.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver attaches to every
|
|
.Tn SCSI
|
|
and
|
|
.Tn ATA
|
|
device found in the system.
|
|
Since it attaches to every device, it provides a generic means of accessing
|
|
.Tn SCSI
|
|
and
|
|
.Tn ATA
|
|
devices, and allows the user to access devices which have no
|
|
"standard" peripheral driver associated with them.
|
|
.Sh KERNEL CONFIGURATION
|
|
It is only necessary to configure one
|
|
.Nm
|
|
device in the kernel;
|
|
.Nm
|
|
devices are automatically allocated as
|
|
.Tn SCSI
|
|
and
|
|
.Tn ATA
|
|
devices are found.
|
|
.Sh IOCTLS
|
|
.Bl -tag -width 5n
|
|
.It CAMIOCOMMAND union ccb *
|
|
This ioctl takes most kinds of CAM CCBs and passes them through to the CAM
|
|
transport layer for action.
|
|
Note that some CCB types are not allowed
|
|
through the passthrough device, and must be sent through the
|
|
.Xr xpt 4
|
|
device instead.
|
|
Some examples of xpt-only CCBs are XPT_SCAN_BUS,
|
|
XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC.
|
|
These CCB types have various attributes that make it illogical or
|
|
impossible to service them through the passthrough interface.
|
|
.Pp
|
|
If the user would like the kernel to do error recovery, the
|
|
.Dv CAM_PASS_ERR_RECOVER
|
|
flag must be set on the CCB, and the retry_count field set to the number
|
|
of retries.
|
|
.It CAMGETPASSTHRU union ccb *
|
|
This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device
|
|
corresponding to the device in question.
|
|
Although this ioctl is available through the
|
|
.Nm
|
|
driver, it is of limited use, since the caller must already know that
|
|
the device in question is a passthrough device if they are issuing this
|
|
ioctl.
|
|
It is probably more useful to issue this ioctl through the
|
|
.Xr xpt 4
|
|
device.
|
|
.It CAMIOQUEUE union ccb *
|
|
Queue a CCB to the
|
|
.Nm
|
|
driver to be executed asynchronously.
|
|
The caller may use
|
|
.Xr select 2 ,
|
|
.Xr poll 2
|
|
or
|
|
.Xr kevent 2
|
|
to receive notification when the CCB has completed.
|
|
.Pp
|
|
This ioctl takes most CAM CCBs, but some CCB types are not allowed through
|
|
the pass device, and must be sent through the
|
|
.Xr xpt 4
|
|
device instead.
|
|
Some examples of xpt-only CCBs are XPT_SCAN_BUS,
|
|
XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC.
|
|
These CCB types have various attributes that make it illogical or
|
|
impossible to service them through the passthrough interface.
|
|
.Pp
|
|
Although the
|
|
.Dv CAMIOQUEUE
|
|
ioctl is not defined to take an argument, it does require a
|
|
pointer to a union ccb.
|
|
It is not defined to take an argument to avoid an extra malloc and copy
|
|
inside the generic
|
|
.Xr ioctl 2
|
|
handler.
|
|
.Pp
|
|
The completed CCB will be returned via the
|
|
.Dv CAMIOGET
|
|
ioctl.
|
|
An error will only be returned from the
|
|
.Dv CAMIOQUEUE
|
|
ioctl if there is an error allocating memory for the request or copying
|
|
memory from userland.
|
|
All other errors will be reported as standard CAM CCB status errors.
|
|
Since the CCB is not copied back to the user process from the pass driver
|
|
in the
|
|
.Dv CAMIOQUEUE
|
|
ioctl, the user's passed-in CCB will not be modfied.
|
|
This is the case even with immediate CCBs.
|
|
Instead, the completed CCB must be retrieved via the
|
|
.Dv CAMIOGET
|
|
ioctl and the status examined.
|
|
.Pp
|
|
Multiple CCBs may be queued via the
|
|
.Dv CAMIOQUEUE
|
|
ioctl at any given time, and they may complete in a different order than
|
|
the order that they were submitted.
|
|
The caller must take steps to identify CCBs that are queued and completed.
|
|
The
|
|
.Dv periph_priv
|
|
structure inside struct ccb_hdr is available for userland use with the
|
|
.Dv CAMIOQUEUE
|
|
and
|
|
.Dv CAMIOGET
|
|
ioctls, and will be preserved across calls.
|
|
Also, the periph_links linked list pointers inside struct ccb_hdr are
|
|
available for userland use with the
|
|
.Dv CAMIOQUEUE
|
|
and
|
|
.Dv CAMIOGET
|
|
ioctls and will be preserved across calls.
|
|
.Pp
|
|
If the user would like the kernel to do error recovery, the
|
|
.Dv CAM_PASS_ERR_RECOVER
|
|
flag must be set on the CCB, and the retry_count field set to the number
|
|
of retries.
|
|
.It CAMIOGET union ccb *
|
|
Retrieve completed CAM CCBs queued via the
|
|
.Dv CAMIOQUEUE
|
|
ioctl.
|
|
An error will only be returned from the
|
|
.Dv CAMIOGET
|
|
ioctl if the
|
|
.Nm
|
|
driver fails to copy data to the user process or if there are no completed
|
|
CCBs available to retrieve.
|
|
If no CCBs are available to retrieve,
|
|
errno will be set to
|
|
.Dv ENOENT .
|
|
.Pp
|
|
All other errors will be reported as standard CAM CCB status errors.
|
|
.Pp
|
|
Although the
|
|
.Dv CAMIOGET
|
|
ioctl is not defined to take an argument, it does require a
|
|
pointer to a union ccb.
|
|
It is not defined to take an argument to avoid an extra malloc and copy
|
|
inside the generic
|
|
.Xr ioctl 2
|
|
handler.
|
|
.Pp
|
|
The pass driver will report via
|
|
.Xr select 2 ,
|
|
.Xr poll 2
|
|
or
|
|
.Xr kevent 2
|
|
when a CCB has completed.
|
|
One CCB may be retrieved per
|
|
.Dv CAMIOGET
|
|
call.
|
|
CCBs may be returned in an order different than the order they were
|
|
submitted.
|
|
So the caller should use the
|
|
.Dv periph_priv
|
|
area inside the CCB header to store pointers to identifying information.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/passn -compact
|
|
.It Pa /dev/pass Ns Ar n
|
|
Character device nodes for the
|
|
.Nm
|
|
driver.
|
|
There should be one of these for each device accessed through the
|
|
CAM subsystem.
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
None.
|
|
.Sh SEE ALSO
|
|
.Xr kqueue 2 ,
|
|
.Xr poll 2 ,
|
|
.Xr select 2 ,
|
|
.Xr cam 3 ,
|
|
.Xr cam_cdbparse 3 ,
|
|
.Xr cam 4 ,
|
|
.Xr cd 4 ,
|
|
.Xr ctl 4 ,
|
|
.Xr da 4 ,
|
|
.Xr sa 4 ,
|
|
.Xr xpt 4 ,
|
|
.Xr camcontrol 8 ,
|
|
.Xr camdd 8
|
|
.Sh HISTORY
|
|
The CAM passthrough driver first appeared in
|
|
.Fx 3.0 .
|
|
.Sh AUTHORS
|
|
.An Kenneth Merry Aq Mt ken@FreeBSD.org
|