1 /* $NetBSD: scsi_changer.h,v 1.11 1998/02/13 08:28:32 enami Exp $ */ 2 3 /*- 4 * SPDX-License-Identifier: BSD-4-Clause 5 * 6 * Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com> 7 * All rights reserved. 8 * 9 * Partially based on an autochanger driver written by Stefan Grefen 10 * and on an autochanger driver written by the Systems Programming Group 11 * at the University of Utah Computer Science Department. 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions 15 * are met: 16 * 1. Redistributions of source code must retain the above copyright 17 * notice, this list of conditions and the following disclaimer. 18 * 2. Redistributions in binary form must reproduce the above copyright 19 * notice, this list of conditions and the following disclaimer in the 20 * documentation and/or other materials provided with the distribution. 21 * 3. All advertising materials mentioning features or use of this software 22 * must display the following acknowledgements: 23 * This product includes software developed by Jason R. Thorpe 24 * for And Communications, http://www.and.com/ 25 * 4. The name of the author may not be used to endorse or promote products 26 * derived from this software without specific prior written permission. 27 * 28 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 29 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 30 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 31 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 32 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 33 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 34 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 35 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 36 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 37 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 38 * SUCH DAMAGE. 39 */ 40 41 /* 42 * SCSI changer interface description 43 */ 44 45 /*- 46 * Partially derived from software written by Stefan Grefen 47 * (grefen@goofy.zdv.uni-mainz.de soon grefen@convex.com) 48 * based on the SCSI System by written Julian Elischer (julian@tfs.com) 49 * for TRW Financial Systems. 50 * 51 * TRW Financial Systems, in accordance with their agreement with Carnegie 52 * Mellon University, makes this software available to CMU to distribute 53 * or use in any manner that they see fit as long as this message is kept with 54 * the software. For this reason TFS also grants any other persons or 55 * organisations permission to use or modify this software. 56 * 57 * TFS supplies this software to be publicly redistributed 58 * on the understanding that TFS is not responsible for the correct 59 * functioning of this software in any circumstances. 60 * 61 * Ported to run under 386BSD by Julian Elischer (julian@tfs.com) Sept 1992 62 */ 63 64 #ifndef _SCSI_SCSI_CH_H 65 #define _SCSI_SCSI_CH_H 1 66 67 #include <sys/cdefs.h> 68 69 /* 70 * SCSI command format 71 */ 72 73 /* 74 * Exchange the medium in the source element with the medium 75 * located at the destination element. 76 */ 77 struct scsi_exchange_medium { 78 uint8_t opcode; 79 #define EXCHANGE_MEDIUM 0xa6 80 uint8_t byte2; 81 uint8_t tea[2]; /* transport element address */ 82 uint8_t src[2]; /* source address */ 83 uint8_t fdst[2]; /* first destination address */ 84 uint8_t sdst[2]; /* second destination address */ 85 uint8_t invert; 86 #define EXCHANGE_MEDIUM_INV1 0x01 87 #define EXCHANGE_MEDIUM_INV2 0x02 88 uint8_t control; 89 }; 90 91 /* 92 * Cause the medium changer to check all elements for medium and any 93 * other status relevant to the element. 94 */ 95 struct scsi_initialize_element_status { 96 uint8_t opcode; 97 #define INITIALIZE_ELEMENT_STATUS 0x07 98 uint8_t byte2; 99 uint8_t reserved[3]; 100 uint8_t control; 101 }; 102 103 /* 104 * Request the changer to move a unit of media from the source element 105 * to the destination element. 106 */ 107 struct scsi_move_medium { 108 uint8_t opcode; 109 uint8_t byte2; 110 uint8_t tea[2]; /* transport element address */ 111 uint8_t src[2]; /* source element address */ 112 uint8_t dst[2]; /* destination element address */ 113 uint8_t reserved[2]; 114 uint8_t invert; 115 #define MOVE_MEDIUM_INVERT 0x01 116 uint8_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 uint8_t opcode; 125 uint8_t byte2; 126 uint8_t tea[2]; /* transport element address */ 127 uint8_t dst[2]; /* destination element address */ 128 uint8_t reserved[2]; 129 uint8_t invert; 130 #define POSITION_TO_ELEMENT_INVERT 0x01 131 uint8_t control; 132 }; 133 134 /* 135 * Request that the changer report the status of its internal elements. 136 */ 137 struct scsi_read_element_status { 138 uint8_t opcode; 139 uint8_t byte2; 140 #define READ_ELEMENT_STATUS_VOLTAG 0x10 /* report volume tag info */ 141 /* ...next 4 bits are an element type code... */ 142 uint8_t sea[2]; /* starting element address */ 143 uint8_t count[2]; /* number of elements */ 144 uint8_t flags; 145 #define READ_ELEMENT_STATUS_DVCID 0x01 /* report device serial number */ 146 #define READ_ELEMENT_STATUS_CURDATA 0x02 /* allow motion during command */ 147 148 uint8_t len[3]; /* length of data buffer */ 149 uint8_t reserved1; 150 uint8_t control; 151 }; 152 153 struct scsi_request_volume_element_address { 154 uint8_t opcode; 155 uint8_t byte2; 156 #define REQUEST_VOLUME_ELEMENT_ADDRESS_VOLTAG 0x10 157 /* ...next 4 bits are an element type code... */ 158 uint8_t eaddr[2]; /* element address */ 159 uint8_t count[2]; /* number of elements */ 160 uint8_t reserved0; 161 uint8_t len[3]; /* length of data buffer */ 162 uint8_t reserved1; 163 uint8_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 uint8_t fear[2]; /* first element address reported */ 181 uint8_t count[2]; /* number of elements available */ 182 uint8_t reserved; 183 uint8_t nbytes[3]; /* byte count of all pages */ 184 }; 185 186 struct read_element_status_page_header { 187 uint8_t type; /* element type code; see type codes below */ 188 uint8_t flags; 189 #define READ_ELEMENT_STATUS_AVOLTAG 0x40 190 #define READ_ELEMENT_STATUS_PVOLTAG 0x80 191 uint8_t edl[2]; /* element descriptor length */ 192 uint8_t reserved; 193 uint8_t nbytes[3]; /* byte count of all descriptors */ 194 }; 195 196 /* 197 * Format of a volume tag 198 */ 199 200 struct volume_tag { 201 uint8_t vif[32]; /* volume identification field */ 202 uint8_t reserved[2]; 203 uint8_t vsn[2]; /* volume sequence number */ 204 }; 205 206 struct read_element_status_device_id { 207 uint8_t prot_code_set; 208 #define READ_ELEMENT_STATUS_CODE_SET(p) ((p) & 0x0F) 209 #define READ_ELEMENT_STATUS_PROTOCOL_ID(p) ((p) >> 4) 210 211 uint8_t piv_assoc_designator_type; 212 #define READ_ELEMENT_STATUS_PIV_SET 0x80 213 #define READ_ELEMENT_STATUS_ASSOCIATION(p) ((p) >> 4) 214 #define READ_ELEMENT_STATUS_DESIGNATOR_TYPE(p) ((p) & 0x0F) 215 216 uint8_t reserved2; 217 uint8_t designator_length; 218 uint8_t designator[256]; /* Allocate max length */ 219 }; 220 221 struct read_element_status_descriptor { 222 uint8_t eaddr[2]; /* element address */ 223 uint8_t flags1; 224 225 #define READ_ELEMENT_STATUS_FULL 0x01 226 #define READ_ELEMENT_STATUS_IMPEXP 0x02 227 #define READ_ELEMENT_STATUS_EXCEPT 0x04 228 #define READ_ELEMENT_STATUS_ACCESS 0x08 229 #define READ_ELEMENT_STATUS_EXENAB 0x10 230 #define READ_ELEMENT_STATUS_INENAB 0x20 231 232 #define READ_ELEMENT_STATUS_MT_MASK1 0x05 233 #define READ_ELEMENT_STATUS_ST_MASK1 0x0c 234 #define READ_ELEMENT_STATUS_IE_MASK1 0x3f 235 #define READ_ELEMENT_STATUS_DT_MASK1 0x0c 236 237 uint8_t reserved0; 238 uint8_t sense_code; 239 uint8_t sense_qual; 240 241 union { 242 struct { 243 uint8_t dt_scsi_flags; 244 245 #define READ_ELEMENT_STATUS_DT_LUNMASK 0x07 246 #define READ_ELEMENT_STATUS_DT_LUVALID 0x10 247 #define READ_ELEMENT_STATUS_DT_IDVALID 0x20 248 #define READ_ELEMENT_STATUS_DT_NOTBUS 0x80 249 250 uint8_t dt_scsi_addr; 251 uint8_t reserved1; 252 } scsi_2; 253 254 /* reserved and obsolete (as of SCSI-3) fields */ 255 uint8_t reserved_or_obsolete[3]; 256 } dt_or_obsolete; 257 258 uint8_t flags2; 259 #define READ_ELEMENT_STATUS_INVERT 0x40 260 #define READ_ELEMENT_STATUS_SVALID 0x80 261 #define READ_ELEMENT_STATUS_ED 0x80 262 #define READ_ELEMENT_STATUS_MEDIA_TYPE_MASK 0x07 263 264 uint8_t ssea[2]; /* source storage element address */ 265 266 union { 267 struct volume_tag pvoltag; 268 struct volume_tag voltag[2]; 269 struct read_element_status_device_id devid; 270 struct { 271 struct volume_tag pvoltag; 272 struct read_element_status_device_id devid; 273 } pvol_and_devid; 274 struct { 275 struct volume_tag voltag[2]; 276 struct read_element_status_device_id devid; 277 } vol_tags_and_devid; 278 } voltag_devid; 279 }; 280 281 /* XXX add data returned by REQUEST VOLUME ELEMENT ADDRESS */ 282 283 /* Element type codes */ 284 #define ELEMENT_TYPE_MASK 0x0f /* Note: these aren't bits */ 285 #define ELEMENT_TYPE_ALL 0x00 286 #define ELEMENT_TYPE_MT 0x01 287 #define ELEMENT_TYPE_ST 0x02 288 #define ELEMENT_TYPE_IE 0x03 289 #define ELEMENT_TYPE_DT 0x04 290 291 /* 292 * XXX The following definitions should be common to all SCSI device types. 293 */ 294 #define PGCODE_MASK 0x3f /* valid page number bits in pg_code */ 295 #define PGCODE_PS 0x80 /* indicates page is savable */ 296 297 /* 298 * Send volume tag information to the changer 299 */ 300 301 struct scsi_send_volume_tag { 302 uint8_t opcode; 303 #define SEND_VOLUME_TAG 0xb6 304 uint8_t byte2; 305 uint8_t ea[2]; /* element address */ 306 uint8_t reserved2; 307 uint8_t sac; /* send action code */ 308 309 #define SEND_VOLUME_TAG_ASSERT_PRIMARY 0x08 310 #define SEND_VOLUME_TAG_ASSERT_ALTERNATE 0x09 311 #define SEND_VOLUME_TAG_REPLACE_PRIMARY 0x0a 312 #define SEND_VOLUME_TAG_REPLACE_ALTERNATE 0x0b 313 #define SEND_VOLUME_TAG_UNDEFINED_PRIMARY 0x0c 314 #define SEND_VOLUME_TAG_UNDEFINED_ALTERNATE 0x0d 315 316 uint8_t reserved4[2]; 317 uint8_t pll[2]; /* parameter list length */ 318 uint8_t reserved5; 319 uint8_t control; 320 }; 321 322 /* 323 * Parameter format for SEND VOLUME TAG 324 */ 325 326 struct scsi_send_volume_tag_parameters { 327 uint8_t vitf[32]; /* volume tag identification template */ 328 uint8_t reserved1[2]; 329 uint8_t minvsn[2]; /* minimum volume sequence number */ 330 uint8_t reserved2[2]; 331 uint8_t maxvsn[2]; /* maximum volume sequence number */ 332 }; 333 334 /* 335 * Device capabilities page. 336 * 337 * This page defines characteristics of the element types in the 338 * medium changer device. 339 * 340 * Note in the definitions below, the following abbreviations are 341 * used: 342 * MT Medium transport element (picker) 343 * ST Storage transport element (slot) 344 * IE Import/export element (portal) 345 * DT Data transfer element (tape/disk drive) 346 */ 347 struct page_device_capabilities { 348 uint8_t pg_code; /* page code (0x1f) */ 349 uint8_t pg_length; /* page length (0x12) */ 350 351 /* 352 * The STOR_xx bits indicate that an element of a given 353 * type may provide independent storage for a unit of 354 * media. The top four bits of this value are reserved. 355 */ 356 uint8_t stor; 357 #define STOR_MT 0x01 358 #define STOR_ST 0x02 359 #define STOR_IE 0x04 360 #define STOR_DT 0x08 361 362 uint8_t reserved0; 363 364 /* 365 * The MOVE_TO_yy bits indicate the changer supports 366 * moving a unit of medium from an element of a given type to an 367 * element of type yy. This is used to determine if a given 368 * MOVE MEDIUM command is legal. The top four bits of each 369 * of these values are reserved. 370 */ 371 uint8_t move_from[CHET_MAX + 1]; 372 #define MOVE_TO_MT 0x01 373 #define MOVE_TO_ST 0x02 374 #define MOVE_TO_IE 0x04 375 #define MOVE_TO_DT 0x08 376 377 uint8_t reserved1[4]; 378 379 /* 380 * Similar to above, but for EXCHANGE MEDIUM. 381 */ 382 uint8_t exchange_with[CHET_MAX + 1]; 383 #define EXCHANGE_WITH_MT 0x01 384 #define EXCHANGE_WITH_ST 0x02 385 #define EXCHANGE_WITH_IE 0x04 386 #define EXCHANGE_WITH_DT 0x08 387 }; 388 389 /* 390 * Medium changer elemement address assignment page. 391 * 392 * Some of these fields can be a little confusing, so an explanation 393 * is in order. 394 * 395 * Each component within a medium changer apparatus is called an 396 * "element". 397 * 398 * The "medium transport element address" is the address of the first 399 * picker (robotic arm). "Number of medium transport elements" tells 400 * us how many pickers exist in the changer. 401 * 402 * The "first storage element address" is the address of the first 403 * slot in the tape or disk magazine. "Number of storage elements" tells 404 * us how many slots exist in the changer. 405 * 406 * The "first import/export element address" is the address of the first 407 * medium portal accessible both by the medium changer and an outside 408 * human operator. This is where the changer might deposit tapes destined 409 * for some vault. The "number of import/export elements" tells us 410 * not many of these portals exist in the changer. NOTE: this number may 411 * be 0. 412 * 413 * The "first data transfer element address" is the address of the first 414 * tape or disk drive in the changer. "Number of data transfer elements" 415 * tells us how many drives exist in the changer. 416 */ 417 struct page_element_address_assignment { 418 uint8_t pg_code; /* page code (0x1d) */ 419 uint8_t pg_length; /* page length (0x12) */ 420 421 /* Medium transport element address */ 422 uint8_t mtea[2]; 423 424 /* Number of medium transport elements */ 425 uint8_t nmte[2]; 426 427 /* First storage element address */ 428 uint8_t fsea[2]; 429 430 /* Number of storage elements */ 431 uint8_t nse[2]; 432 433 /* First import/export element address */ 434 uint8_t fieea[2]; 435 436 /* Number of import/export elements */ 437 uint8_t niee[2]; 438 439 /* First data transfer element address */ 440 uint8_t fdtea[2]; 441 442 /* Number of data transfer elements */ 443 uint8_t ndte[2]; 444 445 uint8_t reserved[2]; 446 }; 447 448 /* 449 * Transport geometry parameters page. 450 * 451 * Defines whether each medium transport element is a member of a set of 452 * elements that share a common robotics subsystem and whether the element 453 * is capable of media rotation. One transport geometry descriptor is 454 * transferred for each medium transport element, beginning with the first 455 * medium transport element (other than the default transport element address 456 * of 0). 457 */ 458 struct page_transport_geometry_parameters { 459 uint8_t pg_code; /* page code (0x1e) */ 460 uint8_t pg_length; /* page length; variable */ 461 462 /* Transport geometry descriptor(s) are here. */ 463 464 uint8_t misc; 465 #define CAN_ROTATE 0x01 466 467 /* Member number in transport element set. */ 468 uint8_t member; 469 }; 470 471 __BEGIN_DECLS 472 void scsi_move_medium(struct ccb_scsiio *csio, uint32_t retries, 473 void (*cbfcnp)(struct cam_periph *, union ccb *), 474 uint8_t tag_action, uint32_t tea, uint32_t src, 475 uint32_t dst, int invert, uint8_t sense_len, 476 uint32_t timeout); 477 478 void scsi_exchange_medium(struct ccb_scsiio *csio, uint32_t retries, 479 void (*cbfcnp)(struct cam_periph *, union ccb *), 480 uint8_t tag_action, uint32_t tea, uint32_t src, 481 uint32_t dst1, uint32_t dst2, int invert1, 482 int invert2, uint8_t sense_len, uint32_t timeout); 483 484 void scsi_position_to_element(struct ccb_scsiio *csio, uint32_t retries, 485 void (*cbfcnp)(struct cam_periph *, union ccb *), 486 uint8_t tag_action, uint32_t tea, uint32_t dst, 487 int invert, uint8_t sense_len, 488 uint32_t timeout); 489 490 void scsi_read_element_status(struct ccb_scsiio *csio, uint32_t retries, 491 void (*cbfcnp)(struct cam_periph *, union ccb *), 492 uint8_t tag_action, int voltag, uint32_t sea, 493 int curdata, int dvcid, 494 uint32_t count, uint8_t *data_ptr, 495 uint32_t dxfer_len, uint8_t sense_len, 496 uint32_t timeout); 497 498 void scsi_initialize_element_status(struct ccb_scsiio *csio, uint32_t retries, 499 void (*cbfcnp)(struct cam_periph *, union ccb *), 500 uint8_t tag_action, uint8_t sense_len, 501 uint32_t timeout); 502 void scsi_send_volume_tag(struct ccb_scsiio *csio, uint32_t retries, 503 void (*cbfcnp)(struct cam_periph *, union ccb *), 504 uint8_t tag_action, 505 uint16_t element_address, 506 uint8_t send_action_code, 507 struct scsi_send_volume_tag_parameters *parameters, 508 uint8_t sense_len, uint32_t timeout); 509 __END_DECLS 510 511 #endif /* _SCSI_SCSI_CH_H */ 512