1 /* $NetBSD: isp_tpublic.h,v 1.19 2010/01/03 02:47:09 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 */ 376