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, 0 insertions, 167 deletions
diff --git a/static/freebsd/man4/pass.4 3.html b/static/freebsd/man4/pass.4 3.html deleted file mode 100644 index c2a062ec..00000000 --- a/static/freebsd/man4/pass.4 3.html +++ /dev/null @@ -1,167 +0,0 @@ -<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> |