1 /* $OpenBSD: scsi_changer.h,v 1.11 2023/04/11 00:45:09 jsg Exp $ */ 2 /* $NetBSD: scsi_changer.h,v 1.7 1996/04/03 00:25:48 thorpej Exp $ */ 3 4 /* 5 * Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com> 6 * All rights reserved. 7 * 8 * Partially based on an autochanger driver written by Stefan Grefen 9 * and on an autochanger driver written by the Systems Programming Group 10 * at the University of Utah Computer Science Department. 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions 14 * are met: 15 * 1. Redistributions of source code must retain the above copyright 16 * notice, this list of conditions and the following disclaimer. 17 * 2. Redistributions in binary form must reproduce the above copyright 18 * notice, this list of conditions and the following disclaimer in the 19 * documentation and/or other materials provided with the distribution. 20 * 3. All advertising materials mentioning features or use of this software 21 * must display the following acknowledgements: 22 * This product includes software developed by Jason R. Thorpe 23 * for And Communications, http://www.and.com/ 24 * 4. The name of the author may not be used to endorse or promote products 25 * derived from this software without specific prior written permission. 26 * 27 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 28 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 29 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 30 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 31 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 32 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 33 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 34 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 35 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 36 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 37 * SUCH DAMAGE. 38 */ 39 40 /* 41 * SCSI changer interface description 42 */ 43 44 /* 45 * Partially derived from software written by Stefan Grefen 46 * (grefen@goofy.zdv.uni-mainz.de soon grefen@convex.com) 47 * based on the SCSI System by written Julian Elischer (julian@tfs.com) 48 * for TRW Financial Systems. 49 * 50 * TRW Financial Systems, in accordance with their agreement with Carnegie 51 * Mellon University, makes this software available to CMU to distribute 52 * or use in any manner that they see fit as long as this message is kept with 53 * the software. For this reason TFS also grants any other persons or 54 * organisations permission to use or modify this software. 55 * 56 * TFS supplies this software to be publicly redistributed 57 * on the understanding that TFS is not responsible for the correct 58 * functioning of this software in any circumstances. 59 * 60 * Ported to run under 386BSD by Julian Elischer (julian@tfs.com) Sept 1992 61 */ 62 63 #ifndef _SCSI_SCSI_CHANGER_H 64 #define _SCSI_SCSI_CHANGER_H 65 66 /* 67 * SCSI command format 68 */ 69 70 /* 71 * Exchange the medium in the source element with the medium 72 * located at the destination element. 73 */ 74 struct scsi_exchange_medium { 75 u_int8_t opcode; 76 #define EXCHANGE_MEDIUM 0xa6 77 u_int8_t byte2; 78 u_int8_t tea[2]; /* transport element address */ 79 u_int8_t src[2]; /* source address */ 80 u_int8_t fdst[2]; /* first destination address */ 81 u_int8_t sdst[2]; /* second destination address */ 82 u_int8_t flags; 83 #define EXCHANGE_MEDIUM_INV1 0x01 84 #define EXCHANGE_MEDIUM_INV2 0x02 85 u_int8_t control; 86 }; 87 88 /* 89 * Cause the medium changer to check all elements for medium and any 90 * other status relevant to the element. 91 */ 92 struct scsi_initialize_elememt_status { 93 u_int8_t opcode; 94 #define INITIALIZE_ELEMENT_STATUS 0x07 95 u_int8_t byte2; 96 u_int8_t reserved[3]; 97 u_int8_t control; 98 }; 99 100 /* 101 * Request the changer to move a unit of media from the source element 102 * to the destination element. 103 */ 104 struct scsi_move_medium { 105 u_int8_t opcode; 106 #define MOVE_MEDIUM 0xa5 107 u_int8_t byte2; 108 u_int8_t tea[2]; /* transport element address */ 109 u_int8_t src[2]; /* source element address */ 110 u_int8_t dst[2]; /* destination element address */ 111 u_int8_t reserved[2]; 112 u_int8_t flags; 113 #define MOVE_MEDIUM_INVERT 0x01 114 u_int8_t control; 115 }; 116 117 /* 118 * Position the specified transport element (picker) in front of 119 * the destination element specified. 120 */ 121 struct scsi_position_to_element { 122 u_int8_t opcode; 123 #define POSITION_TO_ELEMENT 0x2b 124 u_int8_t byte2; 125 u_int8_t tea[2]; /* transport element address */ 126 u_int8_t dst[2]; /* destination element address */ 127 u_int8_t reserved[2]; 128 u_int8_t flags; 129 #define POSITION_TO_ELEMENT_INVERT 0x01 130 u_int8_t control; 131 }; 132 133 /* 134 * Request that the changer report the status of its internal elements. 135 */ 136 struct scsi_read_element_status { 137 u_int8_t opcode; 138 #define READ_ELEMENT_STATUS 0xb8 139 u_int8_t byte2; 140 #define READ_ELEMENT_STATUS_VOLTAG 0x10 /* report volume tag info */ 141 /* ...next 4 bits are an element type code... */ 142 u_int8_t sea[2]; /* starting element address */ 143 u_int8_t count[2]; /* number of elements */ 144 u_int8_t reserved0; 145 u_int8_t len[3]; /* length of data buffer */ 146 u_int8_t reserved1; 147 u_int8_t control; 148 }; 149 150 struct scsi_request_volume_element_address { 151 u_int8_t opcode; 152 #define REQUEST_VOLUME_ELEMENT_ADDRESS 0xb5 153 u_int8_t byte2; 154 #define REQUEST_VOLUME_ELEMENT_ADDRESS_VOLTAG 0x10 155 /* ...next 4 bits are an element type code... */ 156 u_int8_t eaddr[2]; /* element address */ 157 u_int8_t count[2]; /* number of elements */ 158 u_int8_t reserved0; 159 u_int8_t len[3]; /* length of data buffer */ 160 u_int8_t reserved1; 161 u_int8_t control; 162 }; 163 164 /* XXX scsi_release */ 165 166 /* 167 * Data returned by READ ELEMENT STATUS consists of an 8-byte header 168 * followed by one or more read_element_status_pages. 169 */ 170 struct read_element_status_header { 171 u_int8_t fear[2]; /* first element address reported */ 172 u_int8_t count[2]; /* number of elements available */ 173 u_int8_t reserved; 174 u_int8_t nbytes[3]; /* byte count of all pages */ 175 }; 176 177 struct read_element_status_page_header { 178 u_int8_t type; /* element type code; see type codes below */ 179 u_int8_t flags; 180 #define READ_ELEMENT_STATUS_AVOLTAG 0x40 181 #define READ_ELEMENT_STATUS_PVOLTAG 0x80 182 u_int8_t edl[2]; /* element descriptor length */ 183 u_int8_t reserved; 184 u_int8_t nbytes[3]; /* byte count of all descriptors */ 185 }; 186 187 /* 188 * Format of a volume tag 189 */ 190 191 struct volume_tag { 192 u_int8_t vif[32]; /* volume identification field */ 193 u_int8_t reserved[2]; 194 u_int8_t vsn[2]; /* volume sequence number */ 195 }; 196 197 struct read_element_status_descriptor { 198 u_int8_t eaddr[2]; /* element address */ 199 u_int8_t flags1; 200 201 #define READ_ELEMENT_STATUS_FULL 0x01 202 #define READ_ELEMENT_STATUS_IMPEXP 0x02 203 #define READ_ELEMENT_STATUS_EXCEPT 0x04 204 #define READ_ELEMENT_STATUS_ACCESS 0x08 205 #define READ_ELEMENT_STATUS_EXENAB 0x10 206 #define READ_ELEMENT_STATUS_INENAB 0x20 207 208 #define READ_ELEMENT_STATUS_MT_MASK1 0x05 209 #define READ_ELEMENT_STATUS_ST_MASK1 0x0c 210 #define READ_ELEMENT_STATUS_IE_MASK1 0x3f 211 #define READ_ELEMENT_STATUS_DT_MASK1 0x0c 212 213 u_int8_t reserved0; 214 u_int8_t sense_code; 215 u_int8_t sense_qual; 216 217 /* 218 * dt_scsi_flags and dt_scsi_addr are valid only on data transport 219 * elements. These bytes are undefined for all other element types. 220 */ 221 u_int8_t dt_scsi_flags; 222 223 #define READ_ELEMENT_STATUS_DT_LUNMASK 0x07 224 #define READ_ELEMENT_STATUS_DT_LUVALID 0x10 225 #define READ_ELEMENT_STATUS_DT_IDVALID 0x20 226 #define READ_ELEMENT_STATUS_DT_NOTBUS 0x80 227 228 u_int8_t dt_scsi_addr; 229 230 u_int8_t reserved1; 231 232 u_int8_t flags2; 233 #define READ_ELEMENT_STATUS_INVERT 0x40 234 #define READ_ELEMENT_STATUS_SVALID 0x80 235 u_int8_t ssea[2]; /* source storage element address */ 236 237 /* 238 * bytes 12-47: Primary volume tag information. 239 * (field omitted if PVOLTAG = 0) 240 * 241 * bytes 48-83: Alternate volume tag information. 242 * (field omitted if AVOLTAG = 0) 243 */ 244 245 struct volume_tag pvoltag; /* omitted if PVOLTAG == 0 */ 246 struct volume_tag avoltag; /* omitted if AVOLTAG == 0 */ 247 248 /* 249 * bytes 84-87: Reserved (moved up if either of the above fields 250 * are omitted) 251 * 252 * bytes 88-end: Vendor-specific: (moved up if either of the 253 * above fields are missing) 254 */ 255 }; 256 257 /* XXX add data returned by REQUEST VOLUME ELEMENT ADDRESS */ 258 259 /* Element type codes */ 260 #define ELEMENT_TYPE_MASK 0x0f /* Note: these aren't bits */ 261 #define ELEMENT_TYPE_ALL 0x00 262 #define ELEMENT_TYPE_MT 0x01 263 #define ELEMENT_TYPE_ST 0x02 264 #define ELEMENT_TYPE_IE 0x03 265 #define ELEMENT_TYPE_DT 0x04 266 267 /* 268 * XXX The following definitions should be common to all SCSI device types. 269 */ 270 #define PGCODE_MASK 0x3f /* valid page number bits in pg_code */ 271 #define PGCODE_PS 0x80 /* indicates page is savable */ 272 273 /* 274 * Device capabilities page. 275 * 276 * This page defines characteristics of the element types in the 277 * medium changer device. 278 * 279 * Note in the definitions below, the following abbreviations are 280 * used: 281 * MT Medium transport element (picker) 282 * ST Storage transport element (slot) 283 * IE Import/export element (portal) 284 * DT Data transfer element (tape/disk drive) 285 */ 286 #define CAP_PAGE 0x1f 287 struct page_device_capabilities { 288 u_int8_t pg_code; /* page code (0x1f) */ 289 u_int8_t pg_length; /* page length (0x12) */ 290 291 /* 292 * The STOR_xx bits indicate that an element of a given 293 * type may provide independent storage for a unit of 294 * media. The top four bits of this value are reserved. 295 */ 296 u_int8_t stor; 297 #define STOR_MT 0x01 298 #define STOR_ST 0x02 299 #define STOR_IE 0x04 300 #define STOR_DT 0x08 301 302 u_int8_t reserved0; 303 304 /* 305 * The MOVE_TO_yy bits indicate the changer supports 306 * moving a unit of medium from an element of a given type to an 307 * element of type yy. This is used to determine if a given 308 * MOVE MEDIUM command is legal. The top four bits of each 309 * of these values are reserved. 310 */ 311 u_int8_t move_from_mt; 312 u_int8_t move_from_st; 313 u_int8_t move_from_ie; 314 u_int8_t move_from_dt; 315 #define MOVE_TO_MT 0x01 316 #define MOVE_TO_ST 0x02 317 #define MOVE_TO_IE 0x04 318 #define MOVE_TO_DT 0x08 319 320 u_int8_t reserved1[2]; 321 322 /* 323 * Similar to above, but for EXCHANGE MEDIUM. 324 */ 325 u_int8_t exchange_with_mt; 326 u_int8_t exchange_with_st; 327 u_int8_t exchange_with_ie; 328 u_int8_t exchange_with_dt; 329 #define EXCHANGE_WITH_MT 0x01 330 #define EXCHANGE_WITH_ST 0x02 331 #define EXCHANGE_WITH_IE 0x04 332 #define EXCHANGE_WITH_DT 0x08 333 }; 334 335 /* 336 * Medium changer element address assignment page. 337 * 338 * Some of these fields can be a little confusing, so an explanation 339 * is in order. 340 * 341 * Each component within a medium changer apparatus is called an 342 * "element". 343 * 344 * The "medium transport element address" is the address of the first 345 * picker (robotic arm). "Number of medium transport elements" tells 346 * us how many pickers exist in the changer. 347 * 348 * The "first storage element address" is the address of the first 349 * slot in the tape or disk magazine. "Number of storage elements" tells 350 * us how many slots exist in the changer. 351 * 352 * The "first import/export element address" is the address of the first 353 * medium portal accessible both by the medium changer and an outside 354 * human operator. This is where the changer might deposit tapes destined 355 * for some vault. The "number of import/export elements" tells us 356 * not many of these portals exist in the changer. NOTE: this number may 357 * be 0. 358 * 359 * The "first data transfer element address" is the address of the first 360 * tape or disk drive in the changer. "Number of data transfer elements" 361 * tells us how many drives exist in the changer. 362 */ 363 #define EA_PAGE 0x1d 364 struct page_element_address_assignment { 365 u_int8_t pg_code; /* page code (0x1d) */ 366 u_int8_t pg_length; /* page length (0x12) */ 367 368 /* Medium transport element address */ 369 u_int8_t mtea[2]; 370 371 /* Number of medium transport elements */ 372 u_int8_t nmte[2]; 373 374 /* First storage element address */ 375 u_int8_t fsea[2]; 376 377 /* Number of storage elements */ 378 u_int8_t nse[2]; 379 380 /* First import/export element address */ 381 u_int8_t fieea[2]; 382 383 /* Number of import/export elements */ 384 u_int8_t niee[2]; 385 386 /* First data transfer element address */ 387 u_int8_t fdtea[2]; 388 389 /* Number of data transfer elements */ 390 u_int8_t ndte[2]; 391 392 u_int8_t reserved[2]; 393 }; 394 395 /* 396 * Transport geometry parameters page. 397 * 398 * Defines whether each medium transport element is a member of a set of 399 * elements that share a common robotics subsystem and whether the element 400 * is capable of media rotation. One transport geometry descriptor is 401 * transferred for each medium transport element, beginning with the first 402 * medium transport element (other than the default transport element address 403 * of 0). 404 */ 405 #define TGP_PAGE 0x1e 406 struct page_transport_geometry_parameters { 407 u_int8_t pg_code; /* page code (0x1e) */ 408 u_int8_t pg_length; /* page length; variable */ 409 410 /* Transport geometry descriptor(s) are here. */ 411 412 u_int8_t misc; 413 #define CAN_ROTATE 0x01 414 415 /* Member number in transport element set. */ 416 u_int8_t member; 417 }; 418 419 #endif /* _SCSI_SCSI_CHANGER_H */ 420