diff options
Diffstat (limited to 'static/freebsd/man4/ch.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ch.4 3.html | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/static/freebsd/man4/ch.4 3.html b/static/freebsd/man4/ch.4 3.html new file mode 100644 index 00000000..e70095c2 --- /dev/null +++ b/static/freebsd/man4/ch.4 3.html @@ -0,0 +1,278 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CH(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">CH(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">ch</code> — <span class="Nd">SCSI + media-changer (juke box) 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 ch</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">ch</code> driver provides support for a + <i class="Em">SCSI</i> media changer. It allows many slots of media to be + multiplexed between a number of drives. The changer device may optionally be + equipped with a bar code reader, which reads label information attached to + the media.</p> +<p class="Pp">A SCSI adapter must also be separately configured into the system + before a SCSI changer can be configured.</p> +<p class="Pp" id="ch0">As the SCSI adapter is probed during boot, the + <i class="Em">SCSI</i> bus is scanned for devices. Any devices found which + answer as 'Changer' type devices will be 'attached' to the + <code class="Nm">ch</code> driver. In <span class="Ux">FreeBSD</span> + releases prior to 2.1, the first found will be attached as + <a class="permalink" href="#ch0"><i class="Em">ch0</i></a> and the next, + <a class="permalink" href="#ch1"><i class="Em" id="ch1">ch1</i></a> etc. + Beginning in 2.1 it is possible to specify what ch unit a device should come + on line as; refer to <a class="Xr">scsi(4)</a> for details on kernel + configuration.</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 explicitly configure one + <code class="Nm">ch</code> device; data structures are dynamically allocated + as media changes are found on the SCSI bus.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1> +<p class="Pp">User mode programs communicate with the changer driver through a + number of ioctls which are described below. Changer element addresses used + in the communication between the kernel and the changer device are mapped to + zero-based logical addresses. Element types are specified as follows:</p> +<dl class="Bl-tag"> + <dt id="CHET_MT"><a class="permalink" href="#CHET_MT"><code class="Dv">CHET_MT</code></a></dt> + <dd>Medium transport element (picker).</dd> + <dt id="CHET_ST"><a class="permalink" href="#CHET_ST"><code class="Dv">CHET_ST</code></a></dt> + <dd>Storage element (slot).</dd> + <dt id="CHET_IE"><a class="permalink" href="#CHET_IE"><code class="Dv">CHET_IE</code></a></dt> + <dd>Import/export element (portal).</dd> + <dt id="CHET_DT"><a class="permalink" href="#CHET_DT"><code class="Dv">CHET_DT</code></a></dt> + <dd>Data transfer element (drive).</dd> +</dl> +<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls apply to the + changer. They are defined in the header file + <code class="In"><<a class="In">sys/chio.h</a>></code>.</p> +<dl class="Bl-tag"> + <dt id="CHIOMOVE"><a class="permalink" href="#CHIOMOVE"><code class="Dv">CHIOMOVE</code></a></dt> + <dd>(<var class="Vt">struct changer_move</var>) Move a medium from one element + to another (<a class="permalink" href="#MOVE"><b class="Sy" id="MOVE">MOVE + MEDIUM</b></a>) using the current picker. The source and destination + elements are specified in a changer_move structure, which includes at + least the following fields: + <div class="Bd Pp Bd-indent Li"> + <pre>u_int cm_fromtype; /* element type to move from */ +u_int cm_fromunit; /* logical unit of from element */ +u_int cm_totype; /* element type to move to */ +u_int cm_tounit; /* logical unit of to element */ +u_int cm_flags; /* misc. flags */</pre> + </div> + If the <code class="Dv">CM_INVERT</code> in the + <var class="Va">cm_flags</var> field is set, the medium changer is + instructed to flip the medium while moving it.</dd> + <dt id="CHIOEXCHANGE"><a class="permalink" href="#CHIOEXCHANGE"><code class="Dv">CHIOEXCHANGE</code></a></dt> + <dd>(<var class="Vt">struct changer_exchange</var>) Move the medium located in + the source element to the first destination element, and move the medium + that had been in the first destination element to the second destination + element. In case of a simple exchange, the source and second destination + elements should be the same. The current picker is used to perform the + operation. The addresses of the affected elements is specified to the + ioctl in a <var class="Vt">changer_exchange</var> structure which includes + at least the following fields: + <div class="Bd Pp Bd-indent Li"> + <pre>u_int ce_srctype; /* element type of source */ +u_int ce_srcunit; /* logical unit of source */ +u_int ce_fdsttype; /* element type of first destination */ +u_int ce_fdstunit; /* logical unit of first destination */ +u_int ce_sdsttype; /* element type of second destination */ +u_int ce_sdstunit; /* logical unit of second destination */ +u_int ce_flags; /* misc. flags */</pre> + </div> + In <var class="Va">ce_flags</var>, <code class="Dv">CM_INVERT1</code> and/or + <code class="Dv">CM_INVERT2</code> may be set to flip the first or second + medium during the exchange operation, respectively. + <p class="Pp" id="This"><a class="permalink" href="#This"><i class="Em">This + operation is untested</i></a>.</p> + </dd> + <dt id="CHIOPOSITION"><a class="permalink" href="#CHIOPOSITION"><code class="Dv">CHIOPOSITION</code></a></dt> + <dd>(<var class="Vt">struct changer_position</var>) Position the current + picker in front of the specified element. The element is specified with a + changer_position structure, which includes at least the following + elements: + <div class="Bd Pp Bd-indent Li"> + <pre>u_int cp_type; /* element type */ +u_int cp_unit; /* logical unit of element */ +u_int cp_flags; /* misc. flags */</pre> + </div> + The <var class="Va">cp_flags</var> field may be set to + <code class="Dv">CP_INVERT</code> to invert the picker during the + operation.</dd> + <dt id="CHIOGPICKER"><a class="permalink" href="#CHIOGPICKER"><code class="Dv">CHIOGPICKER</code></a></dt> + <dd>(<var class="Vt">int</var>) Return the logical address of the current + picker.</dd> + <dt id="CHIOSPICKER"><a class="permalink" href="#CHIOSPICKER"><code class="Dv">CHIOSPICKER</code></a></dt> + <dd>(<var class="Vt">int</var>) Select the picker specified by the given + logical address.</dd> + <dt id="CHIOGPARAMS"><a class="permalink" href="#CHIOGPARAMS"><code class="Dv">CHIOGPARAMS</code></a></dt> + <dd>(<var class="Vt">struct changer_params</var>) Return the configuration + parameters for the media changer. This ioctl fills the changer_params + structure passed by the user with at least the following fields: + <div class="Bd Pp Bd-indent Li"> + <pre>u_int cp_npickers; /* number of pickers */ +u_int cp_nslots; /* number of slots */ +u_int cp_nportals; /* number of import/export portals */ +u_int cp_ndrives; /* number of drives */</pre> + </div> + <p class="Pp">This call can be used by applications to query the dimensions + of the jukebox before using the <code class="Dv">CHIGSTATUS</code> ioctl + to query the jukebox status.</p> + </dd> + <dt id="CHIOIELEM"><a class="permalink" href="#CHIOIELEM"><code class="Dv">CHIOIELEM</code></a></dt> + <dd>Perform the + <a class="permalink" href="#INITIALIZE"><b class="Sy" id="INITIALIZE">INITIALIZE + ELEMENT STATUS</b></a> call on the media changer device. This forces the + media changer to update its internal status information with respect to + loaded media. It also scans any barcode labels provided that it has a + label reader. The <code class="Nm">ch</code> driver's status is not + affected by this call.</dd> + <dt id="CHIOGSTATUS"><a class="permalink" href="#CHIOGSTATUS"><code class="Dv">CHIOGSTATUS</code></a></dt> + <dd>(<var class="Vt">struct changer_element_status_request</var>) Perform the + <a class="permalink" href="#READ"><b class="Sy" id="READ">READ ELEMENT + STATUS</b></a> call on the media changer device. This call reads the + element status information of the media changer and converts it to an + array of <var class="Vt">changer_element_status</var> structures. + <p class="Pp">With each call to <code class="Dv">CHIOGSTATUS</code>, the + status of one or more elements of one type may be queried.</p> + <p class="Pp">The application passes a + <var class="Vt">changer_element_status_request</var> structure to the + <code class="Nm">ch</code> driver which contains the following + fields:</p> + <div class="Bd Pp Bd-indent Li"> + <pre>u_int cesr_element_type; +u_int cesr_element_base; +u_int cesr_element_count; +u_int cesr_flags; +struct changer_element_status *cesr_element_status;</pre> + </div> + <p class="Pp">This structure is read by the driver to determine the type, + logical base address and number of elements for which information is to + be returned in the array of <var class="Vt">changer_element_status</var> + structures pointed to by the <var class="Va">cesr_element_status</var> + field. The application must allocate enough memory for + <var class="Va">cesr_element_count</var> status structures (see below). + The <var class="Va">cesr_flags</var> can optionally be set to + <code class="Dv">CESR_VOLTAGS</code> to indicate that volume tag (bar + code) information is to be read from the jukebox and returned.</p> + <p class="Pp">The <var class="Va">cesr_element_base</var> and + <var class="Va">cesr_element_count</var> fields must be valid with + respect to the physical configuration of the changer. If they are not, + the <code class="Dv">CHIOGSTATUS</code> ioctl returns the + <code class="Er">EINVAL</code> error code.</p> + <p class="Pp">The information about the elements is returned in an array of + <var class="Vt">changer_element_status</var> structures. This structure + include at least the following fields:</p> + <div class="Bd Pp Bd-indent Li"> + <pre>u_int ces_addr; /* element address in media changer */ +u_char ces_flags; /* see CESTATUS definitions below */ +u_char ces_sensecode; /* additional sense code for element */ +u_char ces_sensequal; /* additional sense code qualifier */ +u_char ces_invert; /* invert bit */ +u_char ces_svalid; /* source address (ces_source) valid */ +u_short ces_source; /* source address of medium */ +changer_voltag_t ces_pvoltag; /* primary volume tag */ +changer_voltag_t ces_avoltag; /* alternate volume tag */ +u_char ces_idvalid; /* ces_scsi_id is valid */ +u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */ +u_char ces_lunvalid; /* ces_scsi_lun is valid */ +u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */</pre> + </div> + <p class="Pp">The <var class="Va">ces_addr</var> field contains the address + of the element in the coordinate system of the media changer. It is not + used by the driver, and should be used for diagnostic purposes only.</p> + <p class="Pp">The following flags are defined for the + <var class="Va">ces_flags</var> field:</p> + <dl class="Bl-tag"> + <dt id="CESTATUS_FULL"><a class="permalink" href="#CESTATUS_FULL"><code class="Dv">CESTATUS_FULL</code></a></dt> + <dd>A medium is present.</dd> + <dt id="CESTATUS_IMPEXP"><a class="permalink" href="#CESTATUS_IMPEXP"><code class="Dv">CESTATUS_IMPEXP</code></a></dt> + <dd>The medium has been deposited by the operator (and not by a + picker).</dd> + <dt id="CESTATUS_EXCEPT"><a class="permalink" href="#CESTATUS_EXCEPT"><code class="Dv">CESTATUS_EXCEPT</code></a></dt> + <dd>The element is in an exceptional state (e.g. invalid barcode label, + barcode not yet scanned).</dd> + <dt id="CESTATUS_ACCESS"><a class="permalink" href="#CESTATUS_ACCESS"><code class="Dv">CESTATUS_ACCESS</code></a></dt> + <dd>The element is accessible by the picker.</dd> + <dt id="CESTATUS_EXENAB"><a class="permalink" href="#CESTATUS_EXENAB"><code class="Dv">CESTATUS_EXENAB</code></a></dt> + <dd>The element supports medium export.</dd> + <dt id="CESTATUS_INENAB"><a class="permalink" href="#CESTATUS_INENAB"><code class="Dv">CESTATUS_INENAB</code></a></dt> + <dd>The element supports medium import.</dd> + </dl> + <p class="Pp">Note that not all flags are valid for all element types.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">This version of the <code class="Nm">ch</code> driver has been + tested with a DEC TZ875 (5 slot, one DLT drive) and a Breece Hill Q47 (60 + slot, four DLT drives, barcode reader).</p> +<p class="Pp">Many of the features the <code class="Nm">ch</code> driver + supports are not thoroughly tested due to the fact that the devices + available for testing do not support the necessary commands. This is true + for alternate volume tags, media flipping, import/export element handling, + multiple picker operation and other things.</p> +</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/ch[0-9]</span></dt> + <dd>device entries</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">If the media changer does not support features requested by the + <code class="Nm">ch</code> driver, it will produce both console error + messages and failure return codes to the ioctls described here.</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">chio(1)</a>, <a class="Xr">cam(4)</a>, + <a class="Xr">cd(4)</a>, <a class="Xr">da(4)</a>, + <a class="Xr">sa(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ch</code> driver appeared in + <span class="Ux">386BSD-0.1</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">ch</code> driver was written by + <span class="An">Jason R. Thorpe</span> + <<a class="Mt" href="mailto:thorpej@and.com">thorpej@and.com</a>> for + And Communications, <span class="Pa">http://www.and.com/</span>. It was + added to the system by <span class="An">Stefan Grefen</span> + <<a class="Mt" href="mailto:grefen@goofy.zdv.uni-mainz.de">grefen@goofy.zdv.uni-mainz.de</a>> + who apparently had such a device. It was ported to CAM by + <span class="An">Kenneth Merry</span> + <<a class="Mt" href="mailto:ken@FreeBSD.org">ken@FreeBSD.org</a>>. It + was updated to support volume tags by <span class="An">Hans Huebner</span> + <<a class="Mt" href="mailto:hans@artcom.de">hans@artcom.de</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 14, 1998</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |