| ch.4 (89610) | ch.4 (117011) |
|---|---|
| 1.\" $FreeBSD: head/share/man/man4/ch.4 89610 2002-01-21 12:09:13Z mpp $ | 1.\" $FreeBSD: head/share/man/man4/ch.4 117011 2003-06-28 23:53:39Z ru $ |
| 2.\" Copyright (c) 1996 3.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. --- 25 unchanged lines hidden (view full) --- 35.Cd device ch1 target 4 unit 0 36.Sh DESCRIPTION 37The 38.Xr ch 39driver provides support for a 40.Em SCSI 41media changer. 42It allows many slots of media to be multiplexed between | 2.\" Copyright (c) 1996 3.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. --- 25 unchanged lines hidden (view full) --- 35.Cd device ch1 target 4 unit 0 36.Sh DESCRIPTION 37The 38.Xr ch 39driver provides support for a 40.Em SCSI 41media changer. 42It allows many slots of media to be multiplexed between |
| 43a number of drives. The changer device may optionally be equipped | 43a number of drives. 44The changer device may optionally be equipped |
| 44with a bar code reader, which reads label information attached to 45the media. 46.Pp 47A SCSI adapter must also be separately configured into the system 48before a SCSI changer can be configured. 49.Pp 50As the SCSI adapter is probed during boot, the 51.Em SCSI --- 18 unchanged lines hidden (view full) --- 70.Ar count 71is given in the specification, that number of SCSI media changers 72are configured; Most storage for them is allocated only when found 73so a large number of configured devices is cheap. 74(once the first 75has included the driver). 76.Sh IOCTLS 77User mode programs communicate with the changer driver through a | 45with a bar code reader, which reads label information attached to 46the media. 47.Pp 48A SCSI adapter must also be separately configured into the system 49before a SCSI changer can be configured. 50.Pp 51As the SCSI adapter is probed during boot, the 52.Em SCSI --- 18 unchanged lines hidden (view full) --- 71.Ar count 72is given in the specification, that number of SCSI media changers 73are configured; Most storage for them is allocated only when found 74so a large number of configured devices is cheap. 75(once the first 76has included the driver). 77.Sh IOCTLS 78User mode programs communicate with the changer driver through a |
| 78number of ioctls which are described below. Changer element addresses | 79number of ioctls which are described below. 80Changer element addresses |
| 79used in the communication between the kernel and the changer device are | 81used in the communication between the kernel and the changer device are |
| 80mapped to zero-based logical addresses. Element types are specified 81as follows: | 82mapped to zero-based logical addresses. 83Element types are specified as follows: |
| 82.Bl -tag -width CHET_MT 83.It Dv CHET_MT 84Medium transport element (picker). 85.It Dv CHET_ST 86Storage element (slot). 87.It Dv CHET_IE 88Import/export element (portal). 89.It Dv CHET_DT --- 4 unchanged lines hidden (view full) --- 94.Xr ioctl 2 95calls apply to the changer. 96They are defined 97in the header file 98.Aq Pa sys/chio.h . 99.Pp 100.Bl -tag -width CHIOEXCHANGE 101.It Dv CHIOMOVE | 84.Bl -tag -width CHET_MT 85.It Dv CHET_MT 86Medium transport element (picker). 87.It Dv CHET_ST 88Storage element (slot). 89.It Dv CHET_IE 90Import/export element (portal). 91.It Dv CHET_DT --- 4 unchanged lines hidden (view full) --- 96.Xr ioctl 2 97calls apply to the changer. 98They are defined 99in the header file 100.Aq Pa sys/chio.h . 101.Pp 102.Bl -tag -width CHIOEXCHANGE 103.It Dv CHIOMOVE |
| 102.Pq Li "struct changer_move" 103Move a medium from one element to another (\fBMOVE MEDIUM\fR) using 104the current picker. The source and destination elements are specified | 104.Pq Vt "struct changer_move" 105Move a medium from one element to another 106.Pq Sy "MOVE MEDIUM" 107using the current picker. 108The source and destination elements are specified |
| 105in a changer_move structure, which includes at least the following 106fields: 107.Bd -literal -offset indent 108u_int cm_fromtype; /* element type to move from */ 109u_int cm_fromunit; /* logical unit of from element */ 110u_int cm_totype; /* element type to move to */ 111u_int cm_tounit; /* logical unit of to element */ 112u_int cm_flags; /* misc. flags */ 113.Ed | 109in a changer_move structure, which includes at least the following 110fields: 111.Bd -literal -offset indent 112u_int cm_fromtype; /* element type to move from */ 113u_int cm_fromunit; /* logical unit of from element */ 114u_int cm_totype; /* element type to move to */ 115u_int cm_tounit; /* logical unit of to element */ 116u_int cm_flags; /* misc. flags */ 117.Ed |
| 114If the \fBCM_INVERT\fR in the \fBcm_flags\fR field is set, the medium | 118If the 119.Dv CM_INVERT 120in the 121.Va cm_flags 122field is set, the medium |
| 115changer is instructed to flip the medium while moving it. 116.It Dv CHIOEXCHANGE | 123changer is instructed to flip the medium while moving it. 124.It Dv CHIOEXCHANGE |
| 117.Pq Li "struct changer_exchange" | 125.Pq Vt "struct changer_exchange" |
| 118Move the medium located in the source element to the first destination 119element, and move the medium that had been in the first destination | 126Move the medium located in the source element to the first destination 127element, and move the medium that had been in the first destination |
| 120element to the second destination element. In case of a simple | 128element to the second destination element. 129In case of a simple |
| 121exchange, the source and second destination elements should be the | 130exchange, the source and second destination elements should be the |
| 122same. The current picker is used to perform the operation. The 123addresses of the affected elements is specified to the ioctl in a 124changer_exchange structure which includes at least the following | 131same. 132The current picker is used to perform the operation. 133The addresses of the affected elements is specified to the ioctl in a 134.Vt changer_exchange 135structure which includes at least the following |
| 125fields: 126.Bd -literal -offset indent 127u_int ce_srctype; /* element type of source */ 128u_int ce_srcunit; /* logical unit of source */ 129u_int ce_fdsttype; /* element type of first destination */ 130u_int ce_fdstunit; /* logical unit of first destination */ 131u_int ce_sdsttype; /* element type of second destination */ 132u_int ce_sdstunit; /* logical unit of second destination */ 133u_int ce_flags; /* misc. flags */ 134.Ed | 136fields: 137.Bd -literal -offset indent 138u_int ce_srctype; /* element type of source */ 139u_int ce_srcunit; /* logical unit of source */ 140u_int ce_fdsttype; /* element type of first destination */ 141u_int ce_fdstunit; /* logical unit of first destination */ 142u_int ce_sdsttype; /* element type of second destination */ 143u_int ce_sdstunit; /* logical unit of second destination */ 144u_int ce_flags; /* misc. flags */ 145.Ed |
| 135In \fBce_flags\fR, \fBCM_INVERT1\fR and/or \fBCM_INVERT2\fR may be set | 146In 147.Va ce_flags , 148.Dv CM_INVERT1 149and/or 150.Dv CM_INVERT2 151may be set |
| 136to flip the first or second medium during the exchange operation, 137respectively. 138.Pp | 152to flip the first or second medium during the exchange operation, 153respectively. 154.Pp |
| 139\fIThis operation is untested.\fR | 155.Em This operation is untested . |
| 140.It Dv CHIOPOSITION | 156.It Dv CHIOPOSITION |
| 141.Pq Li "struct changer_position" 142Position the current picker in front of the specified element. The 143element is specified with a changer_position structure, which includes | 157.Pq Vt "struct changer_position" 158Position the current picker in front of the specified element. 159The element is specified with a changer_position structure, which includes |
| 144at least the following elements: 145.Bd -literal -offset indent 146u_int cp_type; /* element type */ 147u_int cp_unit; /* logical unit of element */ 148u_int cp_flags; /* misc. flags */ 149.Ed | 160at least the following elements: 161.Bd -literal -offset indent 162u_int cp_type; /* element type */ 163u_int cp_unit; /* logical unit of element */ 164u_int cp_flags; /* misc. flags */ 165.Ed |
| 150The \fBcp_flags\fR field may be set to \fBCP_INVERT\fR to invert the 151picker during the operation. | 166The 167.Va cp_flags 168field may be set to 169.Dv CP_INVERT 170to invert the picker during the operation. |
| 152.It Dv CHIOGPICKER | 171.It Dv CHIOGPICKER |
| 153.Pq Li "int" | 172.Pq Vt int |
| 154Return the logical address of the current picker. 155.It Dv CHIOSPICKER | 173Return the logical address of the current picker. 174.It Dv CHIOSPICKER |
| 156.Pq Li "int" | 175.Pq Vt int |
| 157Select the picker specified by the given logical address. 158.It Dv CHIOGPARAMS | 176Select the picker specified by the given logical address. 177.It Dv CHIOGPARAMS |
| 159.Pq Li "struct changer_params" 160Return the configuration parameters for the media changer. This ioctl | 178.Pq Vt "struct changer_params" 179Return the configuration parameters for the media changer. 180This ioctl |
| 161fills the changer_params structure passed by the user with at least the 162following fields: 163.Bd -literal -offset indent 164u_int cp_npickers; /* number of pickers */ 165u_int cp_nslots; /* number of slots */ 166u_int cp_nportals; /* number of import/export portals */ 167u_int cp_ndrives; /* number of drives */ 168.Ed 169.Pp 170This call can be used by applications to query the dimensions of | 181fills the changer_params structure passed by the user with at least the 182following fields: 183.Bd -literal -offset indent 184u_int cp_npickers; /* number of pickers */ 185u_int cp_nslots; /* number of slots */ 186u_int cp_nportals; /* number of import/export portals */ 187u_int cp_ndrives; /* number of drives */ 188.Ed 189.Pp 190This call can be used by applications to query the dimensions of |
| 171the jukebox before using the \fBCHIGSTATUS\fR | 191the jukebox before using the 192.Dv CHIGSTATUS |
| 172ioctl to query the jukebox' status. 173.It Dv CHIOIELEM | 193ioctl to query the jukebox' status. 194.It Dv CHIOIELEM |
| 174Perform the \fBINITIALIZE ELEMENT STATUS\fR call on the media changer 175device. This forces the media changer to update its internal status 176information with respect to loaded media. It also scans any barcode 177labels provided that it has a label reader. The | 195Perform the 196.Sy INITIALIZE ELEMENT STATUS 197call on the media changer device. 198This forces the media changer to update its internal status 199information with respect to loaded media. 200It also scans any barcode labels provided that it has a label reader. 201The |
| 178.Nm 179driver's status is not affected by this call. 180.It Dv CHIOGSTATUS | 202.Nm 203driver's status is not affected by this call. 204.It Dv CHIOGSTATUS |
| 181.Pq Li "struct changer_element_status_request" 182Perform the \fBREAD ELEMENT STATUS\fR call on the media changer 183device. This call reads the element status information of the media 184changer and converts it to an array of \fBchanger_element_status\fR | 205.Pq Vt "struct changer_element_status_request" 206Perform the 207.Sy READ ELEMENT STATUS 208call on the media changer device. 209This call reads the element status information of the media 210changer and converts it to an array of 211.Vt changer_element_status |
| 185structures. 186.Pp 187With each call to 188.Dv CHIOGSTATUS , 189the status of one or more elements of one type may be queried. 190.Pp | 212structures. 213.Pp 214With each call to 215.Dv CHIOGSTATUS , 216the status of one or more elements of one type may be queried. 217.Pp |
| 191The application passes a changer_element_status_request structure to the | 218The application passes a 219.Vt changer_element_status_request 220structure to the |
| 192.Nm 193driver which contains the following fields: 194.Bd -literal -offset indent 195u_int cesr_element_type; 196u_int cesr_element_base; 197u_int cesr_element_count; 198u_int cesr_flags; 199struct changer_element_status *cesr_element_status; 200.Ed 201.Pp 202This structure is read by the driver to determine the type, logical 203base address and number of elements for which information is to be | 221.Nm 222driver which contains the following fields: 223.Bd -literal -offset indent 224u_int cesr_element_type; 225u_int cesr_element_base; 226u_int cesr_element_count; 227u_int cesr_flags; 228struct changer_element_status *cesr_element_status; 229.Ed 230.Pp 231This structure is read by the driver to determine the type, logical 232base address and number of elements for which information is to be |
| 204returned in the array of changer_element_status structures pointed to 205by the cesr_element_status field. The application must allocate enough 206memory for cesr_element_count status structures (see below). 207The cesr_flags can optionally be set to | 233returned in the array of 234.Vt changer_element_status 235structures pointed to by the 236.Va cesr_element_status field . 237The application must allocate enough 238memory for 239.Va cesr_element_count 240status structures (see below). 241The 242.Va cesr_flags 243can optionally be set to |
| 208.Dv CESR_VOLTAGS 209to indicate that volume tag (bar code) information is to be read from 210the jukebox and returned. 211.Pp | 244.Dv CESR_VOLTAGS 245to indicate that volume tag (bar code) information is to be read from 246the jukebox and returned. 247.Pp |
| 212The cesr_element_base and cesr_element_count fields must be valid with 213respect to the physical configuration of the changer. If they are 214not, the | 248The 249.Va cesr_element_base 250and 251.Va cesr_element_count 252fields must be valid with respect to the physical configuration of the changer. 253If they are not, the |
| 215.Dv CHIOGSTATUS 216ioctl returns the 217.Er EINVAL 218error code. 219.Pp 220The information about the elements is returned in an array of | 254.Dv CHIOGSTATUS 255ioctl returns the 256.Er EINVAL 257error code. 258.Pp 259The information about the elements is returned in an array of |
| 221changer_element_status structures. This structure include at least 222the following fields: | 260.Vt changer_element_status 261structures. 262This structure include at least the following fields: |
| 223.Bd -literal -offset indent 224u_int ces_addr; /* element address in media changer */ 225u_char ces_flags; /* see CESTATUS definitions below */ 226u_char ces_sensecode; /* additional sense code for element */ 227u_char ces_sensequal; /* additional sense code qualifier */ 228u_char ces_invert; /* invert bit */ 229u_char ces_svalid; /* source address (ces_source) valid */ 230u_short ces_source; /* source address of medium */ 231changer_voltag_t ces_pvoltag; /* primary volume tag */ 232changer_voltag_t ces_avoltag; /* alternate volume tag */ 233u_char ces_idvalid; /* ces_scsi_id is valid */ 234u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */ 235u_char ces_lunvalid; /* ces_scsi_lun is valid */ 236u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */ 237.Ed 238.Pp | 263.Bd -literal -offset indent 264u_int ces_addr; /* element address in media changer */ 265u_char ces_flags; /* see CESTATUS definitions below */ 266u_char ces_sensecode; /* additional sense code for element */ 267u_char ces_sensequal; /* additional sense code qualifier */ 268u_char ces_invert; /* invert bit */ 269u_char ces_svalid; /* source address (ces_source) valid */ 270u_short ces_source; /* source address of medium */ 271changer_voltag_t ces_pvoltag; /* primary volume tag */ 272changer_voltag_t ces_avoltag; /* alternate volume tag */ 273u_char ces_idvalid; /* ces_scsi_id is valid */ 274u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */ 275u_char ces_lunvalid; /* ces_scsi_lun is valid */ 276u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */ 277.Ed 278.Pp |
| 239The ces_addr field contains the address of the element in the 240coordinate system of the media changer. It is not used by the driver, | 279The 280.Va ces_addr 281field contains the address of the element in the 282coordinate system of the media changer. 283It is not used by the driver, |
| 241and should be used for diagnostic purposes only. 242.Pp | 284and should be used for diagnostic purposes only. 285.Pp |
| 243The following flags are defined for the \fBces_flags\fR field: | 286The following flags are defined for the 287.Va ces_flags 288field: |
| 244.Bl -tag -width CESTATUS_IMPEXP 245.It Dv CESTATUS_FULL 246A medium is present. 247.It Dv CESTATUS_IMPEXP 248The medium has been deposited by the operator (and not by a picker). 249.It Dv CESTATUS_EXCEPT 250The element is in an exceptional state (e.g. invalid barcode label, 251barcode not yet scanned). --- 57 unchanged lines hidden --- | 289.Bl -tag -width CESTATUS_IMPEXP 290.It Dv CESTATUS_FULL 291A medium is present. 292.It Dv CESTATUS_IMPEXP 293The medium has been deposited by the operator (and not by a picker). 294.It Dv CESTATUS_EXCEPT 295The element is in an exceptional state (e.g. invalid barcode label, 296barcode not yet scanned). --- 57 unchanged lines hidden --- |