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.\" $FreeBSD$ 29.\" 30.Dd May 3, 2017 31.Dt PASS 4 32.Os 33.Sh NAME 34.Nm pass 35.Nd CAM application passthrough driver 36.Sh SYNOPSIS 37.Cd device pass 38.Sh DESCRIPTION 39The 40.Nm 41driver provides a way for userland applications to issue CAM CCBs to the 42kernel. 43.Pp 44Since the 45.Nm 46driver allows direct access to the CAM subsystem, system administrators 47should exercise caution when granting access to this driver. 48If used 49improperly, this driver can allow userland applications to crash a machine 50or cause data loss. 51.Pp 52The 53.Nm 54driver attaches to every 55.Tn SCSI 56and 57.Tn ATA 58device found in the system. 59Since it attaches to every device, it provides a generic means of accessing 60.Tn SCSI 61and 62.Tn ATA 63devices, and allows the user to access devices which have no 64"standard" peripheral driver associated with them. 65.Sh KERNEL CONFIGURATION 66It is only necessary to configure one 67.Nm 68device in the kernel; 69.Nm 70devices are automatically allocated as 71.Tn SCSI 72and 73.Tn ATA 74devices are found. 75.Sh IOCTLS 76.Bl -tag -width 5n 77.It CAMIOCOMMAND union ccb * 78This ioctl takes most kinds of CAM CCBs and passes them through to the CAM 79transport layer for action. 80Note that some CCB types are not allowed 81through the passthrough device, and must be sent through the 82.Xr xpt 4 83device instead. 84Some examples of xpt-only CCBs are XPT_SCAN_BUS, 85XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. 86These CCB types have various attributes that make it illogical or 87impossible to service them through the passthrough interface. 88.Pp 89If the user would like the kernel to do error recovery, the 90.Dv CAM_PASS_ERR_RECOVER 91flag must be set on the CCB, and the retry_count field set to the number 92of retries. 93.It CAMGETPASSTHRU union ccb * 94This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device 95corresponding to the device in question. 96Although this ioctl is available through the 97.Nm 98driver, it is of limited use, since the caller must already know that 99the device in question is a passthrough device if they are issuing this 100ioctl. 101It is probably more useful to issue this ioctl through the 102.Xr xpt 4 103device. 104.It CAMIOQUEUE union ccb * 105Queue a CCB to the 106.Nm 107driver to be executed asynchronously. 108The caller may use 109.Xr select 2 , 110.Xr poll 2 111or 112.Xr kevent 2 113to receive notification when the CCB has completed. 114.Pp 115This ioctl takes most CAM CCBs, but some CCB types are not allowed through 116the pass device, and must be sent through the 117.Xr xpt 4 118device instead. 119Some examples of xpt-only CCBs are XPT_SCAN_BUS, 120XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. 121These CCB types have various attributes that make it illogical or 122impossible to service them through the passthrough interface. 123.Pp 124Although the 125.Dv CAMIOQUEUE 126ioctl is not defined to take an argument, it does require a 127pointer to a union ccb. 128It is not defined to take an argument to avoid an extra malloc and copy 129inside the generic 130.Xr ioctl 2 131handler. 132.Pp 133The completed CCB will be returned via the 134.Dv CAMIOGET 135ioctl. 136An error will only be returned from the 137.Dv CAMIOQUEUE 138ioctl if there is an error allocating memory for the request or copying 139memory from userland. 140All other errors will be reported as standard CAM CCB status errors. 141Since the CCB is not copied back to the user process from the pass driver 142in the 143.Dv CAMIOQUEUE 144ioctl, the user's passed-in CCB will not be modified. 145This is the case even with immediate CCBs. 146Instead, the completed CCB must be retrieved via the 147.Dv CAMIOGET 148ioctl and the status examined. 149.Pp 150Multiple CCBs may be queued via the 151.Dv CAMIOQUEUE 152ioctl at any given time, and they may complete in a different order than 153the order that they were submitted. 154The caller must take steps to identify CCBs that are queued and completed. 155The 156.Dv periph_priv 157structure inside struct ccb_hdr is available for userland use with the 158.Dv CAMIOQUEUE 159and 160.Dv CAMIOGET 161ioctls, and will be preserved across calls. 162Also, the periph_links linked list pointers inside struct ccb_hdr are 163available for userland use with the 164.Dv CAMIOQUEUE 165and 166.Dv CAMIOGET 167ioctls and will be preserved across calls. 168.Pp 169If the user would like the kernel to do error recovery, the 170.Dv CAM_PASS_ERR_RECOVER 171flag must be set on the CCB, and the retry_count field set to the number 172of retries. 173.It CAMIOGET union ccb * 174Retrieve completed CAM CCBs queued via the 175.Dv CAMIOQUEUE 176ioctl. 177An error will only be returned from the 178.Dv CAMIOGET 179ioctl if the 180.Nm 181driver fails to copy data to the user process or if there are no completed 182CCBs available to retrieve. 183If no CCBs are available to retrieve, 184errno will be set to 185.Dv ENOENT . 186.Pp 187All other errors will be reported as standard CAM CCB status errors. 188.Pp 189Although the 190.Dv CAMIOGET 191ioctl is not defined to take an argument, it does require a 192pointer to a union ccb. 193It is not defined to take an argument to avoid an extra malloc and copy 194inside the generic 195.Xr ioctl 2 196handler. 197.Pp 198The pass driver will report via 199.Xr select 2 , 200.Xr poll 2 201or 202.Xr kevent 2 203when a CCB has completed. 204One CCB may be retrieved per 205.Dv CAMIOGET 206call. 207CCBs may be returned in an order different than the order they were 208submitted. 209So the caller should use the 210.Dv periph_priv 211area inside the CCB header to store pointers to identifying information. 212.El 213.Sh FILES 214.Bl -tag -width /dev/passn -compact 215.It Pa /dev/pass Ns Ar n 216Character device nodes for the 217.Nm 218driver. 219There should be one of these for each device accessed through the 220CAM subsystem. 221.El 222.Sh DIAGNOSTICS 223None. 224.Sh SEE ALSO 225.Xr kqueue 2 , 226.Xr poll 2 , 227.Xr select 2 , 228.Xr cam 3 , 229.Xr cam_cdbparse 3 , 230.Xr cam 4 , 231.Xr cd 4 , 232.Xr ctl 4 , 233.Xr da 4 , 234.Xr sa 4 , 235.Xr xpt 4 , 236.Xr camcontrol 8 , 237.Xr camdd 8 238.Sh HISTORY 239The CAM passthrough driver first appeared in 240.Fx 3.0 . 241.Sh AUTHORS 242.An Kenneth Merry Aq Mt ken@FreeBSD.org 243