d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document new volume tag and element status support.

Browse Source
This commit is contained in:
gibbs 1998-09-15 10:26:24 +00:00
parent 3576feaf0b
commit cd882d0271
1 changed files with 218 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

244
share/man/man4/ch.4
View File

@ -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 .\" Copyright (c) 1996
.\" Julian Elischer <julian@freebsd.org>. All rights reserved. .\" 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 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE. .\" SUCH DAMAGE.
.\" .\"
.Dd August 27, 1993 .Dd May 14, 1998
.Dt CH 4 .Dt CH 4
.Os FreeBSD .Os FreeBSD
.Sh NAME .Sh NAME
.Nm ch .Nm ch
.Nd scsi media-changer (juke box) driver .Nd SCSI media-changer (juke box) driver
.Sh SYNOPSIS .Sh SYNOPSIS
.Cd device ch .Cd device ch
.Cd device ch1 target 4 lun 0 .Cd device ch1 target 4 lun 0
@ -37,14 +37,16 @@
The The
.Xr ch .Xr ch
driver provides support for a driver provides support for a
.Em scsi .Em SCSI
juke box. It allows many slots of media to be multiplexed between a number media changer. It allows many slots of media to be multiplexed between
of drives. 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 .Pp
A scsi adapter must also be separately configured into the system A SCSI adapter must also be separately configured into the system
before a scsi changer can be configured. before a SCSI changer can be configured.
.Pp .Pp
As the scsi adapter is probed during boot, the As the SCSI adapter is probed during boot, the
.Em SCSI .Em SCSI
bus is scanned for devices. Any devices found which answer as 'Changer' bus is scanned for devices. Any devices found which answer as 'Changer'
type devices will be 'attached' to the type devices will be 'attached' to the
@ -64,42 +66,232 @@ for details on kernel configuration.
.Sh KERNEL CONFIGURATION .Sh KERNEL CONFIGURATION
In configuring, if an optional In configuring, if an optional
.Ar count .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 are configured; Most storage for them is allocated only when found
so a large number of configured devices is cheap. (once the first so a large number of configured devices is cheap. (once the first
has included the driver). has included the driver).
.Pp .Pp
.Sh IOCTLS .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 The following
.Xr ioctl 2 .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 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 .Ed
CHIOOP This call can be used by applications to query the dimensions of
This appears to be a 'do-everything' call. 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 .El
.Sh NOTES .Sh NOTES
The This version of the
.Nm .Nm
driver was added to the system by driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a
Stefan Grefen (grefen@goofy.zdv.uni-mainz.de) and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader).
who apparently had such a device .Pp
however It appears as though no-one I have heard of has ever used this Many of the features the
driver. If you use it please let me know so I can test changes. .Nm
Stefan appears to have suffered net.death (or at least net.disconnection). driver supports are not thouroghly tested due to the fact that the
I (julian) have never used this device. If you do please re-write this devices available for testing do not support the necessary commands.
man page and send it to me.. 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 .Sh FILES
.Bl -tag -width /dev/ch[0-9] -compact .Bl -tag -width /dev/ch[0-9] -compact
.It Pa /dev/ch[0-9] .It Pa /dev/ch[0-9]
device entries device entries
.El .El
.Sh DIAGNOSTICS .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 .Sh SEE ALSO
.Xr chio 1 , .Xr chio 1 ,
.Xr cd 4 , .Xr cd 4 ,