xref: /freebsd/sys/cam/cam.h (revision 13de33a5dc2304b13d595d75d48c51793958474f)
1 /*-
2  * Data structures and definitions for the CAM system.
3  *
4  * Copyright (c) 1997 Justin T. Gibbs.
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions, and the following disclaimer,
12  *    without modification, immediately at the beginning of the file.
13  * 2. The name of the author may not be used to endorse or promote products
14  *    derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE 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 THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
20  * 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  * $FreeBSD$
29  */
30 
31 #ifndef _CAM_CAM_H
32 #define _CAM_CAM_H 1
33 
34 #ifdef _KERNEL
35 #include <opt_cam.h>
36 #endif
37 
38 #include <sys/cdefs.h>
39 
40 typedef u_int path_id_t;
41 typedef u_int target_id_t;
42 typedef u_int lun_id_t;
43 typedef union {
44 	u_int64_t	lun64;
45 	u_int8_t	lun[8];
46 } lun64_id_t;
47 
48 #define	CAM_XPT_PATH_ID	((path_id_t)~0)
49 #define	CAM_BUS_WILDCARD ((path_id_t)~0)
50 #define	CAM_TARGET_WILDCARD ((target_id_t)~0)
51 #define	CAM_LUN_WILDCARD ((lun_id_t)~0)
52 
53 #define CAM_EXTLUN_BYTE_SWIZZLE(lun) (	\
54 	((((u_int64_t)lun) & 0xffff000000000000L) >> 48) | \
55 	((((u_int64_t)lun) & 0x0000ffff00000000L) >> 16) | \
56 	((((u_int64_t)lun) & 0x00000000ffff0000L) << 16) | \
57 	((((u_int64_t)lun) & 0x000000000000ffffL) << 48))
58 
59 /*
60  * Maximum length for a CAM CDB.
61  */
62 #define CAM_MAX_CDBLEN 16
63 
64 /*
65  * Definition of a CAM peripheral driver entry.  Peripheral drivers instantiate
66  * one of these for each device they wish to communicate with and pass it into
67  * the xpt layer when they wish to schedule work on that device via the
68  * xpt_schedule API.
69  */
70 struct cam_periph;
71 
72 /*
73  * Priority information for a CAM structure.
74  */
75 typedef enum {
76     CAM_RL_HOST,
77     CAM_RL_BUS,
78     CAM_RL_XPT,
79     CAM_RL_DEV,
80     CAM_RL_NORMAL,
81     CAM_RL_VALUES
82 } cam_rl;
83 /*
84  * The generation number is incremented everytime a new entry is entered into
85  * the queue giving round robin per priority level scheduling.
86  */
87 typedef struct {
88 	u_int32_t priority;
89 #define CAM_PRIORITY_HOST	((CAM_RL_HOST << 8) + 0x80)
90 #define CAM_PRIORITY_BUS	((CAM_RL_BUS << 8) + 0x80)
91 #define CAM_PRIORITY_XPT	((CAM_RL_XPT << 8) + 0x80)
92 #define CAM_PRIORITY_DEV	((CAM_RL_DEV << 8) + 0x80)
93 #define CAM_PRIORITY_OOB	(CAM_RL_DEV << 8)
94 #define CAM_PRIORITY_NORMAL	((CAM_RL_NORMAL << 8) + 0x80)
95 #define CAM_PRIORITY_NONE	(u_int32_t)-1
96 	u_int32_t generation;
97 	int       index;
98 #define CAM_UNQUEUED_INDEX	-1
99 #define CAM_ACTIVE_INDEX	-2
100 #define CAM_DONEQ_INDEX		-3
101 #define CAM_EXTRAQ_INDEX	INT_MAX
102 } cam_pinfo;
103 
104 /*
105  * Macro to compare two generation numbers.  It is used like this:
106  *
107  *	if (GENERATIONCMP(a, >=, b))
108  *		...;
109  *
110  * GERERATIONCMP uses modular arithmetic to guard against wraps
111  * wraps in the generation number.
112  */
113 #define GENERATIONCMP(x, op, y) ((int32_t)((x) - (y)) op 0)
114 
115 /* CAM flags XXX Move to cam_periph.h ??? */
116 typedef enum {
117 	CAM_FLAG_NONE		= 0x00,
118 	CAM_EXPECT_INQ_CHANGE	= 0x01,
119 	CAM_RETRY_SELTO		= 0x02 /* Retry Selection Timeouts */
120 } cam_flags;
121 
122 enum {
123 	SF_RETRY_UA		= 0x01,	/* Retry UNIT ATTENTION conditions. */
124 	SF_NO_PRINT		= 0x02,	/* Never print error status. */
125 	SF_QUIET_IR		= 0x04,	/* Be quiet about Illegal Request reponses */
126 	SF_PRINT_ALWAYS		= 0x08,	/* Always print error status. */
127 	SF_NO_RECOVERY		= 0x10,	/* Don't do active error recovery. */
128 	SF_NO_RETRY		= 0x20	/* Don't do any retries. */
129 };
130 
131 /* CAM  Status field values */
132 typedef enum {
133 	/* CCB request is in progress */
134 	CAM_REQ_INPROG		= 0x00,
135 
136 	/* CCB request completed without error */
137 	CAM_REQ_CMP		= 0x01,
138 
139 	/* CCB request aborted by the host */
140 	CAM_REQ_ABORTED		= 0x02,
141 
142 	/* Unable to abort CCB request */
143 	CAM_UA_ABORT		= 0x03,
144 
145 	/* CCB request completed with an error */
146 	CAM_REQ_CMP_ERR		= 0x04,
147 
148 	/* CAM subsystem is busy */
149 	CAM_BUSY		= 0x05,
150 
151 	/* CCB request was invalid */
152 	CAM_REQ_INVALID		= 0x06,
153 
154 	/* Supplied Path ID is invalid */
155 	CAM_PATH_INVALID	= 0x07,
156 
157 	/* SCSI Device Not Installed/there */
158 	CAM_DEV_NOT_THERE	= 0x08,
159 
160 	/* Unable to terminate I/O CCB request */
161 	CAM_UA_TERMIO		= 0x09,
162 
163 	/* Target Selection Timeout */
164 	CAM_SEL_TIMEOUT		= 0x0a,
165 
166 	/* Command timeout */
167 	CAM_CMD_TIMEOUT		= 0x0b,
168 
169 	/* SCSI error, look at error code in CCB */
170 	CAM_SCSI_STATUS_ERROR	= 0x0c,
171 
172 	/* Message Reject Received */
173 	CAM_MSG_REJECT_REC	= 0x0d,
174 
175 	/* SCSI Bus Reset Sent/Received */
176 	CAM_SCSI_BUS_RESET	= 0x0e,
177 
178 	/* Uncorrectable parity error occurred */
179 	CAM_UNCOR_PARITY	= 0x0f,
180 
181 	/* Autosense: request sense cmd fail */
182 	CAM_AUTOSENSE_FAIL	= 0x10,
183 
184 	/* No HBA Detected error */
185 	CAM_NO_HBA		= 0x11,
186 
187 	/* Data Overrun error */
188 	CAM_DATA_RUN_ERR	= 0x12,
189 
190 	/* Unexpected Bus Free */
191 	CAM_UNEXP_BUSFREE	= 0x13,
192 
193 	/* Target Bus Phase Sequence Failure */
194 	CAM_SEQUENCE_FAIL	= 0x14,
195 
196 	/* CCB length supplied is inadequate */
197 	CAM_CCB_LEN_ERR		= 0x15,
198 
199 	/* Unable to provide requested capability*/
200 	CAM_PROVIDE_FAIL	= 0x16,
201 
202 	/* A SCSI BDR msg was sent to target */
203 	CAM_BDR_SENT		= 0x17,
204 
205 	/* CCB request terminated by the host */
206 	CAM_REQ_TERMIO		= 0x18,
207 
208 	/* Unrecoverable Host Bus Adapter Error */
209 	CAM_UNREC_HBA_ERROR	= 0x19,
210 
211 	/* Request was too large for this host */
212 	CAM_REQ_TOO_BIG		= 0x1a,
213 
214 	/*
215 	 * This request should be requeued to preserve
216 	 * transaction ordering.  This typically occurs
217 	 * when the SIM recognizes an error that should
218 	 * freeze the queue and must place additional
219 	 * requests for the target at the sim level
220 	 * back into the XPT queue.
221 	 */
222 	CAM_REQUEUE_REQ		= 0x1b,
223 
224 	/* ATA error, look at error code in CCB */
225 	CAM_ATA_STATUS_ERROR	= 0x1c,
226 
227 	/* Initiator/Target Nexus lost. */
228 	CAM_SCSI_IT_NEXUS_LOST	= 0x1d,
229 
230 	/* SMP error, look at error code in CCB */
231 	CAM_SMP_STATUS_ERROR	= 0x1e,
232 
233 	/*
234 	 * Command completed without error but  exceeded the soft
235 	 * timeout threshold.
236 	 */
237 	CAM_REQ_SOFTTIMEOUT	= 0x1f,
238 
239 	/*
240 	 * 0x20 - 0x32 are unassigned
241 	 */
242 
243 	/* Initiator Detected Error */
244 	CAM_IDE			= 0x33,
245 
246 	/* Resource Unavailable */
247 	CAM_RESRC_UNAVAIL	= 0x34,
248 
249 	/* Unacknowledged Event by Host */
250 	CAM_UNACKED_EVENT	= 0x35,
251 
252 	/* Message Received in Host Target Mode */
253 	CAM_MESSAGE_RECV	= 0x36,
254 
255 	/* Invalid CDB received in Host Target Mode */
256 	CAM_INVALID_CDB		= 0x37,
257 
258 	/* Lun supplied is invalid */
259 	CAM_LUN_INVALID		= 0x38,
260 
261 	/* Target ID supplied is invalid */
262 	CAM_TID_INVALID		= 0x39,
263 
264 	/* The requested function is not available */
265 	CAM_FUNC_NOTAVAIL	= 0x3a,
266 
267 	/* Nexus is not established */
268 	CAM_NO_NEXUS		= 0x3b,
269 
270 	/* The initiator ID is invalid */
271 	CAM_IID_INVALID		= 0x3c,
272 
273 	/* The SCSI CDB has been received */
274 	CAM_CDB_RECVD		= 0x3d,
275 
276 	/* The LUN is already enabled for target mode */
277 	CAM_LUN_ALRDY_ENA	= 0x3e,
278 
279 	/* SCSI Bus Busy */
280 	CAM_SCSI_BUSY		= 0x3f,
281 
282 
283 	/*
284 	 * Flags
285 	 */
286 
287 	/* The DEV queue is frozen w/this err */
288 	CAM_DEV_QFRZN		= 0x40,
289 
290 	/* Autosense data valid for target */
291 	CAM_AUTOSNS_VALID	= 0x80,
292 
293 	/* SIM ready to take more commands */
294 	CAM_RELEASE_SIMQ	= 0x100,
295 
296 	/* SIM has this command in it's queue */
297 	CAM_SIM_QUEUED		= 0x200,
298 
299 	/* Quality of service data is valid */
300 	CAM_QOS_VALID		= 0x400,
301 
302 	/* Mask bits for just the status # */
303 	CAM_STATUS_MASK = 0x3F,
304 
305 	/*
306 	 * Target Specific Adjunct Status
307 	 */
308 
309 	/* sent sense with status */
310 	CAM_SENT_SENSE		= 0x40000000
311 } cam_status;
312 
313 typedef enum {
314 	CAM_ESF_NONE		= 0x00,
315 	CAM_ESF_COMMAND		= 0x01,
316 	CAM_ESF_CAM_STATUS	= 0x02,
317 	CAM_ESF_PROTO_STATUS	= 0x04,
318 	CAM_ESF_ALL		= 0xff
319 } cam_error_string_flags;
320 
321 typedef enum {
322 	CAM_EPF_NONE		= 0x00,
323 	CAM_EPF_MINIMAL		= 0x01,
324 	CAM_EPF_NORMAL		= 0x02,
325 	CAM_EPF_ALL		= 0x03,
326 	CAM_EPF_LEVEL_MASK	= 0x0f
327 	/* All bits above bit 3 are protocol-specific */
328 } cam_error_proto_flags;
329 
330 typedef enum {
331 	CAM_ESF_PRINT_NONE	= 0x00,
332 	CAM_ESF_PRINT_STATUS	= 0x10,
333 	CAM_ESF_PRINT_SENSE	= 0x20
334 } cam_error_scsi_flags;
335 
336 typedef enum {
337 	CAM_ESMF_PRINT_NONE	= 0x00,
338 	CAM_ESMF_PRINT_STATUS	= 0x10,
339 	CAM_ESMF_PRINT_FULL_CMD	= 0x20,
340 } cam_error_smp_flags;
341 
342 typedef enum {
343 	CAM_EAF_PRINT_NONE	= 0x00,
344 	CAM_EAF_PRINT_STATUS	= 0x10,
345 	CAM_EAF_PRINT_RESULT	= 0x20
346 } cam_error_ata_flags;
347 
348 struct cam_status_entry
349 {
350 	cam_status  status_code;
351 	const char *status_text;
352 };
353 
354 extern const struct cam_status_entry cam_status_table[];
355 extern const int num_cam_status_entries;
356 #ifdef _KERNEL
357 extern int cam_sort_io_queues;
358 #endif
359 union ccb;
360 
361 #ifdef SYSCTL_DECL	/* from sysctl.h */
362 SYSCTL_DECL(_kern_cam);
363 #endif
364 
365 __BEGIN_DECLS
366 typedef int (cam_quirkmatch_t)(caddr_t, caddr_t);
367 
368 caddr_t	cam_quirkmatch(caddr_t target, caddr_t quirk_table, int num_entries,
369 		       int entry_size, cam_quirkmatch_t *comp_func);
370 
371 void	cam_strvis(u_int8_t *dst, const u_int8_t *src, int srclen, int dstlen);
372 
373 int	cam_strmatch(const u_int8_t *str, const u_int8_t *pattern, int str_len);
374 const struct cam_status_entry*
375 	cam_fetch_status_entry(cam_status status);
376 #ifdef _KERNEL
377 char *	cam_error_string(union ccb *ccb, char *str, int str_len,
378 			 cam_error_string_flags flags,
379 			 cam_error_proto_flags proto_flags);
380 void	cam_error_print(union ccb *ccb, cam_error_string_flags flags,
381 			cam_error_proto_flags proto_flags);
382 #else /* _KERNEL */
383 struct cam_device;
384 
385 char *	cam_error_string(struct cam_device *device, union ccb *ccb, char *str,
386 			 int str_len, cam_error_string_flags flags,
387 			 cam_error_proto_flags proto_flags);
388 void	cam_error_print(struct cam_device *device, union ccb *ccb,
389 			cam_error_string_flags flags,
390 			cam_error_proto_flags proto_flags, FILE *ofile);
391 #endif /* _KERNEL */
392 __END_DECLS
393 
394 #ifdef _KERNEL
395 static __inline void cam_init_pinfo(cam_pinfo *pinfo);
396 
397 static __inline void cam_init_pinfo(cam_pinfo *pinfo)
398 {
399 	pinfo->priority = CAM_PRIORITY_NONE;
400 	pinfo->index = CAM_UNQUEUED_INDEX;
401 }
402 #endif
403 
404 #endif /* _CAM_CAM_H */
405