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