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