Annotation of sys/dev/ic/isp_tpublic.h, Revision 1.1
1.1 ! nbrk 1: /* $OpenBSD: isp_tpublic.h,v 1.9 2007/04/10 17:47:55 miod Exp $ */
! 2: /*
! 3: * Qlogic ISP Host Adapter Public Target Interface Structures && Routines
! 4: *---------------------------------------
! 5: * Copyright (c) 2000, 2001 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; /* initiator 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: * to identify its 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 beginning 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 a 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 capabilities 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;
CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to isp_tpublic.h CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / sys / dev / ic