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