sys/dev/mscp/mscp.h

   1 /*      $NetBSD: mscp.h,v 1.6.38.3 2004/09/21 13:30:59 skrll Exp $      */
   2
   3 /*
   4  * Copyright (c) 1988 Regents of the University of California.
   5  * All rights reserved.
   6  *
   7  * This code is derived from software contributed to Berkeley by
   8  * Chris Torek.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  * 3. Neither the name of the University nor the names of its contributors
  19  *    may be used to endorse or promote products derived from this software
  20  *    without specific prior written permission.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32  * SUCH DAMAGE.
  33  *
  34  *      @(#)mscp.h      7.5 (Berkeley) 6/28/90
  35  */
  36
  37 /*
  38  * Definitions for the Mass Storage Control Protocol
  39  * I WISH I KNEW WHAT MORE OF THESE WERE.  IT SURE WOULD BE NICE
  40  * IF DEC SOLD DOCUMENTATION FOR THEIR OWN CONTROLLERS.
  41  */
  42
  43 /*
  44  * Control message opcodes
  45  */
  46 #define M_OP_ABORT      0x01    /* Abort command */
  47 #define M_OP_GETCMDST   0x02    /* Get command status command */
  48 #define M_OP_GETUNITST  0x03    /* Get unit status command */
  49 #define M_OP_SETCTLRC   0x04    /* Set controller characteristics command */
  50 #define M_OP_SEREX      0x07    /* Serious exception end message */
  51 #define M_OP_AVAILABLE  0x08    /* Available command */
  52 #define M_OP_ONLINE     0x09    /* Online command */
  53 #define M_OP_SETUNITC   0x0a    /* Set unit characteristics command */
  54 #define M_OP_DTACCPATH  0x0b    /* Determine access paths command */
  55 #define M_OP_ACCESS     0x10    /* Access command */
  56 #define M_OP_COMPCD     0x11    /* Compare controller data command */
  57 #define M_OP_ERASE      0x12    /* Erase command */
  58 #define M_OP_FLUSH      0x13    /* Flush command */
  59 #define M_OP_REPLACE    0x14    /* Replace command */
  60 #define M_OP_COMPHD     0x20    /* Compare host data command */
  61 #define M_OP_READ       0x21    /* Read command */
  62 #define M_OP_WRITE      0x22    /* Write command */
  63 #define M_OP_WRITM      0x24    /* Write mark command */
  64 #define M_OP_POS        0x25    /* Positioning command */
  65 #define M_OP_AVAILATTN  0x40    /* Available attention message */
  66 #define M_OP_DUPUNIT    0x41    /* Duplicate unit number attention message */
  67 #define M_OP_ACCPATH    0x42    /* Access path attention message */
  68 #define M_OP_END        0x80    /* End message flag */
  69
  70
  71 /*
  72  * Generic command modifiers
  73  */
  74 #define M_MD_EXPRS      0x8000  /* Express request */
  75 #define M_MD_COMP       0x4000  /* Compare */
  76 #define M_MD_CLSEX      0x2000  /* Clear serious exception */
  77 #define M_MD_ERROR      0x1000  /* Force error */
  78 #define M_MD_SCCHH      0x0800  /* Suppress caching (high speed) */
  79 #define M_MD_SCCHL      0x0400  /* Suppress caching (low speed) */
  80 #define M_MD_SECOR      0x0200  /* Suppress error correction */
  81 #define M_MD_SEREC      0x0100  /* Suppress error recovery */
  82 #define M_MD_SSHDW      0x0080  /* Suppress shadowing */
  83 #define M_MD_WBKNV      0x0040  /* Write back (non-volatile) */
  84 #define M_MD_WBKVL      0x0020  /* Write back (volatile) */
  85 #define M_MD_WRSEQ      0x0010  /* Write shadow set one unit at a time */
  86
  87 /*
  88  * tape command modifiers
  89  */
  90 #define M_MD_IMMEDIATE  0x0040  /* Immediate completion */
  91 #define M_MD_UNLOAD     0x0010  /* Unload tape */
  92 #define M_MD_REVERSE    0x0008  /* Reverse action */
  93 #define M_MD_OBJCOUNT   0x0004  /* Object count */
  94 #define M_MD_REWIND     0x0002  /* Rewind */
  95
  96 /*
  97  * AVAILABLE command modifiers
  98  */
  99 #define M_AVM_ALLCD     0x0002  /* All class drivers */
 100 #define M_AVM_SPINDOWN  0x0001  /* Spin down */
 101
 102 /*
 103  * FLUSH command modifiers
 104  */
 105 #define M_FLM_FLUSHENU  0x0001  /* Flush entire unit */
 106 #define M_FLM_VOLATILE  0x0002  /* Volatile only */
 107
 108 /*
 109  * GET UNIT STATUS command modifiers
 110  */
 111 #define M_GUM_NEXTUNIT  0x0001  /* Next unit */
 112
 113 /*
 114  * ONLINE command modifiers
 115  */
 116 #define M_OLM_RIP       0x0001  /* Allow self destruction */
 117 #define M_OLM_IGNMF     0x0002  /* Ignore media format error */
 118
 119 /*
 120  * ONLINE and SET UNIT CHARACTERISTICS command modifiers
 121  */
 122 #define M_OSM_ALTERHI   0x0020  /* Alter host identifier */
 123 #define M_OSM_SHADOWSP  0x0010  /* Shadow unit specified */
 124 #define M_OSM_CLEARWBL  0x0008  /* Clear write-back data lost */
 125 #define M_OSM_SETWRPROT 0x0004  /* Set write protect */
 126
 127 /*
 128  * REPLACE command modifiers
 129  */
 130 #define M_RPM_PRIMARY   0x0001  /* Primary replacement block */
 131
 132 /*
 133  * End message flags
 134  */
 135 #define M_EF_BBLKR      0x80    /* Bad block reported */
 136 #define M_EF_BBLKU      0x40    /* Bad block unreported */
 137 #define M_EF_ERLOG      0x20    /* Error log generated */
 138 #define M_EF_SEREX      0x10    /* Serious exception */
 139 #define M_EF_EOT        0x08    /* at end-of-tape */
 140 #define M_EF_POSLOST    0x04    /* position lost */
 141
 142 /*
 143  * Controller flags
 144  */
 145 #define M_CF_ATTN       0x80    /* Enable attention messages */
 146 #define M_CF_MISC       0x40    /* Enable miscellaneous error log messages */
 147 #define M_CF_OTHER      0x20    /* Enable other host's error log messages */
 148 #define M_CF_THIS       0x10    /* Enable this host's error log messages */
 149 #define M_CF_MLTHS      0x04    /* Multi-host */
 150 #define M_CF_SHADW      0x02    /* Shadowing */
 151 #define M_CF_576        0x01    /* 576 byte sectors */
 152
 153 /*
 154  * Unit flags
 155  */
 156 #define M_UF_REPLC      0x8000  /* Controller initiated bad block replacement */
 157 #define M_UF_INACT      0x4000  /* Inactive shadow set unit */
 158 #define M_UF_WRTPH      0x2000  /* Write protect (hardware) */
 159 #define M_UF_WRTPS      0x1000  /* Write protect (software or volume) */
 160 #define M_UF_SCCHH      0x8000  /* Suppress caching (high speed) */
 161 #define M_UF_SCCHL      0x4000  /* Suppress caching (low speed) */
 162 #define M_UF_RMVBL      0x0080  /* Removable media */
 163 #define M_UF_WBKNV      0x0040  /* Write back (non-volatile) */
 164 #define M_UF_576        0x0004  /* 576 byte sectors */
 165 #define M_UF_CMPWR      0x0002  /* Compare writes */
 166 #define M_UF_CMPRD      0x0001  /* Compare reads */
 167
 168 /*
 169  * Error Log message format codes
 170  */
 171 #define M_FM_CTLRERR    0x00    /* Controller error */
 172 #define M_FM_BUSADDR    0x01    /* Host memory access error */
 173 #define M_FM_DISKTRN    0x02    /* Disk transfer error */
 174 #define M_FM_SDI        0x03    /* SDI error */
 175 #define M_FM_SMLDSK     0x04    /* Small disk error */
 176 #define M_FM_TAPETRN    0x05    /* Tape transfer error */
 177 #define M_FM_STIERR     0x06    /* STI communication or command failure */
 178 #define M_FM_STIDEL     0x07    /* STI drive error log */
 179 #define M_FM_STIFEL     0x08    /* STI formatter error log */
 180
 181 /*
 182  * Error Log message flags
 183  */
 184 #define M_LF_SUCC       0x80    /* Operation successful */
 185 #define M_LF_CONT       0x40    /* Operation continuing */
 186 #define M_LF_SQNRS      0x01    /* Sequence number reset */
 187
 188 /*
 189  * Status codes
 190  */
 191 #define M_ST_MASK       0x1f    /* Status code mask */
 192 #define M_ST_SUCCESS    0x00    /* Success */
 193 #define M_ST_INVALCMD   0x01    /* Invalid command */
 194 #define M_ST_ABORTED    0x02    /* Command aborted */
 195 #define M_ST_OFFLINE    0x03    /* Unit offline */
 196 #define M_ST_AVAILABLE  0x04    /* Unit available */
 197 #define M_ST_MFMTERR    0x05    /* Media format error */
 198 #define M_ST_WRPROT     0x06    /* Write protected */
 199 #define M_ST_COMPERR    0x07    /* Compare error */
 200 #define M_ST_DATAERR    0x08    /* Data error */
 201 #define M_ST_HOSTBUFERR 0x09    /* Host buffer access error */
 202 #define M_ST_CTLRERR    0x0a    /* Controller error */
 203 #define M_ST_DRIVEERR   0x0b    /* Drive error */
 204 #define M_ST_FORMATTERR 0x0c    /* Formatter error */
 205 #define M_ST_BOT        0x0d    /* Beginning-of-tape */
 206 #define M_ST_TAPEMARK   0x0e    /* Tape mark encountered */
 207 #define M_ST_RDTRUNC    0x10    /* Record data truncated */
 208 #define M_ST_DIAG       0x1f    /* Message from an internal diagnostic */
 209
 210 /*
 211  * Subcodes of M_ST_OFFLINE
 212  */
 213 #define M_OFFLINE_UNKNOWN       (0 << 5) /* unknown or on other ctlr */
 214 #define M_OFFLINE_UNMOUNTED     (1 << 5) /* unmounted or RUN/STOP at STOP */
 215 #define M_OFFLINE_INOPERATIVE   (2 << 5) /* inoperative? */
 216 #define M_OFFLINE_DUPLICATE     (4 << 5) /* duplicate unit number */
 217 #define M_OFFLINE_INDIAGNOSTIC  (8 << 5) /* disabled by FS or diagnostic */
 218
 219 /*
 220  * An MSCP packet begins with a header giving the length of
 221  * the entire packet (including the header itself)(?), two bytes
 222  * of device specific data, and the a whole bunch of variants
 223  * depending on message type.
 224  *
 225  * N.B.:  In most cases we distinguish between a `command' and
 226  * an `end' variant as well.  The command variant is that which
 227  * is given to the controller; the `end' variant is its response.
 228  */
 229
 230 /*
 231  * Generic sequential message variant (command and response).
 232  */
 233 struct mscpv_seq {
 234         long    seq_bytecount;          /* byte count */
 235 #define seq_rbn         seq_bytecount   /* aka RBN (replace) */
 236 #define seq_outref      seq_bytecount   /* aka outref (abort/get cmd status) */
 237         long    seq_buffer;             /* buffer descriptor */
 238         long    seq_mapbase;            /* page map (first PTE) phys address */
 239         long    seq_xxx1;       /* ? */ /* unused */
 240         long    seq_lbn;                /* logical block number */
 241         long    seq_xxx2;       /* ? */ /* unused */
 242         long    *seq_addr;              /* pointer to cmd descriptor */
 243         long    seq_software[4];        /* reserved to software; unused */
 244 };
 245
 246 /*
 247  * Set Controller Characteristics command variant
 248  */
 249 struct mscpv_sccc {
 250         u_short sccc_version;           /* MSCP version number */
 251         u_short sccc_ctlrflags;         /* controller flags */
 252         u_short sccc_hosttimo;          /* host timeout */
 253         u_short sccc_usefrac;           /* use fraction */
 254         long    sccc_time;              /* time and date */
 255         long    sccc_time1;             /* it's a quad field */
 256         long    sccc_errlgfl;   /* ? */
 257         short   sccc_xxx2;      /* ? */
 258         short   sccc_copyspd;   /* ? */
 259 };
 260
 261 /*
 262  * Set Controller Characteristics end variant
 263  */
 264 struct mscpv_scce {
 265         u_short scce_version;           /* MSCP version number */
 266         u_short scce_ctlrflags;         /* controller flags */
 267         u_short scce_ctlrtimo;          /* controller timeout */
 268         u_short scce_ctlrcmdl;          /* ??? */
 269         quad_t  scce_ctlrid;            /* controller ID */
 270         long    scce_xxx[3];    /* ? */
 271         long    scce_volser;            /* volume serial number */
 272 };
 273
 274 /*
 275  * On Line command variant
 276  */
 277 struct mscpv_onlc {
 278         long    onlc_xxx1[4];   /* ? */
 279         long    onlc_errlgfl;           /* error log flag? */
 280         short   onlc_xxx2;      /* ? */
 281         short   onlc_copyspd;           /* copy speed? */
 282 };
 283
 284 /*
 285  * On Line end variant
 286  */
 287 struct mscpv_onle {
 288         long    onle_xxx1[3];   /* ? */
 289 /*???*/ short   onle_xxx2;      /* ? */
 290         u_char  onle_drivetype;         /* drive type index (same in guse) */
 291         char    onle_xxx3;      /* ? */
 292         long    onle_mediaid;           /* media type id (same in guse) */
 293         long    onle_xxx4;      /* ? */
 294         long    onle_unitsize;          /* unit size in sectors */
 295         long    onle_volser;            /* volume serial number */
 296 };
 297
 298 /*
 299  * Get Unit Status end variant (and Avail Attn?)
 300  */
 301 struct mscpv_guse {
 302         u_short guse_multunit;          /* multi-unit code */
 303         u_short guse_unitflags;         /* unit flags */
 304         long    guse_hostid;            /* host id */
 305         long    guse_unitid0;   /*???*/
 306         short   guse_unitid1;   /*???*/
 307         u_char  guse_drivetype;         /* drive type index */
 308         u_char  guse_unitid2;   /*???*/
 309         long    guse_mediaid;           /* media type id (encoded) */
 310         short   guse_shadowunit;        /* shadow unit */
 311         short   guse_shadowstat;        /* shadow status */
 312         u_short guse_nspt;              /* sectors per track */
 313         u_short guse_group;             /* track group size */
 314         u_short guse_ngpc;              /* groups per cylinder */
 315         u_short guse_xxx;               /* reserved */
 316         u_short guse_rctsize;           /* RCT size (sectors) */
 317         u_char  guse_nrpt;              /* RBNs per track */
 318         u_char  guse_nrct;              /* number of RCTs */
 319 };
 320
 321 /*
 322  * Macros to break up and build media IDs.  An ID encodes the port
 323  * type in the top 10 bits, and the drive type in the remaining 22.
 324  * The 10 bits, and 15 of the 22, are in groups of 5, with the value
 325  * 0 representing space and values 1..26 representing A..Z.  The low
 326  * 7 bits represent a number in 0..127.  Hence an RA81 on a UDA50
 327  * is <D><U><R><A>< >81, or 0x25641051.  This encoding scheme is known
 328  * in part in uda.c.
 329  *
 330  * The casts below are just to make pcc generate better code.
 331  */
 332 #define MSCP_MEDIA_PORT(id)     (((long)(id) >> 22) & 0x3ff)    /* port */
 333 #define MSCP_MEDIA_DRIVE(id)    ((long)(id) & 0x003fffff)       /* drive */
 334 #define MSCP_MID_ECH(n, id)     (((int)(id) >> ((n) * 5 + 7)) & 0x1f)
 335 #define MSCP_MID_CHAR(n, id) \
 336         (MSCP_MID_ECH(n, id) ? MSCP_MID_ECH(n, id) + '@' : ' ')
 337 #define MSCP_MID_NUM(id)        ((id) & 0x7f)
 338 /* for, e.g., RA81 */
 339 #define MSCP_MKDRIVE2(a, b, n) \
 340         (((a) - '@') << 17 | ((b) - '@') << 12 | (n))
 341 /* for, e.g., RRD50 */
 342 #define MSCP_MKDRIVE3(a, b, c, n) \
 343         (((a) - '@') << 17 | ((b) - '@') << 12 | ((c) - '@') << 7 | (n))
 344
 345 /*
 346  * Error datagram variant.
 347  */
 348 struct mscpv_erd {
 349         quad_t  erd_ctlrid;             /* controller ID */
 350         u_char  erd_ctlrsoftware;       /* controller software version */
 351         u_char  erd_ctlrhardware;       /* controller hardware version */
 352         u_short erd_multiunit;          /* multi-unit code (?) */
 353         union {
 354                 u_long  un_busaddr;     /* bus address, if mem access err */
 355                 quad_t  un_unitid;      /* unit id, otherwise */
 356         } erd_un1;
 357 #define erd_busaddr     erd_un1.un_busaddr
 358 #define erd_unitid      erd_un1.un_unitid
 359         u_char  erd_unitsoftware;       /* unit software version */
 360         u_char  erd_unithardware;       /* unit hardware version */
 361         union {
 362                 u_char  un_b[2];        /* level, retry (if disk xfer err) */
 363                 u_short un_s;           /* cylinder (if small disk error) */
 364         } erd_un2;
 365 #define erd_level       erd_un2.un_b[0]
 366 #define erd_retry       erd_un2.un_b[1]
 367 #define erd_sdecyl      erd_un2.un_s
 368         long    erd_volser;             /* volume serial number */
 369         u_long  erd_hdr;                /* `header' (block number) */
 370         u_char  erd_sdistat[12];        /* SDI status information (?) */
 371 };
 372
 373 /*
 374  * I am making brash assumptions about the first four bytes of all
 375  * MSCP packets.  These appear to be true for both UDA50s and TMSCP
 376  * devices (TU81, TA81, TK50).  DEC claim that these four bytes are
 377  * not part of MSCP itself, yet at least the length is necessary
 378  * for, e.g., error checking.
 379  */
 380 struct mscp {
 381         u_short mscp_msglen;            /* length in bytes */
 382         u_char  mscp_msgtc;             /* type (high 4 bits) and credits */
 383         u_char  mscp_vcid;              /* virtual circuit ID */
 384         long    mscp_cmdref;            /* command reference number */
 385         u_short mscp_unit;              /* unit number */
 386         u_short mscp_seqnum;            /* sequence number */
 387         u_char  mscp_opcode;            /* opcode */
 388 #define mscp_format     mscp_opcode     /* aka format (datagrams) */
 389         u_char  mscp_flags;             /* flags */
 390         u_short mscp_modifier;          /* modifier (commands) */
 391 #define mscp_status     mscp_modifier   /* aka status (ends) */
 392 #define mscp_event      mscp_modifier   /* aka event (datagrams) */
 393         union {
 394                 struct  mscpv_seq un_seq;       /* generic sequential msg */
 395                 struct  mscpv_sccc un_sccc;     /* SCC command */
 396                 struct  mscpv_scce un_scce;     /* SCC end */
 397                 struct  mscpv_onlc un_onlc;     /* on line command */
 398                 struct  mscpv_onle un_onle;     /* on line end */
 399                 struct  mscpv_guse un_guse;     /* get unit status */
 400                 struct  mscpv_erd un_erd;       /* error datagram */
 401         } mscp_un;
 402 /*???*/ long    mscp_xxx;               /* pad to 64 bytes */
 403 };
 404
 405 /*
 406  * Define message length according to the DEC specifications by dropping
 407  * the four byte header.
 408  */
 409 #define MSCP_MSGLEN     (sizeof (struct mscp) - 4)
 410
 411 /*
 412  * Shorthand
 413  */
 414
 415 /*
 416  * Generic packet
 417  */
 418 #define mscp_seq        mscp_un.un_seq
 419
 420 /*
 421  * Set Controller Characteristics packet
 422  */
 423 #define mscp_sccc       mscp_un.un_sccc
 424
 425 /*
 426  * Set Controller Characteristics end packet
 427  */
 428 #define mscp_scce       mscp_un.un_scce
 429
 430 /*
 431  * Online / Set Unit Characteristics command packet
 432  */
 433 #define mscp_onlc       mscp_un.un_onlc
 434
 435 /*
 436  * Online end packet
 437  */
 438 #define mscp_onle       mscp_un.un_onle
 439
 440 /*
 441  * Get Unit Status end packet
 442  */
 443 #define mscp_guse       mscp_un.un_guse
 444
 445 /*
 446  * MSCP Error Log packet
 447  */
 448 #define mscp_erd        mscp_un.un_erd
 449
 450 /*
 451  * MSCP seq_addr field actually belongs to overall packet.
 452  */
 453 #define mscp_addr       mscp_seq.seq_addr
 454
 455 /*
 456  * Macros to break up mscp_msgtc, and types.
 457  */
 458 #define MSCP_MSGTYPE(m) ((m) & 0xf0)
 459 #define MSCP_CREDITS(m) ((m) & 0x0f)
 460
 461 #define MSCPT_SEQ               0x00    /* sequential message */
 462 #define MSCPT_DATAGRAM          0x10    /* error datagram */
 463 #define MSCPT_CREDITS           0x20    /* credit notification */
 464 #define MSCPT_MAINTENANCE       0xf0    /* who knows */
 465
 466
 467 /*
 468  * Here begin more perhaps brash assumptions about MSCP devices...
 469  */
 470
 471 /*
 472  * MSCP controllers have `command rings' and `response rings'.  A
 473  * command ring is a pool of MSCP packets that the host uses to give
 474  * commands to the controller; a response ring is a pool of MSCP
 475  * packets that the controller uses to give back responses.  Entries
 476  * in the command and response rings are `owned' by either the host
 477  * or the controller; only the owner is allowed to alter any of the
 478  * fields in the MSCP packet.  Thus, free command packets are owned
 479  * by the host, and free response packets by the controller.  When
 480  * the host gives a packet to the controller, it tells the controller
 481  * by touching a device register; when the controller gives a response
 482  * to the host, it generates an interrupt if enabled, and sets
 483  * a device register as well.
 484  *
 485  * The pool is `described' by a set of pointers to the packets, along
 486  * with the two flags below.
 487  */
 488 #define MSCP_OWN        0x80000000      /* controller owns this packet */
 489 #define MSCP_INT        0x40000000      /* controller should interrupt */