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 March 17, 2015 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.It CAMGETPASSTHRU union ccb * 89This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device 90corresponding to the device in question. 91Although this ioctl is available through the 92.Nm 93driver, it is of limited use, since the caller must already know that 94the device in question is a passthrough device if they are issuing this 95ioctl. 96It is probably more useful to issue this ioctl through the 97.Xr xpt 4 98device. 99.It CAMIOQUEUE union ccb * 100Queue a CCB to the 101.Nm 102driver to be executed asynchronously. 103The caller may use 104.Xr select 2 , 105.Xr poll 2 106or 107.Xr kevent 2 108to receive notification when the CCB has completed. 109.Pp 110This ioctl takes most CAM CCBs, but some CCB types are not allowed through 111the pass device, and must be sent through the 112.Xr xpt 4 113device instead. 114Some examples of xpt-only CCBs are XPT_SCAN_BUS, 115XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. 116These CCB types have various attributes that make it illogical or 117impossible to service them through the passthrough interface. 118.Pp 119Although the 120.Dv CAMIOQUEUE 121ioctl is not defined to take an argument, it does require a 122pointer to a union ccb. 123It is not defined to take an argument to avoid an extra malloc and copy 124inside the generic 125.Xr ioctl 2 126handler. 127.Pp 128The completed CCB will be returned via the 129.Dv CAMIOGET 130ioctl. 131An error will only be returned from the 132.Dv CAMIOQUEUE 133ioctl if there is an error allocating memory for the request or copying 134memory from userland. 135All other errors will be reported as standard CAM CCB status errors. 136Since the CCB is not copied back to the user process from the pass driver 137in the 138.Dv CAMIOQUEUE 139ioctl, the user's passed-in CCB will not be modfied. 140This is the case even with immediate CCBs. 141Instead, the completed CCB must be retrieved via the 142.Dv CAMIOGET 143ioctl and the status examined. 144.Pp 145Multiple CCBs may be queued via the 146.Dv CAMIOQUEUE 147ioctl at any given time, and they may complete in a different order than 148the order that they were submitted. 149The caller must take steps to identify CCBs that are queued and completed. 150The 151.Dv periph_priv 152structure inside struct ccb_hdr is available for userland use with the 153.Dv CAMIOQUEUE 154and 155.Dv CAMIOGET 156ioctls, and will be preserved across calls. 157Also, the periph_links linked list pointers inside struct ccb_hdr are 158available for userland use with the 159.Dv CAMIOQUEUE 160and 161.Dv CAMIOGET 162ioctls and will be preserved across calls. 163.It CAMIOGET union ccb * 164Retrieve completed CAM CCBs queued via the 165.Dv CAMIOQUEUE 166ioctl. 167An error will only be returned from the 168.Dv CAMIOGET 169ioctl if the 170.Nm 171driver fails to copy data to the user process or if there are no completed 172CCBs available to retrieve. 173If no CCBs are available to retrieve, 174errno will be set to 175.Dv ENOENT . 176.Pp 177All other errors will be reported as standard CAM CCB status errors. 178.Pp 179Although the 180.Dv CAMIOGET 181ioctl is not defined to take an argument, it does require a 182pointer to a union ccb. 183It is not defined to take an argument to avoid an extra malloc and copy 184inside the generic 185.Xr ioctl 2 186handler. 187.Pp 188The pass driver will report via 189.Xr select 2 , 190.Xr poll 2 191or 192.Xr kevent 2 193when a CCB has completed. 194One CCB may be retrieved per 195.Dv CAMIOGET 196call. 197CCBs may be returned in an order different than the order they were 198submitted. 199So the caller should use the 200.Dv periph_priv 201area inside the CCB header to store pointers to identifying information. 202.El 203.Sh FILES 204.Bl -tag -width /dev/passn -compact 205.It Pa /dev/pass Ns Ar n 206Character device nodes for the 207.Nm 208driver. 209There should be one of these for each device accessed through the 210CAM subsystem. 211.El 212.Sh DIAGNOSTICS 213None. 214.Sh SEE ALSO 215.Xr kqueue 2 , 216.Xr poll 2 , 217.Xr select 2 , 218.Xr cam 3 , 219.Xr cam_cdbparse 3 , 220.Xr cam 4 , 221.Xr cd 4 , 222.Xr ctl 4 , 223.Xr da 4 , 224.Xr sa 4 , 225.Xr xpt 4 , 226.Xr camcontrol 8 , 227.Xr camdd 8 228.Sh HISTORY 229The CAM passthrough driver first appeared in 230.Fx 3.0 . 231.Sh AUTHORS 232.An Kenneth Merry Aq Mt ken@FreeBSD.org 233