sys/dev/disk/isp/isp_tpublic.h

   1 /* $FreeBSD: src/sys/dev/isp/isp_tpublic.h,v 1.2.4.3 2001/10/08 05:57:06 mjacob Exp $ */
   2 /* $DragonFly: src/sys/dev/disk/isp/isp_tpublic.h,v 1.2 2003/06/17 04:28:27 dillon Exp $ */
   3 /*
   4  * Qlogic ISP Host Adapter Public Target Interface Structures && Routines
   5  *---------------------------------------
   6  * Copyright (c) 2000 by Matthew Jacob
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions, and the following disclaimer,
  14  *    without modification, immediately at the beginning of the file.
  15  * 2. The name of the author may not be used to endorse or promote products
  16  *    derived from this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  22  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28  * SUCH DAMAGE.
  29  *
  30  * Matthew Jacob
  31  * Feral Software
  32  * mjacob@feral.com
  33  */
  34
  35 /*
  36  * Required software target mode message and event handling structures.
  37  *
  38  * The message and event structures are used by the MI layer
  39  * to propagate messages and events upstream.
  40  */
  41
  42 #ifndef IN_MSGLEN
  43 #define IN_MSGLEN       8
  44 #endif
  45 typedef struct {
  46         void *          nt_hba;                 /* HBA tag */
  47         u_int64_t       nt_iid;                 /* inititator id */
  48         u_int64_t       nt_tgt;                 /* target id */
  49         u_int64_t       nt_lun;                 /* logical unit */
  50         u_int8_t        nt_bus;                 /* bus */
  51         u_int8_t        nt_tagtype;             /* tag type */
  52         u_int16_t       nt_tagval;              /* tag value */
  53         u_int8_t        nt_msg[IN_MSGLEN];      /* message content */
  54 } tmd_msg_t;
  55
  56 typedef struct {
  57         void *          ev_hba;                 /* HBA tag */
  58         u_int16_t       ev_bus;                 /* bus */
  59         u_int16_t       ev_event;               /* type of async event */
  60 } tmd_event_t;
  61
  62 /*
  63  * Suggested Software Target Mode Command Handling structure.
  64  *
  65  * A note about terminology:
  66  *
  67  *   MD stands for "Machine Dependent".
  68  *
  69  *    This driver is structured in three layers: Outer MD, core, and inner MD.
  70  *    The latter also is bus dependent (i.e., is cognizant of PCI bus issues
  71  *    as well as platform issues).
  72  *
  73  *
  74  *   "Outer Layer" means "Other Module"
  75  *
  76  *    Some additional module that actually implements SCSI target command
  77  *    policy is the recipient of incoming commands and the source of the
  78  *    disposition for them.
  79  *
  80  * The command structure below is one suggested possible MD command structure,
  81  * but since the handling of thbis is entirely in the MD layer, there is
  82  * no explicit or implicit requirement that it be used.
  83  *
  84  * The cd_private tag should be used by the MD layer to keep a free list
  85  * of these structures. Code outside of this driver can then use this
  86  * as an to identify it's own unit structures. That is, when not on the MD
  87  * layer's freelist, the MD layer should shove into it the identifier
  88  * that the outer layer has for it- passed in on an initial QIN_HBA_REG
  89  * call (see below).
  90  *
  91  * The cd_hba tag is a tag that uniquely identifies the HBA this target
  92  * mode command is coming from. The outer layer has to pass this back
  93  * unchanged to avoid chaos.
  94  *
  95  * The cd_iid, cd_tgt, cd_lun and cd_bus tags are used to identify the
  96  * id of the initiator who sent us a command, the target claim to be, the
  97  * lun on the target we claim to be, and the bus instance (for multiple
  98  * bus host adapters) that this applies to (consider it an extra Port
  99  * parameter). The iid, tgt and lun values are deliberately chosen to be
 100  * fat so that, for example, World Wide Names can be used instead of
 101  * the units that the Qlogic firmware uses (in the case where the MD
 102  * layer maintains a port database, for example).
 103  *
 104  * The cd_tagtype field specifies what kind of command tag has been
 105  * sent with the command. The cd_tagval is the tag's value (low 16
 106  * bits). It also contains (in the upper 16 bits) any command handle.
 107  *
 108  *
 109  * N.B.: when the MD layer sends this command to outside software
 110  * the outside software likely *MUST* return the same cd_tagval that
 111  * was in place because this value is likely what the Qlogic f/w uses
 112  * to identify a command.
 113  *
 114  * The cd_cdb contains storage for the passed in command descriptor block.
 115  * This is the maximum size we can get out of the Qlogic f/w. There's no
 116  * passed in length because whoever decodes the command to act upon it
 117  * will know what the appropriate length is.
 118  *
 119  * The tag cd_lflags are the flags set by the MD driver when it gets
 120  * command incoming or when it needs to inform any outside entities
 121  * that the last requested action failed.
 122  *
 123  * The tag cd_hflags should be set by any outside software to indicate
 124  * the validity of sense and status fields (defined below) and to indicate
 125  * the direction data is expected to move. It is an error to have both
 126  * CDFH_DATA_IN and CDFH_DATA_OUT set.
 127  *
 128  * If the CDFH_STSVALID flag is set, the command should be completed (after
 129  * sending any data and/or status). If CDFH_SNSVALID is set and the MD layer
 130  * can also handle sending the associated sense data (either back with an
 131  * FCP RESPONSE IU for Fibre Channel or otherwise automatically handling a
 132  * REQUEST SENSE from the initator for this target/lun), the MD layer will
 133  * set the CDFL_SENTSENSE flag on successful transmission of the sense data.
 134  * It is an error for the CDFH_SNSVALID bit to be set and CDFH_STSVALID not
 135  * to be set. It is an error for the CDFH_SNSVALID be set and the associated
 136  * SCSI status (cd_scsi_status) not be set to CHECK CONDITON.
 137  *
 138  * The tag cd_data points to a data segment to either be filled or
 139  * read from depending on the direction of data movement. The tag
 140  * is undefined if no data direction is set. The MD layer and outer
 141  * layers must agree on the meaning of cd_data.
 142  *
 143  * The tag cd_totlen is the total data amount expected to be moved
 144  * over the life of the command. It *may* be set by the MD layer, possibly
 145  * from the datalen field of an FCP CMND IU unit. If it shows up in the outer
 146  * layers set to zero and the CDB indicates data should be moved, the outer
 147  * layer should set it to the amount expected to be moved.
 148  *
 149  * The tag cd_resid should be the total residual of data not transferred.
 150  * The outer layers need to set this at the begining of command processing
 151  * to equal cd_totlen. As data is successfully moved, this value is decreased.
 152  * At the end of a command, any nonzero residual indicates the number of bytes
 153  * requested but not moved. XXXXXXXXXXXXXXXXXXXXXXX TOO VAGUE!!!
 154  *
 155  * The tag cd_xfrlen is the length of the currently active data transfer.
 156  * This allows several interations between any outside software and the
 157  * MD layer to move data.
 158  *
 159  * The reason that total length and total residual have to be tracked
 160  * is that fibre channel FCP DATA IU units have to have a relative
 161  * offset field.
 162  *
 163  * N.B.: there is no necessary 1-to-1 correspondence between any one
 164  * data transfer segment and the number of CTIOs that will be generated
 165  * satisfy the current data transfer segment. It's not also possible to
 166  * predict how big a transfer can be before it will be 'too big'. Be
 167  * reasonable- a 64KB transfer is 'reasonable'. A 1MB transfer may not
 168  * be. A 32MB transfer is unreasonable. The problem here has to do with
 169  * how CTIOs can be used to map passed data pointers. In systems which
 170  * have page based scatter-gather requirements, each PAGESIZEd chunk will
 171  * consume one data segment descriptor- you get 3 or 4 of them per CTIO.
 172  * The size of the REQUEST QUEUE you drop a CTIO onto is finite (typically
 173  * it's 256, but on some systems it's even smaller, and note you have to
 174  * sure this queue with the initiator side of this driver).
 175  *
 176  * The tags cd_sense and cd_scsi_status are pretty obvious.
 177  *
 178  * The tag cd_error is to communicate between the MD layer and outer software
 179  * the current error conditions.
 180  *
 181  * The tag cd_reserved pads out the structure to 128 bytes. The first
 182  * half of the pad area is reserved to the MD layer, and the second half
 183  * may be used by outer layers, for scratch purposes.
 184  */
 185
 186 #ifndef _LP64
 187 #if     defined(__alpha__) || defined(__sparcv9cpu) || defined(__sparc_v9__) ||\
 188     defined(__ia64__)
 189 #define _LP64
 190 #endif
 191 #endif
 192
 193 #ifndef _TMD_PAD_LEN
 194 #ifdef  _LP64
 195 #define _TMD_PAD_LEN    12
 196 #else
 197 #define _TMD_PAD_LEN    24
 198 #endif
 199 #endif
 200 #ifndef ATIO_CDBLEN
 201 #define ATIO_CDBLEN     26
 202 #endif
 203 #ifndef QLTM_SENSELEN
 204 #define QLTM_SENSELEN   18
 205 #endif
 206 typedef struct tmd_cmd {
 207         void *                  cd_private;     /* layer private data */
 208         void *                  cd_hba;         /* HBA tag */
 209         void *                  cd_data;        /* 'pointer' to data */
 210         u_int64_t               cd_iid;         /* initiator ID */
 211         u_int64_t               cd_tgt;         /* target id */
 212         u_int64_t               cd_lun;         /* logical unit */
 213         u_int8_t                cd_bus;         /* bus */
 214         u_int8_t                cd_tagtype;     /* tag type */
 215         u_int32_t               cd_tagval;      /* tag value */
 216         u_int8_t                cd_cdb[ATIO_CDBLEN];    /* Command */
 217         u_int8_t                cd_lflags;      /* flags lower level sets */
 218         u_int8_t                cd_hflags;      /* flags higher level sets */
 219         u_int32_t               cd_totlen;      /* total data requirement */
 220         u_int32_t               cd_resid;       /* total data residual */
 221         u_int32_t               cd_xfrlen;      /* current data requirement */
 222         int32_t                 cd_error;       /* current error */
 223         u_int8_t                cd_sense[QLTM_SENSELEN];
 224         u_int16_t               cd_scsi_status; /* closing SCSI status */
 225         u_int8_t                cd_reserved[_TMD_PAD_LEN];
 226 } tmd_cmd_t;
 227
 228 #define CDFL_SNSVALID   0x01            /* sense data (from f/w) valid */
 229 #define CDFL_NODISC     0x02            /* disconnects disabled */
 230 #define CDFL_SENTSENSE  0x04            /* last action sent sense data */
 231 #define CDFL_SENTSTATUS 0x08            /* last action sent status */
 232 #define CDFL_ERROR      0x10            /* last action ended in error */
 233 #define CDFL_BUSY       0x40            /* this command is not on a free list */
 234 #define CDFL_PRIVATE_0  0x80            /* private layer flags */
 235
 236 #define CDFH_SNSVALID   0x01            /* sense data valid */
 237 #define CDFH_STSVALID   0x02            /* status valid */
 238 #define CDFH_NODATA     0x00            /* no data transfer expected */
 239 #define CDFH_DATA_IN    0x04            /* target (us) -> initiator (them) */
 240 #define CDFH_DATA_OUT   0x08            /* initiator (them) -> target (us) */
 241 #define CDFH_DATA_MASK  0x0C            /* mask to cover data direction */
 242 #define CDFH_PRIVATE_0  0x80            /* private layer flags */
 243
 244 /*
 245  * Action codes set by the Qlogic MD target driver for
 246  * the external layer to figure out what to do with.
 247  */
 248 typedef enum {
 249         QOUT_HBA_REG=0, /* the argument is a pointer to a hba_register_t */
 250         QOUT_TMD_START, /* the argument is a pointer to a tmd_cmd_t */
 251         QOUT_TMD_DONE,  /* the argument is a pointer to a tmd_cmd_t */
 252         QOUT_TEVENT,    /* the argument is a pointer to a tmd_event_t */
 253         QOUT_TMSG,      /* the argument is a pointer to a tmd_msg_t */
 254         QOUT_HBA_UNREG  /* the argument is a pointer to a hba_register_t */
 255 } tact_e;
 256
 257 /*
 258  * Action codes set by the external layer for the
 259  * MD Qlogic driver to figure out what to do with.
 260  */
 261 typedef enum {
 262         QIN_HBA_REG=6,  /* the argument is a pointer to a hba_register_t */
 263         QIN_ENABLE,     /* the argument is a pointer to a tmd_cmd_t */
 264         QIN_DISABLE,    /* the argument is a pointer to a tmd_cmd_t */
 265         QIN_TMD_CONT,   /* the argument is a pointer to a tmd_cmd_t */
 266         QIN_TMD_FIN,    /* the argument is a pointer to a done tmd_cmd_t */
 267         QIN_HBA_UNREG   /* the argument is a pointer to a hba_register_t */
 268 } qact_e;
 269
 270 /*
 271  * A word about the START/CONT/DONE/FIN dance:
 272  *
 273  *      When the HBA is enabled for receiving commands, one may show up
 274  *      without notice. When that happens, the Qlogic target mode driver
 275  *      gets a tmd_cmd_t, fills it with the info that just arrived, and
 276  *      calls the outer layer with a QOUT_TMD_START code and pointer to
 277  *      the tmd_cmd_t.
 278  *
 279  *      The outer layer decodes the command, fetches data, prepares stuff,
 280  *      whatever, and starts by passing back the pointer with a QIN_TMD_CONT
 281  *      code which causes the Qlogic target mode driver to generate CTIOs to
 282  *      satisfy whatever action needs to be taken. When those CTIOs complete,
 283  *      the Qlogic target driver sends the pointer to the cmd_tmd_t back with
 284  *      a QOUT_TMD_DONE code. This repeats for as long as necessary.
 285  *
 286  *      The outer layer signals it wants to end the command by settings within
 287  *      the tmd_cmd_t itself. When the final QIN_TMD_CONT is reported completed,
 288  *      the outer layer frees the tmd_cmd_t by sending the pointer to it
 289  *      back with a QIN_TMD_FIN code.
 290  *
 291  *      The graph looks like:
 292  *
 293  *      QOUT_TMD_START -> [ QIN_TMD_CONT -> QOUT_TMD_DONE ] * -> QIN_TMD_FIN.
 294  *
 295  */
 296
 297 /*
 298  * A word about ENABLE/DISABLE: the argument is a pointer to an tmd_cmd_t
 299  * with cd_hba, cd_bus, cd_tgt and cd_lun filled out. If an error occurs
 300  * in either enabling or disabling the described lun, cd_lflags is set
 301  * with CDFL_ERROR.
 302  *
 303  * Logical unit zero must be the first enabled and the last disabled.
 304  */
 305
 306 /*
 307  * Target handler functions.
 308  * The MD target handler function (the outer layer calls this)
 309  * should be be prototyped like:
 310  *
 311  *      void target_action(qact_e, void *arg)
 312  *
 313  * The outer layer target handler function (the MD layer calls this)
 314  * should be be prototyped like:
 315  *
 316  *      void system_action(tact_e, void *arg)
 317  */
 318
 319 /*
 320  * This structure is used to register to other software modules the
 321  * binding of an HBA identifier, driver name and instance and the
 322  * lun width capapbilities of this target driver. It's up to each
 323  * platform to figure out how it wants to do this, but a typical
 324  * sequence would be for the MD layer to find some external module's
 325  * entry point and start by sending a QOUT_HBA_REG with info filled
 326  * in, and the external module to call back with a QIN_HBA_REG that
 327  * passes back the corresponding information.
 328  */
 329 typedef struct {
 330         void *  r_identity;
 331         char    r_name[8];
 332         int     r_inst;
 333         int     r_lunwidth;
 334         int     r_buswidth;
 335         void   (*r_action)(int, void *);
 336 } hba_register_t;