sys/cam/scsi/scsi_ch.h

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