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  * 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 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 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    10
  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 TGT_ANY     ((uint64_t) -1)
 115 #define INI_ANY     ((uint64_t) -1)
 116 #define TAG_ANY     0
 117 #define MATCH_TMD(tmd, iid, lun, tag)                   \
 118     (                                                   \
 119         (tmd) &&                                        \
 120         (iid == INI_ANY || iid == tmd->cd_iid) &&       \
 121         (lun == LUN_ANY || lun == tmd->cd_lun) &&       \
 122         (tag == TAG_ANY || tag == tmd->cd_tagval)       \
 123     )
 124
 125 /*
 126  * A word about ENABLE/DISABLE: the argument is a pointer to a enadis_t
 127  * with en_hba, en_iid, en_chan, en_tgt and en_lun filled out.
 128  *
 129  * If an error occurs in either enabling or disabling the described lun
 130  * cd_error is set with an appropriate non-zero value.
 131  */
 132 typedef struct {
 133     void *          en_private;     /* for outer layer usage */
 134     void *          en_hba;         /* HBA tag */
 135     uint64_t        en_iid;         /* initiator ID */
 136     uint64_t        en_tgt;         /* target id */
 137     uint16_t        en_lun;         /* logical unit */
 138     uint16_t        en_chan;        /* channel on card */
 139     int             en_error;
 140 } enadis_t;
 141
 142 /*
 143  * Suggested Software Target Mode Command Handling structure.
 144  *
 145  * A note about terminology:
 146  *
 147  *   MD stands for "Machine Dependent".
 148  *
 149  *    This driver is structured in three layers: Outer MD, core, and inner MD.
 150  *    The latter also is bus dependent (i.e., is cognizant of PCI bus issues
 151  *    as well as platform issues).
 152  *
 153  *
 154  *   "Outer Layer" means "Other Module"
 155  *
 156  *    Some additional module that actually implements SCSI target command
 157  *    policy is the recipient of incoming commands and the source of the
 158  *    disposition for them.
 159  *
 160  * The command structure below is one suggested possible MD command structure,
 161  * but since the handling of thbis is entirely in the MD layer, there is
 162  * no explicit or implicit requirement that it be used.
 163  *
 164  * The cd_private tag should be used by the MD layer to keep a free list
 165  * of these structures. Code outside of this driver can then use this
 166  * to identify it's own unit structures. That is, when not on the MD
 167  * layer's freelist, the MD layer should shove into it the identifier
 168  * that the outer layer has for it- passed in on an initial QIN_HBA_REG
 169  * call (see below).
 170  *
 171  * The cd_hba tag is a tag that uniquely identifies the HBA this target
 172  * mode command is coming from. The outer layer has to pass this back
 173  * unchanged to avoid chaos.
 174  *
 175  * The cd_iid, cd_tgt, cd_lun and cd_port tags are used to identify the
 176  * id of the initiator who sent us a command, the target claim to be, the
 177  * lun on the target we claim to be, and the port instance (for multiple
 178  * port host adapters) that this applies to (consider it an extra port
 179  * parameter). The iid, tgt and lun values are deliberately chosen to be
 180  * fat so that, for example, World Wide Names can be used instead of
 181  * the units that the firmware uses (in the case where the MD
 182  * layer maintains a port database, for example).
 183  *
 184  * The cd_tagtype field specifies what kind of command tag type, if
 185  * any, has been sent with the command. Note that the Outer Layer
 186  * still needs to pass the tag handle through unchanged even
 187  * if the tag type is CD_UNTAGGED.
 188  *
 189  * The cd_cdb contains storage for the passed in command descriptor block.
 190  * There is no need to define length as the callee should be able to
 191  * figure this out.
 192  *
 193  * The tag cd_lflags are the flags set by the MD driver when it gets
 194  * command incoming or when it needs to inform any outside entities
 195  * that the last requested action failed.
 196  *
 197  * The tag cd_hflags should be set by any outside software to indicate
 198  * the validity of sense and status fields (defined below) and to indicate
 199  * the direction data is expected to move. It is an error to have both
 200  * CDFH_DATA_IN and CDFH_DATA_OUT set.
 201  *
 202  * If the CDFH_STSVALID flag is set, the command should be completed (after
 203  * sending any data and/or status). If CDFH_SNSVALID is set and the MD layer
 204  * can also handle sending the associated sense data (either back with an
 205  * FCP RESPONSE IU for Fibre Channel or otherwise automatically handling a
 206  * REQUEST SENSE from the initator for this target/lun), the MD layer will
 207  * set the CDFL_SENTSENSE flag on successful transmission of the sense data.
 208  * It is an error for the CDFH_SNSVALID bit to be set and CDFH_STSVALID not
 209  * to be set. It is an error for the CDFH_SNSVALID be set and the associated
 210  * SCSI status (cd_scsi_status) not be set to CHECK CONDITON.
 211  *
 212  * The tag cd_data points to a data segment to either be filled or
 213  * read from depending on the direction of data movement. The tag
 214  * is undefined if no data direction is set. The MD layer and outer
 215  * layers must agree on the meaning of cd_data and it is specifically
 216  * not defined here.
 217  *
 218  * The tag cd_totlen is the total data amount expected to be moved
 219  * over the life of the command. It may be set by the MD layer, possibly
 220  * from the datalen field of an FCP CMND IU unit. If it shows up in the outer
 221  * layers set to zero and the CDB indicates data should be moved, the outer
 222  * layer should set it to the amount expected to be moved.
 223  *
 224  * The tag cd_resid should be the total residual of data not transferred.
 225  * The outer layers need to set this at the begining of command processing
 226  * to equal cd_totlen. As data is successfully moved, this value is decreased.
 227  * At the end of a command, any nonzero residual indicates the number of bytes
 228  * requested by the command but not moved.
 229  *
 230  * The tag cd_xfrlen is the length of the currently active data transfer.
 231  * This allows several interations between any outside software and the
 232  * MD layer to move data.
 233  *
 234  * The reason that total length and total residual have to be tracked
 235  * is to keep track of relative offset.
 236  *
 237  * The tags cd_sense and cd_scsi_status are pretty obvious.
 238  *
 239  * The tag cd_error is to communicate between the MD layer and outer software
 240  * the current error conditions.
 241  *
 242  * The tag cd_lreserved, cd_hreserved are scratch areas for use for the MD
 243  * and outer layers respectively.
 244  *
 245  */
 246
 247 #ifndef    TMD_CDBLEN
 248 #define    TMD_CDBLEN       16
 249 #endif
 250 #ifndef    TMD_SENSELEN
 251 #define    TMD_SENSELEN     18
 252 #endif
 253 #ifndef    QCDS
 254 #define    QCDS             8
 255 #endif
 256
 257 typedef struct tmd_cmd {
 258     void *              cd_private; /* private data pointer */
 259     void *              cd_hba;     /* HBA tag */
 260     void *              cd_data;    /* 'pointer' to data */
 261     uint64_t            cd_iid;     /* initiator ID */
 262     uint64_t            cd_tgt;     /* target id */
 263     uint64_t            cd_lun;     /* logical unit */
 264     uint32_t            cd_tagval;  /* tag value */
 265     uint32_t            cd_lflags;  /* flags lower level sets */
 266     uint32_t            cd_hflags;  /* flags higher level sets */
 267     uint32_t            cd_totlen;  /* total data load */
 268     uint32_t            cd_resid;   /* total data residual */
 269     uint32_t            cd_xfrlen;  /* current data load */
 270     int32_t             cd_error;   /* current error */
 271     uint8_t     cd_tagtype      : 4,
 272                 cd_port         : 4;    /* port number on HBA */
 273     uint8_t             cd_scsi_status;
 274     uint8_t             cd_sense[TMD_SENSELEN];
 275     uint8_t             cd_cdb[TMD_CDBLEN];
 276     union {
 277         void *          ptrs[QCDS / sizeof (void *)];
 278         uint64_t        llongs[QCDS / sizeof (uint64_t)];
 279         uint32_t        longs[QCDS / sizeof (uint32_t)];
 280         uint16_t        shorts[QCDS / sizeof (uint16_t)];
 281         uint8_t         bytes[QCDS];
 282     } cd_lreserved[3], cd_hreserved[3];
 283 } tmd_cmd_t;
 284
 285 /* defined tags */
 286 #define CD_UNTAGGED     0
 287 #define CD_SIMPLE_TAG   1
 288 #define CD_ORDERED_TAG  2
 289 #define CD_HEAD_TAG     3
 290 #define CD_ACA_TAG      4
 291
 292 #ifndef    TMD_SIZE
 293 #define    TMD_SIZE     (sizeof (tmd_cmd_t))
 294 #endif
 295
 296 /*
 297  * Note that NODISC (obviously) doesn't apply to non-SPI transport.
 298  *
 299  * Note that knowing the data direction and lengh at the time of receipt of
 300  * a command from the initiator is a feature only of Fibre Channel.
 301  *
 302  * The CDFL_BIDIR is in anticipation of the adoption of some newer
 303  * features required by OSD.
 304  *
 305  * The principle selector for MD layer to know whether data is to
 306  * be transferred in any QOUT_TMD_CONT call is cd_xfrlen- the
 307  * flags CDFH_DATA_IN and CDFH_DATA_OUT define which direction.
 308  */
 309 #define    CDFL_SNSVALID        0x01            /* sense data (from f/w) good */
 310 #define    CDFL_SENTSTATUS      0x02            /* last action sent status */
 311 #define    CDFL_DATA_IN         0x04            /* target (us) -> initiator (them) */
 312 #define    CDFL_DATA_OUT        0x08            /* initiator (them) -> target (us) */
 313 #define    CDFL_BIDIR           0x0C            /* bidirectional data */
 314 #define    CDFL_ERROR           0x10            /* last action ended in error */
 315 #define    CDFL_NODISC          0x20            /* disconnects disabled */
 316 #define    CDFL_SENTSENSE       0x40            /* last action sent sense data */
 317 #define    CDFL_BUSY            0x80            /* this command is not on a free list */
 318 #define    CDFL_PRIVATE         0xFF000000      /* private layer flags */
 319
 320 #define    CDFH_SNSVALID        0x01            /* sense data (from outer layer) good */
 321 #define    CDFH_STSVALID        0x02            /* status valid */
 322 #define    CDFH_DATA_IN         0x04            /* target (us) -> initiator (them) */
 323 #define    CDFH_DATA_OUT        0x08            /* initiator (them) -> target (us) */
 324 #define    CDFH_DATA_MASK       0x0C            /* mask to cover data direction */
 325 #define    CDFH_PRIVATE         0xFF000000      /* private layer flags */
 326
 327
 328 /*
 329  * A word about the START/CONT/DONE/FIN dance:
 330  *
 331  *    When the HBA is enabled for receiving commands, one may show up
 332  *    without notice. When that happens, the MD target mode driver
 333  *    gets a tmd_cmd_t, fills it with the info that just arrived, and
 334  *    calls the outer layer with a QOUT_TMD_START code and pointer to
 335  *    the tmd_cmd_t.
 336  *
 337  *    The outer layer decodes the command, fetches data, prepares stuff,
 338  *    whatever, and starts by passing back the pointer with a QIN_TMD_CONT
 339  *    code which causes the MD target mode driver to generate CTIOs to
 340  *    satisfy whatever action needs to be taken. When those CTIOs complete,
 341  *    the MD target driver sends the pointer to the cmd_tmd_t back with
 342  *    a QOUT_TMD_DONE code. This repeats for as long as necessary. These
 343  *    may not be done in parallel- they are sequential operations.
 344  *
 345  *    The outer layer signals it wants to end the command by settings within
 346  *    the tmd_cmd_t itself. When the final QIN_TMD_CONT is reported completed,
 347  *    the outer layer frees the tmd_cmd_t by sending the pointer to it
 348  *    back with a QIN_TMD_FIN code.
 349  *
 350  *    The graph looks like:
 351  *
 352  *    QOUT_TMD_START -> [ QIN_TMD_CONT -> QOUT_TMD_DONE ] * -> QIN_TMD_FIN.
 353  *
 354  */
 355
 356 /*
 357  * Target handler functions.
 358  *
 359  * The MD target handler function (the outer layer calls this)
 360  * should be be prototyped like:
 361  *
 362  *    void target_action(qact_e, void *arg)
 363  *
 364  * The outer layer target handler function (the MD layer calls this)
 365  * should be be prototyped like:
 366  *
 367  *    void scsi_target_handler(tact_e, void *arg)
 368  */
 369 #endif    /* _ISP_TPUBLIC_H */
 370 /*
 371  * vim:ts=4:sw=4:expandtab
 372  */