diff options
Diffstat (limited to 'static/freebsd/man4/pass.4 3.html')
| -rw-r--r-- | static/freebsd/man4/pass.4 3.html | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/static/freebsd/man4/pass.4 3.html b/static/freebsd/man4/pass.4 3.html new file mode 100644 index 00000000..c2a062ec --- /dev/null +++ b/static/freebsd/man4/pass.4 3.html @@ -0,0 +1,167 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PASS(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">PASS(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">pass</code> — <span class="Nd">CAM + application passthrough driver</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">device pass</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">pass</code> driver provides a way for + userland applications to issue CAM CCBs to the kernel.</p> +<p class="Pp">Since the <code class="Nm">pass</code> 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.</p> +<p class="Pp">The <code class="Nm">pass</code> 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.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_CONFIGURATION"><a class="permalink" href="#KERNEL_CONFIGURATION">KERNEL + CONFIGURATION</a></h1> +<p class="Pp">It is only necessary to configure one <code class="Nm">pass</code> + device in the kernel; <code class="Nm">pass</code> devices are automatically + allocated as SCSI and ATA devices are found.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1> +<dl class="Bl-tag"> + <dt>CAMIOCOMMAND union ccb *</dt> + <dd>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 + <a class="Xr">xpt(4)</a> 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. + <p class="Pp">If the user would like the kernel to do error recovery, the + <code class="Dv">CAM_PASS_ERR_RECOVER</code> flag must be set on the + CCB, and the retry_count field set to the number of retries.</p> + </dd> + <dt>CAMGETPASSTHRU union ccb *</dt> + <dd>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 <code class="Nm">pass</code> 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 <a class="Xr">xpt(4)</a> + device.</dd> + <dt>CAMIOQUEUE union ccb *</dt> + <dd>Queue a CCB to the <code class="Nm">pass</code> driver to be executed + asynchronously. The caller may use <a class="Xr">select(2)</a>, + <a class="Xr">poll(2)</a> or <a class="Xr">kevent(2)</a> to receive + notification when the CCB has completed. + <p class="Pp">This ioctl takes most CAM CCBs, but some CCB types are not + allowed through the pass device, and must be sent through the + <a class="Xr">xpt(4)</a> 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.</p> + <p class="Pp">Although the <code class="Dv">CAMIOQUEUE</code> 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 <a class="Xr">ioctl(2)</a> handler.</p> + <p class="Pp">The completed CCB will be returned via the + <code class="Dv">CAMIOGET</code> ioctl. An error will only be returned + from the <code class="Dv">CAMIOQUEUE</code> 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 <code class="Dv">CAMIOQUEUE</code> ioctl, the user's passed-in CCB + will not be modified. This is the case even with immediate CCBs. + Instead, the completed CCB must be retrieved via the + <code class="Dv">CAMIOGET</code> ioctl and the status examined.</p> + <p class="Pp">Multiple CCBs may be queued via the + <code class="Dv">CAMIOQUEUE</code> 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 <code class="Dv">periph_priv</code> structure inside + struct ccb_hdr is available for userland use with the + <code class="Dv">CAMIOQUEUE</code> and <code class="Dv">CAMIOGET</code> + 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 <code class="Dv">CAMIOQUEUE</code> and + <code class="Dv">CAMIOGET</code> ioctls and will be preserved across + calls.</p> + <p class="Pp">If the user would like the kernel to do error recovery, the + <code class="Dv">CAM_PASS_ERR_RECOVER</code> flag must be set on the + CCB, and the retry_count field set to the number of retries.</p> + </dd> + <dt>CAMIOGET union ccb *</dt> + <dd>Retrieve completed CAM CCBs queued via the + <code class="Dv">CAMIOQUEUE</code> ioctl. An error will only be returned + from the <code class="Dv">CAMIOGET</code> ioctl if the + <code class="Nm">pass</code> 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 + <code class="Dv">ENOENT</code>. + <p class="Pp">All other errors will be reported as standard CAM CCB status + errors.</p> + <p class="Pp">Although the <code class="Dv">CAMIOGET</code> 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 <a class="Xr">ioctl(2)</a> handler.</p> + <p class="Pp">The pass driver will report via <a class="Xr">select(2)</a>, + <a class="Xr">poll(2)</a> or <a class="Xr">kevent(2)</a> when a CCB has + completed. One CCB may be retrieved per <code class="Dv">CAMIOGET</code> + call. CCBs may be returned in an order different than the order they + were submitted. So the caller should use the + <code class="Dv">periph_priv</code> area inside the CCB header to store + pointers to identifying information.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/dev/pass</span><var class="Ar">n</var></dt> + <dd>Character device nodes for the <code class="Nm">pass</code> driver. There + should be one of these for each device accessed through the CAM + subsystem.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">None.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">kqueue(2)</a>, <a class="Xr">poll(2)</a>, + <a class="Xr">select(2)</a>, <a class="Xr">cam(3)</a>, + <a class="Xr">cam_cdbparse(3)</a>, <a class="Xr">cam(4)</a>, + <a class="Xr">cd(4)</a>, <a class="Xr">ctl(4)</a>, <a class="Xr">da(4)</a>, + <a class="Xr">sa(4)</a>, <a class="Xr">xpt(4)</a>, + <a class="Xr">camcontrol(8)</a>, <a class="Xr">camdd(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The CAM passthrough driver first appeared in + <span class="Ux">FreeBSD 3.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Kenneth Merry</span> + <<a class="Mt" href="mailto:ken@FreeBSD.org">ken@FreeBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 3, 2017</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |