1.\" 2.\" Copyright (c) 1998, 1999 Kenneth D. Merry. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. The name of the author may not be used to endorse or promote products 14.\" derived from this software without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd May 3, 2017 29.Dt PASS 4 30.Os 31.Sh NAME 32.Nm pass 33.Nd CAM application passthrough driver 34.Sh SYNOPSIS 35.Cd device pass 36.Sh DESCRIPTION 37The 38.Nm 39driver provides a way for userland applications to issue CAM CCBs to the 40kernel. 41.Pp 42Since the 43.Nm 44driver allows direct access to the CAM subsystem, system administrators 45should exercise caution when granting access to this driver. 46If used 47improperly, this driver can allow userland applications to crash a machine 48or cause data loss. 49.Pp 50The 51.Nm 52driver attaches to every 53.Tn SCSI 54and 55.Tn ATA 56device found in the system. 57Since it attaches to every device, it provides a generic means of accessing 58.Tn SCSI 59and 60.Tn ATA 61devices, and allows the user to access devices which have no 62"standard" peripheral driver associated with them. 63.Sh KERNEL CONFIGURATION 64It is only necessary to configure one 65.Nm 66device in the kernel; 67.Nm 68devices are automatically allocated as 69.Tn SCSI 70and 71.Tn ATA 72devices are found. 73.Sh IOCTLS 74.Bl -tag -width 5n 75.It CAMIOCOMMAND union ccb * 76This ioctl takes most kinds of CAM CCBs and passes them through to the CAM 77transport layer for action. 78Note that some CCB types are not allowed 79through the passthrough device, and must be sent through the 80.Xr xpt 4 81device instead. 82Some examples of xpt-only CCBs are XPT_SCAN_BUS, 83XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. 84These CCB types have various attributes that make it illogical or 85impossible to service them through the passthrough interface. 86.Pp 87If the user would like the kernel to do error recovery, the 88.Dv CAM_PASS_ERR_RECOVER 89flag must be set on the CCB, and the retry_count field set to the number 90of retries. 91.It CAMGETPASSTHRU union ccb * 92This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device 93corresponding to the device in question. 94Although this ioctl is available through the 95.Nm 96driver, it is of limited use, since the caller must already know that 97the device in question is a passthrough device if they are issuing this 98ioctl. 99It is probably more useful to issue this ioctl through the 100.Xr xpt 4 101device. 102.It CAMIOQUEUE union ccb * 103Queue a CCB to the 104.Nm 105driver to be executed asynchronously. 106The caller may use 107.Xr select 2 , 108.Xr poll 2 109or 110.Xr kevent 2 111to receive notification when the CCB has completed. 112.Pp 113This ioctl takes most CAM CCBs, but some CCB types are not allowed through 114the pass device, and must be sent through the 115.Xr xpt 4 116device instead. 117Some examples of xpt-only CCBs are XPT_SCAN_BUS, 118XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. 119These CCB types have various attributes that make it illogical or 120impossible to service them through the passthrough interface. 121.Pp 122Although the 123.Dv CAMIOQUEUE 124ioctl is not defined to take an argument, it does require a 125pointer to a union ccb. 126It is not defined to take an argument to avoid an extra malloc and copy 127inside the generic 128.Xr ioctl 2 129handler. 130.Pp 131The completed CCB will be returned via the 132.Dv CAMIOGET 133ioctl. 134An error will only be returned from the 135.Dv CAMIOQUEUE 136ioctl if there is an error allocating memory for the request or copying 137memory from userland. 138All other errors will be reported as standard CAM CCB status errors. 139Since the CCB is not copied back to the user process from the pass driver 140in the 141.Dv CAMIOQUEUE 142ioctl, the user's passed-in CCB will not be modified. 143This is the case even with immediate CCBs. 144Instead, the completed CCB must be retrieved via the 145.Dv CAMIOGET 146ioctl and the status examined. 147.Pp 148Multiple CCBs may be queued via the 149.Dv CAMIOQUEUE 150ioctl at any given time, and they may complete in a different order than 151the order that they were submitted. 152The caller must take steps to identify CCBs that are queued and completed. 153The 154.Dv periph_priv 155structure inside struct ccb_hdr is available for userland use with the 156.Dv CAMIOQUEUE 157and 158.Dv CAMIOGET 159ioctls, and will be preserved across calls. 160Also, the periph_links linked list pointers inside struct ccb_hdr are 161available for userland use with the 162.Dv CAMIOQUEUE 163and 164.Dv CAMIOGET 165ioctls and will be preserved across calls. 166.Pp 167If the user would like the kernel to do error recovery, the 168.Dv CAM_PASS_ERR_RECOVER 169flag must be set on the CCB, and the retry_count field set to the number 170of retries. 171.It CAMIOGET union ccb * 172Retrieve completed CAM CCBs queued via the 173.Dv CAMIOQUEUE 174ioctl. 175An error will only be returned from the 176.Dv CAMIOGET 177ioctl if the 178.Nm 179driver fails to copy data to the user process or if there are no completed 180CCBs available to retrieve. 181If no CCBs are available to retrieve, 182errno will be set to 183.Dv ENOENT . 184.Pp 185All other errors will be reported as standard CAM CCB status errors. 186.Pp 187Although the 188.Dv CAMIOGET 189ioctl is not defined to take an argument, it does require a 190pointer to a union ccb. 191It is not defined to take an argument to avoid an extra malloc and copy 192inside the generic 193.Xr ioctl 2 194handler. 195.Pp 196The pass driver will report via 197.Xr select 2 , 198.Xr poll 2 199or 200.Xr kevent 2 201when a CCB has completed. 202One CCB may be retrieved per 203.Dv CAMIOGET 204call. 205CCBs may be returned in an order different than the order they were 206submitted. 207So the caller should use the 208.Dv periph_priv 209area inside the CCB header to store pointers to identifying information. 210.El 211.Sh FILES 212.Bl -tag -width /dev/passn -compact 213.It Pa /dev/pass Ns Ar n 214Character device nodes for the 215.Nm 216driver. 217There should be one of these for each device accessed through the 218CAM subsystem. 219.El 220.Sh DIAGNOSTICS 221None. 222.Sh SEE ALSO 223.Xr kqueue 2 , 224.Xr poll 2 , 225.Xr select 2 , 226.Xr cam 3 , 227.Xr cam_cdbparse 3 , 228.Xr cam 4 , 229.Xr cd 4 , 230.Xr ctl 4 , 231.Xr da 4 , 232.Xr sa 4 , 233.Xr xpt 4 , 234.Xr camcontrol 8 , 235.Xr camdd 8 236.Sh HISTORY 237The CAM passthrough driver first appeared in 238.Fx 3.0 . 239.Sh AUTHORS 240.An Kenneth Merry Aq Mt ken@FreeBSD.org 241