Document new volume tag and element status support.

1 files 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 <julian@freebsd.org>.  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 ,