sys/dev/isp/isp_tpublic.h

   1 /* $FreeBSD$ */
   2 /*-
   3  * Qlogic ISP Host Adapter Public Target Interface Structures && Routines
   4  *
   5  * Copyright (c) 1997-2006 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 immediately at the beginning of the file, without modification,
  13  *    this list of conditions, and the following disclaimer.
  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 /*
  30  * Qlogic ISP Host Adapter Public Target Interface Structures && Routines
  31  */
  32
  33 #ifndef _ISP_TPUBLIC_H
  34 #define _ISP_TPUBLIC_H  1
  35
  36 /*
  37  * Action codes set by the Qlogic MD target driver for
  38  * the external layer to figure out what to do with.
  39  */
  40 typedef enum {
  41         QOUT_HBA_REG=0, /* the argument is a pointer to a hba_register_t */
  42         QOUT_ENABLE,    /* the argument is a pointer to a enadis_t */
  43         QOUT_DISABLE,   /* the argument is a pointer to a enadis_t */
  44         QOUT_TMD_START, /* the argument is a pointer to a tmd_cmd_t */
  45         QOUT_TMD_DONE,  /* the argument is a pointer to a tmd_cmd_t */
  46         QOUT_NOTIFY,    /* the argument is a pointer to a tmd_notify_t */
  47         QOUT_HBA_UNREG  /* the argument is a pointer to a hba_register_t */
  48 } tact_e;
  49
  50 /*
  51  * Action codes set by the external layer for the
  52  * MD Qlogic driver to figure out what to do with.
  53  */
  54 typedef enum {
  55         QIN_HBA_REG=99, /* the argument is a pointer to a hba_register_t */
  56         QIN_ENABLE,     /* the argument is a pointer to a enadis_t */
  57         QIN_DISABLE,    /* the argument is a pointer to a enadis_t */
  58         QIN_TMD_CONT,   /* the argument is a pointer to a tmd_cmd_t */
  59         QIN_TMD_FIN,    /* the argument is a pointer to a tmd_cmd_t */
  60         QIN_NOTIFY_ACK, /* the argument is a pointer to a tmd_notify_t */
  61         QIN_HBA_UNREG,  /* the argument is a pointer to a hba_register_t */
  62 } qact_e;
  63
  64 /*
  65  * This structure is used to register to other software modules the
  66  * binding of an HBA identifier, driver name and instance and the
  67  * lun width capapbilities of this target driver. It's up to each
  68  * platform to figure out how it wants to do this, but a typical
  69  * sequence would be for the MD layer to find some external module's
  70  * entry point and start by sending a QOUT_HBA_REG with info filled
  71  * in, and the external module to call back with a QIN_HBA_REG that
  72  * passes back the corresponding information.
  73  */
  74 #define QR_VERSION      2
  75 typedef struct {
  76         void *  r_identity;
  77         void   (*r_action)(qact_e, void *);
  78         char    r_name[8];
  79         int     r_inst;
  80         int     r_version;
  81         enum { R_FC, R_SCSI } r_type;
  82 } hba_register_t;
  83
  84 /*
  85  * Notify structure
  86  */
  87 typedef enum {
  88     NT_ABORT_TASK=0x1000,
  89     NT_ABORT_TASK_SET,
  90     NT_CLEAR_ACA,
  91     NT_CLEAR_TASK_SET,
  92     NT_LUN_RESET,
  93     NT_TARGET_RESET,
  94     NT_BUS_RESET,
  95     NT_LIP_RESET,
  96     NT_LINK_UP,
  97     NT_LINK_DOWN,
  98     NT_LOGOUT,
  99     NT_HBA_RESET
 100 } tmd_ncode_t;
 101
 102 typedef struct tmd_notify {
 103     void *      nt_hba;         /* HBA tag */
 104     uint64_t    nt_iid;         /* inititator id */
 105     uint64_t    nt_tgt;         /* target id */
 106     uint16_t    nt_lun;         /* logical unit */
 107     uint16_t    nt_padding;     /* padding */
 108     uint32_t    nt_tagval;      /* tag value */
 109     tmd_ncode_t nt_ncode;       /* action */
 110     void *      nt_lreserved;
 111     void *      nt_hreserved;
 112 } tmd_notify_t;
 113 #define LUN_ANY     0xffff
 114 #define INI_ANY     ((uint64_t) -1)
 115 #define TAG_ANY     0
 116 #define MATCH_TMD(tmd, iid, lun, tag)                   \
 117     (                                                   \
 118         (tmd) &&                                        \
 119         (iid == INI_ANY || iid == tmd->cd_iid) &&       \
 120         (lun == LUN_ANY || lun == tmd->cd_lun) &&       \
 121         (tag == TAG_ANY || tag == tmd->cd_tagval)       \
 122     )
 123
 124 /*
 125  * A word about ENABLE/DISABLE: the argument is a pointer to a enadis_t
 126  * with cd_hba, cd_iid, cd_chan, cd_tgt and cd_lun filled out.
 127  *
 128  * If an error occurs in either enabling or disabling the described lun
 129  * cd_error is set with an appropriate non-zero value.
 130  *
 131  * Logical unit zero must be the first enabled and the last disabled.
 132  */
 133 typedef struct {
 134         void *                  en_private;     /* for outer layer usage */
 135         void *                  en_hba;         /* HBA tag */
 136         u_int64_t               en_iid;         /* initiator ID */
 137         u_int64_t               en_tgt;         /* target id */
 138         u_int64_t               en_lun;         /* logical unit */
 139         u_int8_t                en_chan;        /* channel on card */
 140         int32_t                 en_error;
 141 } enadis_t;
 142
 143 /*
 144  * Suggested Software Target Mode Command Handling structure.
 145  *
 146  * A note about terminology:
 147  *
 148  *   MD stands for "Machine Dependent".
 149  *
 150  *    This driver is structured in three layers: Outer MD, core, and inner MD.
 151  *    The latter also is bus dependent (i.e., is cognizant of PCI bus issues
 152  *    as well as platform issues).
 153  *
 154  *
 155  *   "Outer Layer" means "Other Module"
 156  *
 157  *    Some additional module that actually implements SCSI target command
 158  *    policy is the recipient of incoming commands and the source of the
 159  *    disposition for them.
 160  *
 161  * The command structure below is one suggested possible MD command structure,
 162  * but since the handling of thbis is entirely in the MD layer, there is
 163  * no explicit or implicit requirement that it be used.
 164  *
 165  * The cd_private tag should be used by the MD layer to keep a free list
 166  * of these structures. Code outside of this driver can then use this
 167  * to identify it's own unit structures. That is, when not on the MD
 168  * layer's freelist, the MD layer should shove into it the identifier
 169  * that the outer layer has for it- passed in on an initial QIN_HBA_REG
 170  * call (see below).
 171  *
 172  * The cd_hba tag is a tag that uniquely identifies the HBA this target
 173  * mode command is coming from. The outer layer has to pass this back
 174  * unchanged to avoid chaos.
 175  *
 176  * The cd_iid, cd_tgt, cd_lun and cd_bus tags are used to identify the
 177  * id of the initiator who sent us a command, the target claim to be, the
 178  * lun on the target we claim to be, and the bus instance (for multiple
 179  * bus host adapters) that this applies to (consider it an extra Port
 180  * parameter). The iid, tgt and lun values are deliberately chosen to be
 181  * fat so that, for example, World Wide Names can be used instead of
 182  * the units that the Qlogic firmware uses (in the case where the MD
 183  * layer maintains a port database, for example).
 184  *
 185  * The cd_tagtype field specifies what kind of command tag has been
 186  * sent with the command. The cd_tagval is the tag's value (low 16
 187  * bits). It also contains (in the upper 16 bits) any command handle.
 188  *
 189  *
 190  * N.B.: when the MD layer sends this command to outside software
 191  * the outside software likely *MUST* return the same cd_tagval that
 192  * was in place because this value is likely what the Qlogic f/w uses
 193  * to identify a command.
 194  *
 195  * The cd_cdb contains storage for the passed in command descriptor block.
 196  * This is the maximum size we can get out of the Qlogic f/w. There's no
 197  * passed in length because whoever decodes the command to act upon it
 198  * will know what the appropriate length is.
 199  *
 200  * The tag cd_lflags are the flags set by the MD driver when it gets
 201  * command incoming or when it needs to inform any outside entities
 202  * that the last requested action failed.
 203  *
 204  * The tag cd_hflags should be set by any outside software to indicate
 205  * the validity of sense and status fields (defined below) and to indicate
 206  * the direction data is expected to move. It is an error to have both
 207  * CDFH_DATA_IN and CDFH_DATA_OUT set.
 208  *
 209  * If the CDFH_STSVALID flag is set, the command should be completed (after
 210  * sending any data and/or status). If CDFH_SNSVALID is set and the MD layer
 211  * can also handle sending the associated sense data (either back with an
 212  * FCP RESPONSE IU for Fibre Channel or otherwise automatically handling a
 213  * REQUEST SENSE from the initator for this target/lun), the MD layer will
 214  * set the CDFL_SENTSENSE flag on successful transmission of the sense data.
 215  * It is an error for the CDFH_SNSVALID bit to be set and CDFH_STSVALID not
 216  * to be set. It is an error for the CDFH_SNSVALID be set and the associated
 217  * SCSI status (cd_scsi_status) not be set to CHECK CONDITON.
 218  *
 219  * The tag cd_data points to a data segment to either be filled or
 220  * read from depending on the direction of data movement. The tag
 221  * is undefined if no data direction is set. The MD layer and outer
 222  * layers must agree on the meaning of cd_data.
 223  *
 224  * The tag cd_totlen is the total data amount expected to be moved
 225  * over the life of the command. It *may* be set by the MD layer, possibly
 226  * from the datalen field of an FCP CMND IU unit. If it shows up in the outer
 227  * layers set to zero and the CDB indicates data should be moved, the outer
 228  * layer should set it to the amount expected to be moved.
 229  *
 230  * The tag cd_resid should be the total residual of data not transferred.
 231  * The outer layers need to set this at the begining of command processing
 232  * to equal cd_totlen. As data is successfully moved, this value is decreased.
 233  * At the end of a command, any nonzero residual indicates the number of bytes
 234  * requested but not moved. XXXXXXXXXXXXXXXXXXXXXXX TOO VAGUE!!!
 235  *
 236  * The tag cd_xfrlen is the length of the currently active data transfer.
 237  * This allows several interations between any outside software and the
 238  * MD layer to move data.
 239  *
 240  * The reason that total length and total residual have to be tracked
 241  * is that fibre channel FCP DATA IU units have to have a relative
 242  * offset field.
 243  *
 244  * N.B.: there is no necessary 1-to-1 correspondence between any one
 245  * data transfer segment and the number of CTIOs that will be generated
 246  * satisfy the current data transfer segment. It's not also possible to
 247  * predict how big a transfer can be before it will be 'too big'. Be
 248  * reasonable- a 64KB transfer is 'reasonable'. A 1MB transfer may not
 249  * be. A 32MB transfer is unreasonable. The problem here has to do with
 250  * how CTIOs can be used to map passed data pointers. In systems which
 251  * have page based scatter-gather requirements, each PAGESIZEd chunk will
 252  * consume one data segment descriptor- you get 3 or 4 of them per CTIO.
 253  * The size of the REQUEST QUEUE you drop a CTIO onto is finite (typically
 254  * it's 256, but on some systems it's even smaller, and note you have to
 255  * sure this queue with the initiator side of this driver).
 256  *
 257  * The tags cd_sense and cd_scsi_status are pretty obvious.
 258  *
 259  * The tag cd_error is to communicate between the MD layer and outer software
 260  * the current error conditions.
 261  *
 262  * The tag cd_lreserved, cd_hreserved are scratch areas for use for the MD
 263  * and outer layers respectively.
 264  *
 265  */
 266
 267 #ifndef TMD_CDBLEN
 268 #define TMD_CDBLEN      16
 269 #endif
 270 #ifndef TMD_SENSELEN
 271 #define TMD_SENSELEN    24
 272 #endif
 273 #ifndef QCDS
 274 #define QCDS    8
 275 #endif
 276
 277 typedef struct tmd_cmd {
 278         void *                  cd_private;     /* private data pointer */
 279         void *                  cd_hba;         /* HBA tag */
 280         void *                  cd_data;        /* 'pointer' to data */
 281         u_int64_t               cd_iid;         /* initiator ID */
 282         u_int64_t               cd_tgt;         /* target id */
 283         u_int64_t               cd_lun;         /* logical unit */
 284         u_int32_t               cd_tagval;      /* tag value */
 285         u_int32_t               cd_lflags;      /* flags lower level sets */
 286         u_int32_t               cd_hflags;      /* flags higher level sets */
 287         u_int32_t               cd_totlen;      /* total data requirement */
 288         u_int32_t               cd_resid;       /* total data residual */
 289         u_int32_t               cd_xfrlen;      /* current data requirement */
 290         int32_t                 cd_error;       /* current error */
 291         u_int32_t
 292                 cd_scsi_status  : 16,   /* closing SCSI status */
 293                                 : 7,
 294                 cd_chan         : 1,    /* channel on card */
 295                                 : 2,
 296                 cd_tagtype      : 6;    /* tag type */
 297         u_int8_t                cd_senselen;
 298         u_int8_t                cd_cdblen;
 299         u_int8_t                cd_sense[TMD_SENSELEN];
 300         u_int8_t                cd_cdb[TMD_CDBLEN];     /* Command */
 301         union {
 302                 void *          ptrs[QCDS / sizeof (void *)];
 303                 u_int64_t       llongs[QCDS / sizeof (u_int64_t)];
 304                 u_int32_t       longs[QCDS / sizeof (u_int32_t)];
 305                 u_int16_t       shorts[QCDS / sizeof (u_int16_t)];
 306                 u_int8_t        bytes[QCDS];
 307         } cd_lreserved[2], cd_hreserved[2];
 308 } tmd_cmd_t;
 309
 310 #ifndef TMD_SIZE
 311 #define TMD_SIZE        (sizeof (tmd_cmd_t))
 312 #endif
 313
 314 /*
 315  * Note that NODISC (obviously) doesn't apply to non-SPI transport.
 316  *
 317  * Note that knowing the data direction and lengh at the time of receipt of
 318  * a command from the initiator is a feature only of Fibre Channel.
 319  *
 320  * The CDFL_BIDIR is in anticipation of the adoption of some newer
 321  * features required by OSD.
 322  *
 323  * The principle selector for MD layer to know whether data is to
 324  * be transferred in any QOUT_TMD_CONT call is cd_xfrlen- the
 325  * flags CDFH_DATA_IN and CDFH_DATA_OUT define which direction.
 326  */
 327 #define CDFL_SNSVALID   0x01            /* sense data (from f/w) good */
 328 #define CDFL_SENTSTATUS 0x02            /* last action sent status */
 329 #define CDFL_DATA_IN    0x04            /* target (us) -> initiator (them) */
 330 #define CDFL_DATA_OUT   0x08            /* initiator (them) -> target (us) */
 331 #define CDFL_BIDIR      0x0C            /* bidirectional data */
 332 #define CDFL_ERROR      0x10            /* last action ended in error */
 333 #define CDFL_NODISC     0x20            /* disconnects disabled */
 334 #define CDFL_SENTSENSE  0x40            /* last action sent sense data */
 335 #define CDFL_BUSY       0x80            /* this command is not on a free list */
 336 #define CDFL_PRIVATE    0xFF000000      /* private layer flags */
 337
 338 #define CDFH_SNSVALID   0x01            /* sense data (from outer layer) good */
 339 #define CDFH_STSVALID   0x02            /* status valid */
 340 #define CDFH_DATA_IN    0x04            /* target (us) -> initiator (them) */
 341 #define CDFH_DATA_OUT   0x08            /* initiator (them) -> target (us) */
 342 #define CDFH_DATA_MASK  0x0C            /* mask to cover data direction */
 343 #define CDFH_PRIVATE    0xFF000000      /* private layer flags */
 344
 345
 346 /*
 347  * A word about the START/CONT/DONE/FIN dance:
 348  *
 349  *      When the HBA is enabled for receiving commands, one may show up
 350  *      without notice. When that happens, the Qlogic target mode driver
 351  *      gets a tmd_cmd_t, fills it with the info that just arrived, and
 352  *      calls the outer layer with a QOUT_TMD_START code and pointer to
 353  *      the tmd_cmd_t.
 354  *
 355  *      The outer layer decodes the command, fetches data, prepares stuff,
 356  *      whatever, and starts by passing back the pointer with a QIN_TMD_CONT
 357  *      code which causes the Qlogic target mode driver to generate CTIOs to
 358  *      satisfy whatever action needs to be taken. When those CTIOs complete,
 359  *      the Qlogic target driver sends the pointer to the cmd_tmd_t back with
 360  *      a QOUT_TMD_DONE code. This repeats for as long as necessary.
 361  *
 362  *      The outer layer signals it wants to end the command by settings within
 363  *      the tmd_cmd_t itself. When the final QIN_TMD_CONT is reported completed,
 364  *      the outer layer frees the tmd_cmd_t by sending the pointer to it
 365  *      back with a QIN_TMD_FIN code.
 366  *
 367  *      The graph looks like:
 368  *
 369  *      QOUT_TMD_START -> [ QIN_TMD_CONT -> QOUT_TMD_DONE ] * -> QIN_TMD_FIN.
 370  *
 371  */
 372
 373 /*
 374  * Target handler functions.
 375  *
 376  * The MD target handler function (the outer layer calls this)
 377  * should be be prototyped like:
 378  *
 379  *      void target_action(qact_e, void *arg)
 380  *
 381  * The outer layer target handler function (the MD layer calls this)
 382  * should be be prototyped like:
 383  *
 384  *      void system_target_handler(tact_e, void *arg)
 385  */
 386 #endif  /* _ISP_TPUBLIC_H */