| PASS(4) | Device Drivers Manual | PASS(4) |
pass — CAM
application passthrough driver
device pass
The pass driver provides a way for
userland applications to issue CAM CCBs to the kernel.
Since the pass 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.
The pass driver attaches to every SCSI and
ATA device found in the system. Since it attaches to every device, it
provides a generic means of accessing SCSI and ATA devices, and allows the
user to access devices which have no "standard" peripheral driver
associated with them.
It is only necessary to configure one pass
device in the kernel; pass devices are automatically
allocated as SCSI and ATA devices are found.
If the user would like the kernel to do error recovery, the
CAM_PASS_ERR_RECOVER flag must be set on the
CCB, and the retry_count field set to the number of retries.
pass 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 xpt(4)
device.pass driver to be executed
asynchronously. The caller may use select(2),
poll(2) or kevent(2) to receive
notification when the CCB has completed.
This ioctl takes most CAM CCBs, but some CCB types are not allowed through the pass device, and must be sent through the 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.
Although the 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 ioctl(2) handler.
The completed CCB will be returned via the
CAMIOGET ioctl. An error will only be returned
from the 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 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
CAMIOGET ioctl and the status examined.
Multiple CCBs may be queued via the
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 periph_priv structure inside
struct ccb_hdr is available for userland use with the
CAMIOQUEUE and 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 CAMIOQUEUE and
CAMIOGET ioctls and will be preserved across
calls.
If the user would like the kernel to do error recovery, the
CAM_PASS_ERR_RECOVER flag must be set on the
CCB, and the retry_count field set to the number of retries.
CAMIOQUEUE ioctl. An error will only be returned
from the CAMIOGET ioctl if the
pass 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
ENOENT.
All other errors will be reported as standard CAM CCB status errors.
Although the 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 ioctl(2) handler.
The pass driver will report via select(2),
poll(2) or kevent(2) when a CCB has
completed. One CCB may be retrieved per CAMIOGET
call. CCBs may be returned in an order different than the order they
were submitted. So the caller should use the
periph_priv area inside the CCB header to store
pointers to identifying information.
pass driver. There
should be one of these for each device accessed through the CAM
subsystem.None.
kqueue(2), poll(2), select(2), cam(3), cam_cdbparse(3), cam(4), cd(4), ctl(4), da(4), sa(4), xpt(4), camcontrol(8), camdd(8)
The CAM passthrough driver first appeared in FreeBSD 3.0.
Kenneth Merry <ken@FreeBSD.org>
| May 3, 2017 | Debian |