Document new volume tag and element status support.
This commit is contained in:
gibbs
parent
3576feaf0b
commit
cd882d0271
@ -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 */
|
||||
|
||||
.Bl -tag -width DIOCSDINFO
|
||||
CHIOOP
|
||||
This appears to be a 'do-everything' call.
|
||||
.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) */
|
||||
|
||||
.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
|
||||
This version of the
|
||||
.Nm
|
||||
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 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 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 ,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user