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;