sys/dev/ic/isp_tpublic.h

   1 /* $NetBSD: isp_tpublic.h,v 1.18 2009/06/25 23:44:02 mjacob Exp $ */
   2 /*-
   3  *  Copyright (c) 1997-2008 by Matthew Jacob
   4  *  All rights reserved.
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions
   8  *  are met:
   9  *
  10  *  1. Redistributions of source code must retain the above copyright
  11  *     notice, this list of conditions and the following disclaimer.
  12  *  2. Redistributions in binary form must reproduce the above copyright
  13  *     notice, this list of conditions and the following disclaimer in the
  14  *     documentation and/or other materials provided with the distribution.
  15  *
  16  *  THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  *  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  *  ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  20  *  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  *  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  *  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  *  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  *  SUCH DAMAGE.
  27  */
  28 /*
  29  * Host Adapter Public Target Interface Structures && Routines
  30  */
  31 /*
  32  * A note about terminology:
  33  *
  34  *  "Inner Layer" means this driver (isp and the isp_tpublic API).
  35  *
  36  *    This module includes the both generic and platform specific pieces.
  37  *
  38  *  "Outer Layer" means another (external) module.
  39  *
  40  *    This is an additional module that actually implements SCSI target command
  41  *    decode and is the recipient of incoming commands and the source of the
  42  *    disposition for them.
  43  */
  44
  45 #ifndef    _ISP_TPUBLIC_H
  46 #define    _ISP_TPUBLIC_H    1
  47 /*
  48  * Include general target definitions
  49  */
  50 #include "isp_target.h"
  51
  52 /*
  53  * Action codes set by the Inner Layer for the outer layer to figure out what to do with.
  54  */
  55 typedef enum {
  56     QOUT_HBA_REG=0,     /* the argument is a pointer to a hba_register_t */
  57     QOUT_ENABLE,        /* the argument is a pointer to a enadis_t */
  58     QOUT_DISABLE,       /* the argument is a pointer to a enadis_t */
  59     QOUT_TMD_START,     /* the argument is a pointer to a tmd_cmd_t */
  60     QOUT_TMD_DONE,      /* the argument is a pointer to a tmd_xact_t */
  61     QOUT_NOTIFY,        /* the argument is a pointer to a notify_t */
  62     QOUT_HBA_UNREG      /* the argument is a pointer to a hba_register_t */
  63 } tact_e;
  64
  65 /*
  66  * Action codes set by the outer layer for the
  67  * inner layer to figure out what to do with.
  68  */
  69 typedef enum {
  70     QIN_HBA_REG=99,     /* the argument is a pointer to a hba_register_t */
  71     QIN_GETINFO,        /* the argument is a pointer to a info_t */
  72     QIN_SETINFO,        /* the argument is a pointer to a info_t */
  73     QIN_GETDLIST,       /* the argument is a pointer to a fc_dlist_t */
  74     QIN_ENABLE,         /* the argument is a pointer to a enadis_t */
  75     QIN_DISABLE,        /* the argument is a pointer to a enadis_t */
  76     QIN_TMD_CONT,       /* the argument is a pointer to a tmd_xact_t */
  77     QIN_TMD_FIN,        /* the argument is a pointer to a tmd_cmd_t */
  78     QIN_NOTIFY_ACK,     /* the argument is a pointer to a notify_t */
  79     QIN_HBA_UNREG,      /* the argument is a pointer to a hba_register_t */
  80 } qact_e;
  81
  82 /*
  83  * This structure is used to register to the outer layer the
  84  * binding of an HBA identifier, driver name and instance and the
  85  * lun width capapbilities of this inner layer. It's up to each
  86  * platform to figure out how it wants to actually implement this.
  87  * A typical sequence would be for the MD layer to find some external
  88  * module's entry point and start by sending a QOUT_HBA_REG with info
  89  * filled in, and the external module to call back with a QIN_HBA_REG
  90  * that passes back the corresponding information.
  91  *
  92  * The r_version tag defines the version of this API.
  93  */
  94 #define    QR_VERSION    20
  95 typedef struct {
  96     /* NB: structure tags from here to r_version must never change */
  97     void *                  r_identity;
  98     void                    (*r_action)(qact_e, void *);
  99     char                    r_name[8];
 100     int                     r_inst;
 101     int                     r_version;
 102     uint32_t                r_locator;
 103     uint32_t                r_nchannels;
 104     enum { R_FC, R_SPI }    r_type;
 105     void *                  r_private;
 106 } hba_register_t;
 107
 108 /*
 109  * An information structure that is used to get or set per-channel transport layer parameters.
 110  */
 111 typedef struct {
 112     void *                  i_identity;
 113     enum { I_FC, I_SPI }    i_type;
 114     int                     i_channel;
 115     int                     i_error;
 116     union {
 117         struct {
 118             uint64_t    wwnn_nvram;
 119             uint64_t    wwpn_nvram;
 120             uint64_t    wwnn;
 121             uint64_t    wwpn;
 122         } fc;
 123         struct {
 124             int         iid;
 125         } spi;
 126     }                       i_id;
 127 } info_t;
 128
 129 /*
 130  * An information structure to return a list of logged in WWPNs. FC specific.
 131  */
 132 typedef struct {
 133     void *                  d_identity;
 134     int                     d_channel;
 135     int                     d_error;
 136     int                     d_count;
 137     uint64_t *              d_wwpns;
 138 } fc_dlist_t;
 139
 140 /*
 141  * Lun ENABLE/DISABLE
 142  *
 143  * A word about ENABLE/DISABLE: the argument is a pointer to a enadis_t
 144  * with en_hba, en_chan and en_lun filled out. We used to have an iid
 145  * and target pair, but this just gets silly so we made initiator id
 146  * and target id something you set, once, elsewhere.
 147  *
 148  * If an error occurs in either enabling or disabling the described lun
 149  * en_error is set with an appropriate non-zero value.
 150  */
 151 typedef struct {
 152     void *          en_private;     /* for outer layer usage */
 153     void *          en_hba;         /* HBA tag */
 154     uint16_t        en_lun;         /* logical unit */
 155     uint16_t        en_chan;        /* channel on card */
 156     int             en_error;
 157 } enadis_t;
 158
 159
 160
 161 /*
 162  * Data Transaction
 163  *
 164  * A tmd_xact_t is a structure used to describe a transaction within
 165  * an overall command. It used to be part of the overall command,
 166  * but it became desirable to allow for multiple simultaneous
 167  * transfers for a command to happen. Generally these structures
 168  * define data to be moved (along with the relative offset within
 169  * the overall command) with the last structure containing status
 170  * and sense (if needed) as well.
 171  *
 172  * The td_cmd tag points back to the owning command.
 173  *
 174  * The td_data tag points to the (platform specific) data descriptor.
 175  *
 176  * The td_lprivate is for use by the Inner Layer for private usage.
 177  *
 178  * The td_xfrlen says whether this transaction is moving data- if nonzero.
 179  *
 180  * The td_offset states what the relative offset within the comamnd the
 181  * data transfer will start at. It is undefined if td_xfrlen is zero.
 182  *
 183  * The td_error flag will note any errors that occurred during an attempt
 184  * to start this transaction. The inner layer is responsible for setting
 185  * this.
 186  *
 187  * The td_hflags tag is set by the outer layer to indicate how the inner
 188  * layer is supposed to treat this transaction.
 189  *
 190  * The td_lflags tag is set by the inner layer to indicate whether this
 191  * transaction sent status and/or sense. Note that (much as it hurts),
 192  * this API allows the inner layer to *fail* to send sense even if asked
 193  * to- that is, AUTOSENSE is not a requirement of this API and the outer
 194  * layer has to be prepared for this (unlikely) eventuality.
 195  */
 196
 197 typedef struct tmd_cmd tmd_cmd_t;
 198 typedef struct tmd_xact {
 199     tmd_cmd_t *         td_cmd;                 /* cross-ref to tmd_cmd_t */
 200     void *              td_data;                /* data descriptor */
 201     void *              td_lprivate;            /* private for lower layer */
 202     uint32_t            td_xfrlen;              /* size of this data load */
 203     uint32_t            td_offset;              /* offset for this data load */
 204     int                 td_error;               /* error with this transfer */
 205     uint8_t             td_hflags;              /* flags set by caller */
 206     uint8_t             td_lflags;              /* flags set by callee */
 207 } tmd_xact_t;
 208
 209 #define TDFH_STSVALID   0x01    /* status is valid - include it */
 210 #define TDFH_SNSVALID   0x02    /* sense data (from outer layer) good - include it */
 211 #define TDFH_DATA_IN    0x04    /* target (us) -> initiator (them) */
 212 #define TDFH_DATA_OUT   0x08    /* initiator (them) -> target (us) */
 213 #define TDFH_DATA_MASK  0x0C    /* mask to cover data direction */
 214 #define TDFH_PRIVATE    0xF0    /* private outer layer usage */
 215
 216 #define TDFL_SENTSTATUS 0x01    /* this transaction sent status */
 217 #define TDFL_SENTSENSE  0x02    /* this transaction sent sense data */
 218 #define TDFL_ERROR      0x04    /* this transaction had an error */
 219 #define TDFL_SYNCERROR  0x08    /* ... and didn't even start because of it */
 220 #define TDFL_PRIVATE    0xF0    /* private inner layer usage */
 221
 222 /*
 223  * The command structure below the SCSI Command structure that is
 224  * is the whole point of this API. After a LUN is (or LUNS are)
 225  * enabled, initiators who send commands addressed to the port,
 226  * channel and lun that have been enabled cause an interrupt which
 227  * causes the chip to receive the command and present it to the
 228  * inner layer. The inner layer allocates one of this command
 229  * structures and copies relevant information to it and sends it
 230  * to the outer layer with the action QOUT_TMD_START.
 231  *
 232  * The outer layer is then responsible for command decode and is responsible
 233  * for sending any transactions back (via a QIN_TMD_CONT) to the inner layer
 234  * that (optionally) moves data and then sends closing status.
 235  *
 236  * The outer layer, when informed of the status of the final transaction
 237  * then releases this structure by sending it back to the inner layer
 238  * with the action QOUT_TMD_FIN.
 239  *
 240  * The structure tag meanings are as described below.
 241  *
 242  * The cd_hba tag is a tag that uniquely identifies the HBA this target
 243  * mode command is coming from. The outer layer has to pass this back
 244  * unchanged to avoid chaos. It is identical to the r_identity tag used
 245  * by the inner layer to register with the outer layer.
 246  *
 247  * The cd_iid, cd_channel, cd_tgt and cd_lun tags are used to identify the
 248  * the initiator who sent us a command, the channel on the this particular
 249  * hardware port we arrived on (for multiple channel devices), the target we
 250  * claim to be, and the lun on that target.
 251  *
 252  * The cd_tagval field is a tag that uniquely describes this tag. It may
 253  * or may not have any correspondence to an underying hardware tag. The
 254  * outer layer must pass this back unchanged or chaos will result.
 255  *
 256  * The tag cd_totlen is the total data amount expected to be moved
 257  * for this command. This will be set to non-zero for transports
 258  * that know this value from the transport level (e.g., Fibre Channel).
 259  * If it shows up in the outer layers set to zero, the total data length
 260  * must be inferred from the CDB.
 261  *
 262  * The tag cd_moved is the total amount of data moved so far. It is the
 263  * responsibilty of the inner layer to set this for every transaction and
 264  * to keep track of it so that transport level residuals may be correctly
 265  * set.
 266  *
 267  * The cd_cdb contains storage for the passed in SCSI command.
 268  *
 269  * The cd_tagtype field specifies what kind of command tag type, if
 270  * any, has been sent with this command.
 271  *
 272  * The tag cd_flags has some junk flags set but mostly has flags reserved for outer layer use.
 273  *
 274  * The tags cd_sense and cd_scsi_status are self-explanatory.
 275  *
 276  * The cd_xact tag is the first or only transaction structure related to this command.
 277  *
 278  * The tag cd_lreserved, cd_hreserved are scratch areas for use for the outer and inner layers respectively.
 279  *
 280  */
 281
 282 #ifndef TMD_CDBLEN
 283 #define TMD_CDBLEN       16
 284 #endif
 285 #ifndef TMD_SENSELEN
 286 #define TMD_SENSELEN     18
 287 #endif
 288 #ifndef QCDS
 289 #define QCDS             (sizeof (uint64_t))
 290 #endif
 291 #ifndef TMD_PRIV_LO
 292 #define TMD_PRIV_LO 4
 293 #endif
 294 #ifndef TMD_PRIV_HI
 295 #define TMD_PRIV_HI 4
 296 #endif
 297
 298 struct tmd_cmd {
 299     void *              cd_hba;     /* HBA tag */
 300     uint64_t            cd_iid;     /* initiator ID */
 301     uint64_t            cd_tgt;     /* target id */
 302     uint64_t            cd_tagval;  /* tag value */
 303     uint8_t             cd_lun[8];  /* logical unit */
 304     uint32_t            cd_totlen;  /* total data load */
 305     uint32_t            cd_moved;   /* total data moved so far */
 306     uint16_t            cd_channel; /* channel index */
 307     uint16_t            cd_flags;   /* flags */
 308     uint16_t            cd_req_cnt; /* how many tmd_xact_t's are active */
 309     uint8_t             cd_cdb[TMD_CDBLEN];
 310     uint8_t             cd_tagtype; /* tag type */
 311     uint8_t             cd_scsi_status;
 312     uint8_t             cd_sense[TMD_SENSELEN];
 313     tmd_xact_t          cd_xact;    /* first or only transaction */
 314     union {
 315         void *          ptrs[QCDS / sizeof (void *)];       /* (assume) one pointer */
 316         uint64_t        llongs[QCDS / sizeof (uint64_t)];   /* one long long */
 317         uint32_t        longs[QCDS / sizeof (uint32_t)];    /* two longs */
 318         uint16_t        shorts[QCDS / sizeof (uint16_t)];   /* four shorts */
 319         uint8_t         bytes[QCDS];                        /* eight bytes */
 320     } cd_lreserved[TMD_PRIV_LO], cd_hreserved[TMD_PRIV_HI];
 321 };
 322
 323 #define CDF_NODISC      0x0001  /* disconnects disabled */
 324 #define CDF_DATA_IN     0x0002  /* target (us) -> initiator (them) */
 325 #define CDF_DATA_OUT    0x0004  /* initiator (them) -> target (us) */
 326 #define CDF_BIDIR       0x0006  /* bidirectional data */
 327 #define CDF_SNSVALID    0x0008  /* sense is set on incoming command */
 328 #define CDF_PRIVATE     0xff00  /* available for private use in outer layer */
 329
 330 /* defined tags */
 331 #define CD_UNTAGGED     0
 332 #define CD_SIMPLE_TAG   1
 333 #define CD_ORDERED_TAG  2
 334 #define CD_HEAD_TAG     3
 335 #define CD_ACA_TAG      4
 336
 337 #ifndef    TMD_SIZE
 338 #define    TMD_SIZE     (sizeof (tmd_cmd_t))
 339 #endif
 340
 341 #define L0LUN_TO_FLATLUN(lptr)              ((((lptr)[0] & 0x3f) << 8) | ((lptr)[1]))
 342 #define FLATLUN_TO_L0LUN(lptr, lun)                 \
 343     (lptr)[1] = lun & 0xff;                         \
 344     if (sizeof (lun) == 1) {                        \
 345         (lptr)[0] = 0;                              \
 346     } else {                                        \
 347         uint16_t nl = lun;                          \
 348         if (nl == LUN_ANY) {                        \
 349             (lptr)[0] = (nl >> 8) & 0xff;           \
 350         } else if (nl < 256) {                      \
 351             (lptr)[0] = 0;                          \
 352         } else {                                    \
 353             (lptr)[0] = 0x40 | ((nl >> 8) & 0x3f);  \
 354         }                                           \
 355     }                                               \
 356     memset(&(lptr)[2], 0, 6)
 357
 358 /*
 359  * Inner Layer Handler Function.
 360  *
 361  * The inner layer target handler function (the outer layer calls this)
 362  * should be be prototyped like so:
 363  *
 364  *    void target_action(qact_e, void *arg)
 365  *
 366  * The outer layer target handler function (the inner layer calls this)
 367  * should be be prototyped like:
 368  *
 369  *    void scsi_target_handler(tact_e, void *arg)
 370  */
 371
 372 #endif    /* _ISP_TPUBLIC_H */
 373 /*
 374  * vim:ts=4:sw=4:expandtab
 375  */