1 /* $NetBSD: isp_tpublic.h,v 1.16 2008/03/11 05:33:30 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 /* 49 * Action codes set by the Inner Layer for the outer layer to figure out what to do with. 50 */ 51 typedef enum { 52 QOUT_HBA_REG=0, /* the argument is a pointer to a hba_register_t */ 53 QOUT_ENABLE, /* the argument is a pointer to a enadis_t */ 54 QOUT_DISABLE, /* the argument is a pointer to a enadis_t */ 55 QOUT_TMD_START, /* the argument is a pointer to a tmd_cmd_t */ 56 QOUT_TMD_DONE, /* the argument is a pointer to a tmd_xact_t */ 57 QOUT_NOTIFY, /* the argument is a pointer to a tmd_notify_t */ 58 QOUT_HBA_UNREG /* the argument is a pointer to a hba_register_t */ 59 } tact_e; 60 61 /* 62 * Action codes set by the outer layer for the 63 * inner layer to figure out what to do with. 64 */ 65 typedef enum { 66 QIN_HBA_REG=99, /* the argument is a pointer to a hba_register_t */ 67 QIN_GETINFO, /* the argument is a pointer to a info_t */ 68 QIN_SETINFO, /* the argument is a pointer to a info_t */ 69 QIN_GETDLIST, /* the argument is a pointer to a fc_dlist_t */ 70 QIN_ENABLE, /* the argument is a pointer to a enadis_t */ 71 QIN_DISABLE, /* the argument is a pointer to a enadis_t */ 72 QIN_TMD_CONT, /* the argument is a pointer to a tmd_xact_t */ 73 QIN_TMD_FIN, /* the argument is a pointer to a tmd_cmd_t */ 74 QIN_NOTIFY_ACK, /* the argument is a pointer to a tmd_notify_t */ 75 QIN_HBA_UNREG, /* the argument is a pointer to a hba_register_t */ 76 } qact_e; 77 78 /* 79 * This structure is used to register to the outer layer the 80 * binding of an HBA identifier, driver name and instance and the 81 * lun width capapbilities of this inner layer. It's up to each 82 * platform to figure out how it wants to actually implement this. 83 * A typical sequence would be for the MD layer to find some external 84 * module's entry point and start by sending a QOUT_HBA_REG with info 85 * filled in, and the external module to call back with a QIN_HBA_REG 86 * that passes back the corresponding information. 87 * 88 * The r_version tag defines the version of this API. 89 */ 90 #define QR_VERSION 19 91 typedef struct { 92 /* NB: structure tags from here to r_version must never change */ 93 void * r_identity; 94 void (*r_action)(qact_e, void *); 95 char r_name[8]; 96 int r_inst; 97 int r_version; 98 uint32_t r_locator; 99 uint32_t r_nchannels; 100 enum { R_FC, R_SPI } r_type; 101 void * r_private; 102 } hba_register_t; 103 104 /* 105 * An information structure that is used to get or set per-channel transport layer parameters. 106 */ 107 typedef struct { 108 void * i_identity; 109 enum { I_FC, I_SPI } i_type; 110 int i_channel; 111 int i_error; 112 union { 113 struct { 114 uint64_t wwnn_nvram; 115 uint64_t wwpn_nvram; 116 uint64_t wwnn; 117 uint64_t wwpn; 118 } fc; 119 struct { 120 int iid; 121 } spi; 122 } i_id; 123 } info_t; 124 125 /* 126 * An information structure to return a list of logged in WWPNs. FC specific. 127 */ 128 typedef struct { 129 void * d_identity; 130 int d_channel; 131 int d_error; 132 int d_count; 133 uint64_t * d_wwpns; 134 } fc_dlist_t; 135 136 /* 137 * Notify structure- these are for asynchronous events that need to be sent 138 * as notifications to the outer layer. It should be pretty self-explanatory. 139 */ 140 typedef enum { 141 NT_UNKNOWN=0x999, 142 NT_ABORT_TASK=0x1000, 143 NT_ABORT_TASK_SET, 144 NT_CLEAR_ACA, 145 NT_CLEAR_TASK_SET, 146 NT_LUN_RESET, 147 NT_TARGET_RESET, 148 NT_BUS_RESET, 149 NT_LIP_RESET, 150 NT_LINK_UP, 151 NT_LINK_DOWN, 152 NT_LOGOUT, 153 NT_HBA_RESET 154 } tmd_ncode_t; 155 156 typedef struct tmd_notify { 157 void * nt_hba; /* HBA tag */ 158 uint64_t nt_iid; /* inititator id */ 159 uint64_t nt_tgt; /* target id */ 160 uint16_t nt_lun; /* logical unit */ 161 uint16_t : 15, 162 nt_need_ack : 1; /* this notify needs an ACK */ 163 uint64_t nt_tagval; /* tag value */ 164 uint32_t nt_channel; /* channel id */ 165 tmd_ncode_t nt_ncode; /* action */ 166 void * nt_lreserved; 167 void * nt_hreserved; 168 } tmd_notify_t; 169 #define LUN_ANY 0xffff 170 #define TGT_ANY ((uint64_t) -1) 171 #ifdef INI_ANY 172 #define INI_ANY ((uint64_t) -1) 173 #endif 174 #ifndef INI_NONE 175 #define INI_NONE ((uint64_t) 0) 176 #endif 177 #define TAG_ANY ((uint64_t) 0) 178 #define MATCH_TMD(tmd, iid, lun, tag) \ 179 ( \ 180 (tmd) && \ 181 (iid == INI_ANY || iid == tmd->cd_iid) && \ 182 (lun == LUN_ANY || lun == tmd->cd_lun) && \ 183 (tag == TAG_ANY || tag == tmd->cd_tagval) \ 184 ) 185 186 /* 187 * Lun ENABLE/DISABLE 188 * 189 * A word about ENABLE/DISABLE: the argument is a pointer to a enadis_t 190 * with en_hba, en_chan and en_lun filled out. We used to have an iid 191 * and target pair, but this just gets silly so we made initiator id 192 * and target id something you set, once, elsewhere. 193 * 194 * If an error occurs in either enabling or disabling the described lun 195 * en_error is set with an appropriate non-zero value. 196 */ 197 typedef struct { 198 void * en_private; /* for outer layer usage */ 199 void * en_hba; /* HBA tag */ 200 uint16_t en_lun; /* logical unit */ 201 uint16_t en_chan; /* channel on card */ 202 int en_error; 203 } enadis_t; 204 205 206 207 /* 208 * Data Transaction 209 * 210 * A tmd_xact_t is a structure used to describe a transaction within 211 * an overall command. It used to be part of the overall command, 212 * but it became desirable to allow for multiple simultaneous 213 * transfers for a command to happen. Generally these structures 214 * define data to be moved (along with the relative offset within 215 * the overall command) with the last structure containing status 216 * and sense (if needed) as well. 217 * 218 * The td_cmd tag points back to the owning command. 219 * 220 * The td_data tag points to the (platform specific) data descriptor. 221 * 222 * The td_lprivate is for use by the Inner Layer for private usage. 223 * 224 * The td_xfrlen says whether this transaction is moving data- if nonzero. 225 * 226 * The td_offset states what the relative offset within the comamnd the 227 * data transfer will start at. It is undefined if td_xfrlen is zero. 228 * 229 * The td_error flag will note any errors that occurred during an attempt 230 * to start this transaction. The inner layer is responsible for setting 231 * this. 232 * 233 * The td_hflags tag is set by the outer layer to indicate how the inner 234 * layer is supposed to treat this transaction. 235 * 236 * The td_lflags tag is set by the inner layer to indicate whether this 237 * transaction sent status and/or sense. Note that (much as it hurts), 238 * this API allows the inner layer to *fail* to send sense even if asked 239 * to- that is, AUTOSENSE is not a requirement of this API and the outer 240 * layer has to be prepared for this (unlikely) eventuality. 241 */ 242 243 typedef struct tmd_cmd tmd_cmd_t; 244 typedef struct tmd_xact { 245 tmd_cmd_t * td_cmd; /* cross-ref to tmd_cmd_t */ 246 void * td_data; /* data descriptor */ 247 void * td_lprivate; /* private for lower layer */ 248 uint32_t td_xfrlen; /* size of this data load */ 249 uint32_t td_offset; /* offset for this data load */ 250 int td_error; /* error with this transfer */ 251 uint8_t td_hflags; /* flags set by caller */ 252 uint8_t td_lflags; /* flags set by callee */ 253 } tmd_xact_t; 254 255 #define TDFH_STSVALID 0x01 /* status is valid - include it */ 256 #define TDFH_SNSVALID 0x02 /* sense data (from outer layer) good - include it */ 257 #define TDFH_DATA_IN 0x04 /* target (us) -> initiator (them) */ 258 #define TDFH_DATA_OUT 0x08 /* initiator (them) -> target (us) */ 259 #define TDFH_DATA_MASK 0x0C /* mask to cover data direction */ 260 #define TDFH_PRIVATE 0xF0 /* private outer layer usage */ 261 262 #define TDFL_SENTSTATUS 0x01 /* this transaction sent status */ 263 #define TDFL_SENTSENSE 0x02 /* this transaction sent sense data */ 264 #define TDFL_ERROR 0x04 /* this transaction had an error */ 265 #define TDFL_PRIVATE 0xF0 /* private inner layer usage */ 266 267 /* 268 * The command structure below the SCSI Command structure that is 269 * is the whole point of this API. After a LUN is (or LUNS are) 270 * enabled, initiators who send commands addressed to the port, 271 * channel and lun that have been enabled cause an interrupt which 272 * causes the chip to receive the command and present it to the 273 * inner layer. The inner layer allocates one of this command 274 * structures and copies relevant information to it and sends it 275 * to the outer layer with the action QOUT_TMD_START. 276 * 277 * The outer layer is then responsible for command decode and is responsible 278 * for sending any transactions back (via a QIN_TMD_CONT) to the inner layer 279 * that (optionally) moves data and then sends closing status. 280 * 281 * The outer layer, when informed of the status of the final transaction 282 * then releases this structure by sending it back to the inner layer 283 * with the action QOUT_TMD_FIN. 284 * 285 * The structure tag meanings are as described below. 286 * 287 * The cd_hba tag is a tag that uniquely identifies the HBA this target 288 * mode command is coming from. The outer layer has to pass this back 289 * unchanged to avoid chaos. It is identical to the r_identity tag used 290 * by the inner layer to register with the outer layer. 291 * 292 * The cd_iid, cd_channel, cd_tgt and cd_lun tags are used to identify the 293 * the initiator who sent us a command, the channel on the this particular 294 * hardware port we arrived on (for multiple channel devices), the target we 295 * claim to be, and the lun on that target. 296 * 297 * The cd_tagval field is a tag that uniquely describes this tag. It may 298 * or may not have any correspondence to an underying hardware tag. The 299 * outer layer must pass this back unchanged or chaos will result. 300 * 301 * The tag cd_totlen is the total data amount expected to be moved 302 * for this command. This will be set to non-zero for transports 303 * that know this value from the transport level (e.g., Fibre Channel). 304 * If it shows up in the outer layers set to zero, the total data length 305 * must be inferred from the CDB. 306 * 307 * The tag cd_moved is the total amount of data moved so far. It is the 308 * responsibilty of the inner layer to set this for every transaction and 309 * to keep track of it so that transport level residuals may be correctly 310 * set. 311 * 312 * The cd_cdb contains storage for the passed in SCSI command. 313 * 314 * The cd_tagtype field specifies what kind of command tag type, if 315 * any, has been sent with this command. 316 * 317 * The tag cd_flags has some junk flags set but mostly has flags reserved for outer layer use. 318 * 319 * The tags cd_sense and cd_scsi_status are self-explanatory. 320 * 321 * The cd_xact tag is the first or only transaction structure related to this command. 322 * 323 * The tag cd_lreserved, cd_hreserved are scratch areas for use for the outer and inner layers respectively. 324 * 325 */ 326 327 #ifndef TMD_CDBLEN 328 #define TMD_CDBLEN 16 329 #endif 330 #ifndef TMD_SENSELEN 331 #define TMD_SENSELEN 18 332 #endif 333 #ifndef QCDS 334 #define QCDS (sizeof (uint64_t)) 335 #endif 336 #ifndef TMD_PRIV_LO 337 #define TMD_PRIV_LO 4 338 #endif 339 #ifndef TMD_PRIV_HI 340 #define TMD_PRIV_HI 4 341 #endif 342 343 struct tmd_cmd { 344 void * cd_hba; /* HBA tag */ 345 uint64_t cd_iid; /* initiator ID */ 346 uint64_t cd_tgt; /* target id */ 347 uint64_t cd_tagval; /* tag value */ 348 uint8_t cd_lun[8]; /* logical unit */ 349 uint32_t cd_totlen; /* total data load */ 350 uint32_t cd_moved; /* total data moved so far */ 351 uint16_t cd_channel; /* channel index */ 352 uint16_t cd_flags; /* flags */ 353 uint16_t cd_req_cnt; /* how many tmd_xact_t's are active */ 354 uint8_t cd_cdb[TMD_CDBLEN]; 355 uint8_t cd_tagtype; /* tag type */ 356 uint8_t cd_scsi_status; 357 uint8_t cd_sense[TMD_SENSELEN]; 358 tmd_xact_t cd_xact; /* first or only transaction */ 359 union { 360 void * ptrs[QCDS / sizeof (void *)]; /* (assume) one pointer */ 361 uint64_t llongs[QCDS / sizeof (uint64_t)]; /* one long long */ 362 uint32_t longs[QCDS / sizeof (uint32_t)]; /* two longs */ 363 uint16_t shorts[QCDS / sizeof (uint16_t)]; /* four shorts */ 364 uint8_t bytes[QCDS]; /* eight bytes */ 365 } cd_lreserved[TMD_PRIV_LO], cd_hreserved[TMD_PRIV_HI]; 366 }; 367 368 #define CDF_NODISC 0x0001 /* disconnects disabled */ 369 #define CDF_DATA_IN 0x0002 /* target (us) -> initiator (them) */ 370 #define CDF_DATA_OUT 0x0004 /* initiator (them) -> target (us) */ 371 #define CDF_BIDIR 0x0006 /* bidirectional data */ 372 #define CDF_SNSVALID 0x0008 /* sense is set on incoming command */ 373 #define CDF_PRIVATE 0xff00 /* available for private use in outer layer */ 374 375 /* defined tags */ 376 #define CD_UNTAGGED 0 377 #define CD_SIMPLE_TAG 1 378 #define CD_ORDERED_TAG 2 379 #define CD_HEAD_TAG 3 380 #define CD_ACA_TAG 4 381 382 #ifndef TMD_SIZE 383 #define TMD_SIZE (sizeof (tmd_cmd_t)) 384 #endif 385 386 #define L0LUN_TO_FLATLUN(lptr) ((((lptr)[0] & 0x3f) << 8) | ((lptr)[1])) 387 #define FLATLUN_TO_L0LUN(lptr, lun) \ 388 (lptr)[1] = lun & 0xff; \ 389 if (sizeof (lun) == 1) { \ 390 (lptr)[0] = 0; \ 391 } else { \ 392 uint16_t nl = lun; \ 393 if (nl == LUN_ANY) { \ 394 (lptr)[0] = (nl >> 8) & 0xff; \ 395 } else if (nl < 256) { \ 396 (lptr)[0] = 0; \ 397 } else { \ 398 (lptr)[0] = 0x40 | ((nl >> 8) & 0x3f); \ 399 } \ 400 } \ 401 memset(&(lptr)[2], 0, 6) 402 403 /* 404 * Inner Layer Handler Function. 405 * 406 * The inner layer target handler function (the outer layer calls this) 407 * should be be prototyped like so: 408 * 409 * void target_action(qact_e, void *arg) 410 * 411 * The outer layer target handler function (the inner layer calls this) 412 * should be be prototyped like: 413 * 414 * void scsi_target_handler(tact_e, void *arg) 415 */ 416 #endif /* _ISP_TPUBLIC_H */ 417 /* 418 * vim:ts=4:sw=4:expandtab 419 */ 420