From cd882d0271d38457b76a7bb8572cda07d7416751 Mon Sep 17 00:00:00 2001 From: gibbs Date: Tue, 15 Sep 1998 10:26:24 +0000 Subject: Document new volume tag and element status support. --- share/man/man4/ch.4 | 244 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 218 insertions(+), 26 deletions(-) diff --git a/share/man/man4/ch.4 b/share/man/man4/ch.4 index a306fff..f985d6c 100644 --- a/share/man/man4/ch.4 +++ b/share/man/man4/ch.4 @@ -1,4 +1,4 @@ -.\" $Id: ch.4,v 1.10 1997/02/22 13:24:25 peter Exp $ +.\" $Id: ch.4,v 1.11 1997/06/02 21:01:00 max Exp $ .\" Copyright (c) 1996 .\" Julian Elischer . All rights reserved. .\" @@ -24,12 +24,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd August 27, 1993 +.Dd May 14, 1998 .Dt CH 4 .Os FreeBSD .Sh NAME .Nm ch -.Nd scsi media-changer (juke box) driver +.Nd SCSI media-changer (juke box) driver .Sh SYNOPSIS .Cd device ch .Cd device ch1 target 4 lun 0 @@ -37,14 +37,16 @@ The .Xr ch driver provides support for a -.Em scsi -juke box. It allows many slots of media to be multiplexed between a number -of drives. +.Em SCSI +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 informationen attached to +the media. .Pp -A scsi adapter must also be separately configured into the system -before a scsi changer can be configured. +A SCSI adapter must also be separately configured into the system +before a SCSI changer can be configured. .Pp -As the scsi adapter is probed during boot, the +As the SCSI adapter is probed during boot, the .Em SCSI bus is scanned for devices. Any devices found which answer as 'Changer' type devices will be 'attached' to the @@ -64,42 +66,232 @@ for details on kernel configuration. .Sh KERNEL CONFIGURATION In configuring, if an optional .Ar count -is given in the specification, that number of scsi media changers +is given in the specification, that number of SCSI media changers are configured; Most storage for them is allocated only when found so a large number of configured devices is cheap. (once the first has included the driver). .Pp .Sh IOCTLS +User mode programs communicate with the changer driver through a +number of ioctls which are described below. Changer element addresses +used in the communcation between the kernel and the changer device are +mapped to zero-based logical addresses. Element types are specified +as follows: +.Bl -tag -width CHET_MT +.It Dv CHET_MT +Medium transport element (picker). +.It Dv CHET_ST +Storage element (slot). +.It Dv CHET_IE +Import/export element (portal). +.It Dv CHET_DT +Data transfer element (drive). +.El +.Pp The following .Xr ioctl 2 -call applies to the changer. It is defined in +calls apply to the changer. They are defined in in the header file -.Em sys/chio.h. +.Aq Pa sys/chio.h . +.Pp +.Bl -tag -width CHIOEXCHANGE +.It Dv CHIOMOVE +.Pq Li "struct changer_move" +Move a medium from one element to another (\fBMOVE MEDIUM\fR) using +the current picker. The source and destination elements are specified +in a changer_move structure, which includes at least the following +fields: +.Bd -literal -offset indent +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 */ +.Ed +If the \fBCM_INVERT\fR in the \fBcm_flags\fR field is set, the medium +changer is instructed to flip the medium while moving it. +.It Dv CHIOEXCHANGE +.Pq Li "struct changer_exchange" +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 +changer_exchange structure which includes at least the following +fields: +.Bd -literal -offset indent +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 */ +.Ed +In \fBce_flags\fR, \fBCM_INVERT1\fR and/or \fBCM_INVERT2\fR may be set +to flip the first or second medium during the exchange operation, +respectively. +.Pp +\fIThis operation is untested.\fR +.It Dv CHIOPOSITION +.Pq Li "struct changer_position" +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: +.Bd -literal -offset indent +u_int cp_type; /* element type */ +u_int cp_unit; /* logical unit of element */ +u_int cp_flags; /* misc. flags */ +.Ed +The \fBcp_flags\fR field may be set to \fBCP_INVERT\fR to invert the +picker during the operation. +.It Dv CHIOGPICKER +.Pq Li "int" +Return the logical address of the current picker. +.It Dv CHIOSPICKER +.Pq Li "int" +Select the picker specified by the given logical address. +.It Dv CHIOGPARAMS +.Pq Li "struct changer_params" +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: +.Bd -literal -offset indent +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 */ + +.Ed +This call can be used by applications to query the dimensions of +the jukebox before using the \fBCHIGSTATUS\fR +ioctl to query the jukebox' status. +.It Dv CHIOIELEM +Perform the \fBINITIALIZE ELEMENT STATUS\fR call on the media changer +device. This forces the media changer to update it's internal status +information with respect to loaded media. It also scans any barcode +labels provided that it has a label reader. The +.Nm +driver's status is not affected by this call. +.It Dv CHIOGSTATUS +.Pq Li "struct changer_element_status_request" +Perform the \fBREAD ELEMENT STATUS\fR call on the media changer +device. This call reads the element status information of the media +changer and converts it to an array of \fBchanger_element_status\fR +structures. +.Pp +With each call to +.Dv CHIOGSTATUS +, the status of one or more elements of one type may be queried. +.Pp +The application passes a changer_element_status_request structure to the +.Nm +driver which contains the following fields: +.Bd -literal -offset indent +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; + +.Ed +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 changer_element_status structures pointed to +by the cesr_element_status field. The application must allocate enough +memory for cesr_element_count status structures (see below). +The cesr_flags can optionally be set to +.Dv CESR_VOLTAGS +to indicate that volume tag (bar code) information is to be read from +the jukebox and returned. +.Pp +The cesr_element_base and cesr_element_count fields must be valid with +respect to the physical configuration of the changer. If they are +not, the +.Dv CHIOGSTATUS +ioctl returns the +.Er EINVAL +error code. +.Pp +The information about the elements is returned in an array of +changer_element_status structures. This structure include at least +the following fields: +.Bd -literal -offset indent +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 elemtne (if ces_lunvalid is nonzero) */ -.Bl -tag -width DIOCSDINFO -CHIOOP -This appears to be a 'do-everything' call. +.Ed +The ces_addr 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. +.Pp +The following flags are defined for the \fBces_flags\fR field: +.Bl -tag -width CESTATUS_IMPEXP +.It Dv CESTATUS_FULL +A medium is present. +.It Dv CESTATUS_IMPEXP +The medium has been deposited by the operator (and not by a picker). +.It Dv CESTATUS_EXCEPT +The element is in an exceptional state (e.g. invalid barcode label, +barcode not yet scanned). +.It Dv CESTATUS_ACCESS +The element is accessible by the picker. +.It Dv CESTATUS_EXENAB +The element supports medium export. +.It Dv CESTATUS_INENAB +The element supports medium import. +.El +.Pp +Note that not all flags are valid for all element types. .El .Sh NOTES -The +This version of the .Nm -driver was added to the system by - Stefan Grefen (grefen@goofy.zdv.uni-mainz.de) -who apparently had such a device -however It appears as though no-one I have heard of has ever used this -driver. If you use it please let me know so I can test changes. -Stefan appears to have suffered net.death (or at least net.disconnection). -I (julian) have never used this device. If you do please re-write this -man page and send it to me.. - +driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a +and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader). +.Pp +Many of the features the +.Nm +driver supports are not thouroghly 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. +.Sh AUTHORS +The +.Nm +driver was written by +.An Jason R. Thorpe Aq thorpej@and.com +for And Communications, http://www.and.com/. +It was added to the system by +.An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de +who apparently had such a device. +It was ported to CAM by +.An Kenneth Merry Aq ken@FreeBSD.ORG . +It was updated to support volume tags by +.An Hans Huebner Aq hans@artcom.de . .Sh FILES .Bl -tag -width /dev/ch[0-9] -compact .It Pa /dev/ch[0-9] device entries .El .Sh DIAGNOSTICS -None. +If the media changer does not support features requested by the +.Nm +driver, it will produce both console error messages and failure return +codes to the ioctls described here. .Sh SEE ALSO .Xr chio 1 , .Xr cd 4 , -- cgit v1.1