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