1 /* $FreeBSD$ */ 2 /* $NetBSD: scsi_changer.h,v 1.11 1998/02/13 08:28:32 enami 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_CH_H 64 #define _SCSI_SCSI_CH_H 1 65 66 #include <sys/cdefs.h> 67 68 /* 69 * SCSI command format 70 */ 71 72 /* 73 * Exchange the medium in the source element with the medium 74 * located at the destination element. 75 */ 76 struct scsi_exchange_medium { 77 u_int8_t opcode; 78 #define EXCHANGE_MEDIUM 0xa6 79 u_int8_t byte2; 80 u_int8_t tea[2]; /* transport element address */ 81 u_int8_t src[2]; /* source address */ 82 u_int8_t fdst[2]; /* first destination address */ 83 u_int8_t sdst[2]; /* second destination address */ 84 u_int8_t invert; 85 #define EXCHANGE_MEDIUM_INV1 0x01 86 #define EXCHANGE_MEDIUM_INV2 0x02 87 u_int8_t control; 88 }; 89 90 /* 91 * Cause the medium changer to check all elements for medium and any 92 * other status relevant to the element. 93 */ 94 struct scsi_initialize_element_status { 95 u_int8_t opcode; 96 #define INITIALIZE_ELEMENT_STATUS 0x07 97 u_int8_t byte2; 98 u_int8_t reserved[3]; 99 u_int8_t control; 100 }; 101 102 /* 103 * Request the changer to move a unit of media from the source element 104 * to the destination element. 105 */ 106 struct scsi_move_medium { 107 u_int8_t opcode; 108 #define MOVE_MEDIUM 0xa5 109 u_int8_t byte2; 110 u_int8_t tea[2]; /* transport element address */ 111 u_int8_t src[2]; /* source element address */ 112 u_int8_t dst[2]; /* destination element address */ 113 u_int8_t reserved[2]; 114 u_int8_t invert; 115 #define MOVE_MEDIUM_INVERT 0x01 116 u_int8_t control; 117 }; 118 119 /* 120 * Position the specified transport element (picker) in front of 121 * the destination element specified. 122 */ 123 struct scsi_position_to_element { 124 u_int8_t opcode; 125 #define POSITION_TO_ELEMENT 0x2b 126 u_int8_t byte2; 127 u_int8_t tea[2]; /* transport element address */ 128 u_int8_t dst[2]; /* destination element address */ 129 u_int8_t reserved[2]; 130 u_int8_t invert; 131 #define POSITION_TO_ELEMENT_INVERT 0x01 132 u_int8_t control; 133 }; 134 135 /* 136 * Request that the changer report the status of its internal elements. 137 */ 138 struct scsi_read_element_status { 139 u_int8_t opcode; 140 #define READ_ELEMENT_STATUS 0xb8 141 u_int8_t byte2; 142 #define READ_ELEMENT_STATUS_VOLTAG 0x10 /* report volume tag info */ 143 /* ...next 4 bits are an element type code... */ 144 u_int8_t sea[2]; /* starting element address */ 145 u_int8_t count[2]; /* number of elements */ 146 u_int8_t reserved0; 147 u_int8_t len[3]; /* length of data buffer */ 148 u_int8_t reserved1; 149 u_int8_t control; 150 }; 151 152 struct scsi_request_volume_element_address { 153 u_int8_t opcode; 154 #define REQUEST_VOLUME_ELEMENT_ADDRESS 0xb5 155 u_int8_t byte2; 156 #define REQUEST_VOLUME_ELEMENT_ADDRESS_VOLTAG 0x10 157 /* ...next 4 bits are an element type code... */ 158 u_int8_t eaddr[2]; /* element address */ 159 u_int8_t count[2]; /* number of elements */ 160 u_int8_t reserved0; 161 u_int8_t len[3]; /* length of data buffer */ 162 u_int8_t reserved1; 163 u_int8_t control; 164 }; 165 166 /* XXX scsi_release */ 167 168 /* 169 * Changer-specific mode page numbers. 170 */ 171 #define CH_ELEMENT_ADDR_ASSIGN_PAGE 0x1D 172 #define CH_TRANS_GEOM_PARAMS_PAGE 0x1E 173 #define CH_DEVICE_CAP_PAGE 0x1F 174 175 /* 176 * Data returned by READ ELEMENT STATUS consists of an 8-byte header 177 * followed by one or more read_element_status_pages. 178 */ 179 struct read_element_status_header { 180 u_int8_t fear[2]; /* first element address reported */ 181 u_int8_t count[2]; /* number of elements available */ 182 u_int8_t reserved; 183 u_int8_t nbytes[3]; /* byte count of all pages */ 184 }; 185 186 struct read_element_status_page_header { 187 u_int8_t type; /* element type code; see type codes below */ 188 u_int8_t flags; 189 #define READ_ELEMENT_STATUS_AVOLTAG 0x40 190 #define READ_ELEMENT_STATUS_PVOLTAG 0x80 191 u_int8_t edl[2]; /* element descriptor length */ 192 u_int8_t reserved; 193 u_int8_t nbytes[3]; /* byte count of all descriptors */ 194 }; 195 196 /* 197 * Format of a volume tag 198 */ 199 200 struct volume_tag { 201 u_int8_t vif[32]; /* volume identification field */ 202 u_int8_t reserved[2]; 203 u_int8_t vsn[2]; /* volume sequence number */ 204 }; 205 206 struct read_element_status_descriptor { 207 u_int8_t eaddr[2]; /* element address */ 208 u_int8_t flags1; 209 210 #define READ_ELEMENT_STATUS_FULL 0x01 211 #define READ_ELEMENT_STATUS_IMPEXP 0x02 212 #define READ_ELEMENT_STATUS_EXCEPT 0x04 213 #define READ_ELEMENT_STATUS_ACCESS 0x08 214 #define READ_ELEMENT_STATUS_EXENAB 0x10 215 #define READ_ELEMENT_STATUS_INENAB 0x20 216 217 #define READ_ELEMENT_STATUS_MT_MASK1 0x05 218 #define READ_ELEMENT_STATUS_ST_MASK1 0x0c 219 #define READ_ELEMENT_STATUS_IE_MASK1 0x3f 220 #define READ_ELEMENT_STATUS_DT_MASK1 0x0c 221 222 u_int8_t reserved0; 223 u_int8_t sense_code; 224 u_int8_t sense_qual; 225 226 /* 227 * dt_scsi_flags and dt_scsi_addr are valid only on data transport 228 * elements. These bytes are undefined for all other element types. 229 */ 230 u_int8_t dt_scsi_flags; 231 232 #define READ_ELEMENT_STATUS_DT_LUNMASK 0x07 233 #define READ_ELEMENT_STATUS_DT_LUVALID 0x10 234 #define READ_ELEMENT_STATUS_DT_IDVALID 0x20 235 #define READ_ELEMENT_STATUS_DT_NOTBUS 0x80 236 237 u_int8_t dt_scsi_addr; 238 239 u_int8_t reserved1; 240 241 u_int8_t flags2; 242 #define READ_ELEMENT_STATUS_INVERT 0x40 243 #define READ_ELEMENT_STATUS_SVALID 0x80 244 u_int8_t ssea[2]; /* source storage element address */ 245 246 struct volume_tag pvoltag; /* omitted if PVOLTAG == 0 */ 247 struct volume_tag avoltag; /* omitted if AVOLTAG == 0 */ 248 249 /* Other data may follow */ 250 }; 251 252 /* XXX add data returned by REQUEST VOLUME ELEMENT ADDRESS */ 253 254 /* Element type codes */ 255 #define ELEMENT_TYPE_MASK 0x0f /* Note: these aren't bits */ 256 #define ELEMENT_TYPE_ALL 0x00 257 #define ELEMENT_TYPE_MT 0x01 258 #define ELEMENT_TYPE_ST 0x02 259 #define ELEMENT_TYPE_IE 0x03 260 #define ELEMENT_TYPE_DT 0x04 261 262 /* 263 * XXX The following definitions should be common to all SCSI device types. 264 */ 265 #define PGCODE_MASK 0x3f /* valid page number bits in pg_code */ 266 #define PGCODE_PS 0x80 /* indicates page is savable */ 267 268 /* 269 * Send volume tag information to the changer 270 */ 271 272 struct scsi_send_volume_tag { 273 u_int8_t opcode; 274 #define SEND_VOLUME_TAG 0xb6 275 u_int8_t byte2; 276 u_int8_t ea[2]; /* element address */ 277 u_int8_t reserved2; 278 u_int8_t sac; /* send action code */ 279 280 #define SEND_VOLUME_TAG_ASSERT_PRIMARY 0x08 281 #define SEND_VOLUME_TAG_ASSERT_ALTERNATE 0x09 282 #define SEND_VOLUME_TAG_REPLACE_PRIMARY 0x0a 283 #define SEND_VOLUME_TAG_REPLACE_ALTERNATE 0x0b 284 #define SEND_VOLUME_TAG_UNDEFINED_PRIMARY 0x0c 285 #define SEND_VOLUME_TAG_UNDEFINED_ALTERNATE 0x0d 286 287 u_int8_t reserved4[2]; 288 u_int8_t pll[2]; /* parameter list length */ 289 u_int8_t reserved5; 290 u_int8_t control; 291 }; 292 293 /* 294 * Parameter format for SEND VOLUME TAG 295 */ 296 297 struct scsi_send_volume_tag_parameters { 298 u_int8_t vitf[32]; /* volume tag identification template */ 299 u_int8_t reserved1[2]; 300 u_int8_t minvsn[2]; /* minimum volume sequence number */ 301 u_int8_t reserved2[2]; 302 u_int8_t maxvsn[2]; /* maximum volume sequence number */ 303 }; 304 305 /* 306 * Device capabilities page. 307 * 308 * This page defines characteristics of the elemenet types in the 309 * medium changer device. 310 * 311 * Note in the definitions below, the following abbreviations are 312 * used: 313 * MT Medium transport element (picker) 314 * ST Storage transport element (slot) 315 * IE Import/export element (portal) 316 * DT Data tranfer element (tape/disk drive) 317 */ 318 struct page_device_capabilities { 319 u_int8_t pg_code; /* page code (0x1f) */ 320 u_int8_t pg_length; /* page length (0x12) */ 321 322 /* 323 * The STOR_xx bits indicate that an element of a given 324 * type may provide independent storage for a unit of 325 * media. The top four bits of this value are reserved. 326 */ 327 u_int8_t stor; 328 #define STOR_MT 0x01 329 #define STOR_ST 0x02 330 #define STOR_IE 0x04 331 #define STOR_DT 0x08 332 333 u_int8_t reserved0; 334 335 /* 336 * The MOVE_TO_yy bits indicate the changer supports 337 * moving a unit of medium from an element of a given type to an 338 * element of type yy. This is used to determine if a given 339 * MOVE MEDIUM command is legal. The top four bits of each 340 * of these values are reserved. 341 */ 342 u_int8_t move_from[CHET_MAX + 1]; 343 #define MOVE_TO_MT 0x01 344 #define MOVE_TO_ST 0x02 345 #define MOVE_TO_IE 0x04 346 #define MOVE_TO_DT 0x08 347 348 u_int8_t reserved1[4]; 349 350 /* 351 * Similar to above, but for EXCHANGE MEDIUM. 352 */ 353 u_int8_t exchange_with[CHET_MAX + 1]; 354 #define EXCHANGE_WITH_MT 0x01 355 #define EXCHANGE_WITH_ST 0x02 356 #define EXCHANGE_WITH_IE 0x04 357 #define EXCHANGE_WITH_DT 0x08 358 }; 359 360 /* 361 * Medium changer elemement address assignment page. 362 * 363 * Some of these fields can be a little confusing, so an explanation 364 * is in order. 365 * 366 * Each component within a a medium changer apparatus is called an 367 * "element". 368 * 369 * The "medium transport element address" is the address of the first 370 * picker (robotic arm). "Number of medium transport elements" tells 371 * us how many pickers exist in the changer. 372 * 373 * The "first storage element address" is the address of the first 374 * slot in the tape or disk magazine. "Number of storage elements" tells 375 * us how many slots exist in the changer. 376 * 377 * The "first import/export element address" is the address of the first 378 * medium portal accessible both by the medium changer and an outside 379 * human operator. This is where the changer might deposit tapes destined 380 * for some vault. The "number of import/export elements" tells us 381 * not many of these portals exist in the changer. NOTE: this number may 382 * be 0. 383 * 384 * The "first data transfer element address" is the address of the first 385 * tape or disk drive in the changer. "Number of data transfer elements" 386 * tells us how many drives exist in the changer. 387 */ 388 struct page_element_address_assignment { 389 u_int8_t pg_code; /* page code (0x1d) */ 390 u_int8_t pg_length; /* page length (0x12) */ 391 392 /* Medium transport element address */ 393 u_int8_t mtea[2]; 394 395 /* Number of medium transport elements */ 396 u_int8_t nmte[2]; 397 398 /* First storage element address */ 399 u_int8_t fsea[2]; 400 401 /* Number of storage elements */ 402 u_int8_t nse[2]; 403 404 /* First import/export element address */ 405 u_int8_t fieea[2]; 406 407 /* Number of import/export elements */ 408 u_int8_t niee[2]; 409 410 /* First data transfer element address */ 411 u_int8_t fdtea[2]; 412 413 /* Number of data trafer elements */ 414 u_int8_t ndte[2]; 415 416 u_int8_t reserved[2]; 417 }; 418 419 /* 420 * Transport geometry parameters page. 421 * 422 * Defines whether each medium transport element is a member of a set of 423 * elements that share a common robotics subsystem and whether the element 424 * is capable of media rotation. One transport geometry descriptor is 425 * transferred for each medium transport element, beginning with the first 426 * medium transport element (other than the default transport element address 427 * of 0). 428 */ 429 struct page_transport_geometry_parameters { 430 u_int8_t pg_code; /* page code (0x1e) */ 431 u_int8_t pg_length; /* page length; variable */ 432 433 /* Transport geometry descriptor(s) are here. */ 434 435 u_int8_t misc; 436 #define CAN_ROTATE 0x01 437 438 /* Member number in transport element set. */ 439 u_int8_t member; 440 }; 441 442 __BEGIN_DECLS 443 void scsi_move_medium(struct ccb_scsiio *csio, u_int32_t retries, 444 void (*cbfcnp)(struct cam_periph *, union ccb *), 445 u_int8_t tag_action, u_int32_t tea, u_int32_t src, 446 u_int32_t dst, int invert, u_int8_t sense_len, 447 u_int32_t timeout); 448 449 void scsi_exchange_medium(struct ccb_scsiio *csio, u_int32_t retries, 450 void (*cbfcnp)(struct cam_periph *, union ccb *), 451 u_int8_t tag_action, u_int32_t tea, u_int32_t src, 452 u_int32_t dst1, u_int32_t dst2, int invert1, 453 int invert2, u_int8_t sense_len, u_int32_t timeout); 454 455 void scsi_position_to_element(struct ccb_scsiio *csio, u_int32_t retries, 456 void (*cbfcnp)(struct cam_periph *, union ccb *), 457 u_int8_t tag_action, u_int32_t tea, u_int32_t dst, 458 int invert, u_int8_t sense_len, 459 u_int32_t timeout); 460 461 void scsi_read_element_status(struct ccb_scsiio *csio, u_int32_t retries, 462 void (*cbfcnp)(struct cam_periph *, union ccb *), 463 u_int8_t tag_action, int voltag, u_int32_t sea, 464 u_int32_t count, u_int8_t *data_ptr, 465 u_int32_t dxfer_len, u_int8_t sense_len, 466 u_int32_t timeout); 467 468 void scsi_initialize_element_status(struct ccb_scsiio *csio, u_int32_t retries, 469 void (*cbfcnp)(struct cam_periph *, union ccb *), 470 u_int8_t tag_action, u_int8_t sense_len, 471 u_int32_t timeout); 472 void scsi_send_volume_tag(struct ccb_scsiio *csio, u_int32_t retries, 473 void (*cbfcnp)(struct cam_periph *, union ccb *), 474 u_int8_t tag_action, 475 u_int16_t element_address, 476 u_int8_t send_action_code, 477 struct scsi_send_volume_tag_parameters *parameters, 478 u_int8_t sense_len, u_int32_t timeout); 479 __END_DECLS 480 481 #endif /* _SCSI_SCSI_CH_H */ 482