xref: /freebsd/sys/cam/cam.h (revision 02e9120893770924227138ba49df1edb3896112a)
1 /*-
2  * Data structures and definitions for the CAM system.
3  *
4  * SPDX-License-Identifier: BSD-2-Clause
5  *
6  * Copyright (c) 1997 Justin T. Gibbs.
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  * 1. Redistributions of source code must retain the above copyright
13  *    notice, this list of conditions, and the following disclaimer,
14  *    without modification, immediately at the beginning of the file.
15  * 2. The name of the author may not be used to endorse or promote products
16  *    derived from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
22  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28  * SUCH DAMAGE.
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 #ifndef _KERNEL
39 #include <stdbool.h>
40 #include <stdio.h>
41 #endif
42 
43 typedef u_int path_id_t;
44 typedef u_int target_id_t;
45 typedef uint64_t lun_id_t;
46 
47 #define	CAM_XPT_PATH_ID	((path_id_t)~0)
48 #define	CAM_BUS_WILDCARD ((path_id_t)~0)
49 #define	CAM_TARGET_WILDCARD ((target_id_t)~0)
50 #define	CAM_LUN_WILDCARD (~(u_int)0)
51 
52 #define CAM_EXTLUN_BYTE_SWIZZLE(lun) (	\
53 	((((uint64_t)lun) & 0xffff000000000000L) >> 48) | \
54 	((((uint64_t)lun) & 0x0000ffff00000000L) >> 16) | \
55 	((((uint64_t)lun) & 0x00000000ffff0000L) << 16) | \
56 	((((uint64_t)lun) & 0x000000000000ffffL) << 48))
57 
58 /*
59  * Maximum length for a CAM CDB.
60  */
61 #define CAM_MAX_CDBLEN 16
62 
63 /*
64  * Definition of a CAM peripheral driver entry.  Peripheral drivers instantiate
65  * one of these for each device they wish to communicate with and pass it into
66  * the xpt layer when they wish to schedule work on that device via the
67  * xpt_schedule API.
68  */
69 struct cam_periph;
70 
71 /*
72  * Priority information for a CAM structure.
73  */
74 typedef enum {
75     CAM_RL_HOST,
76     CAM_RL_BUS,
77     CAM_RL_XPT,
78     CAM_RL_DEV,
79     CAM_RL_NORMAL,
80     CAM_RL_VALUES
81 } cam_rl;
82 /*
83  * The generation number is incremented every time a new entry is entered into
84  * the queue giving round robin per priority level scheduling.
85  */
86 typedef struct {
87 	uint32_t priority;
88 #define CAM_PRIORITY_HOST	((CAM_RL_HOST << 8) + 0x80)
89 #define CAM_PRIORITY_BUS	((CAM_RL_BUS << 8) + 0x80)
90 #define CAM_PRIORITY_XPT	((CAM_RL_XPT << 8) + 0x80)
91 #define CAM_PRIORITY_DEV	((CAM_RL_DEV << 8) + 0x80)
92 #define CAM_PRIORITY_OOB	(CAM_RL_DEV << 8)
93 #define CAM_PRIORITY_NORMAL	((CAM_RL_NORMAL << 8) + 0x80)
94 #define CAM_PRIORITY_NONE	(uint32_t)-1
95 	uint32_t generation;
96 	int       index;
97 #define CAM_UNQUEUED_INDEX	-1
98 #define CAM_ACTIVE_INDEX	-2
99 #define CAM_DONEQ_INDEX		-3
100 #define CAM_ASYNC_INDEX		-4
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 responses */
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 	SF_RETRY_BUSY		= 0x40	/* Retry BUSY status. */
130 };
131 
132 /* CAM  Status field values */
133 typedef enum {
134 	/* CCB request is in progress */
135 	CAM_REQ_INPROG		= 0x00,
136 
137 	/* CCB request completed without error */
138 	CAM_REQ_CMP		= 0x01,
139 
140 	/* CCB request aborted by the host */
141 	CAM_REQ_ABORTED		= 0x02,
142 
143 	/* Unable to abort CCB request */
144 	CAM_UA_ABORT		= 0x03,
145 
146 	/* CCB request completed with an error */
147 	CAM_REQ_CMP_ERR		= 0x04,
148 
149 	/* CAM subsystem is busy */
150 	CAM_BUSY		= 0x05,
151 
152 	/* CCB request was invalid */
153 	CAM_REQ_INVALID		= 0x06,
154 
155 	/* Supplied Path ID is invalid */
156 	CAM_PATH_INVALID	= 0x07,
157 
158 	/* SCSI Device Not Installed/there */
159 	CAM_DEV_NOT_THERE	= 0x08,
160 
161 	/* Unable to terminate I/O CCB request */
162 	CAM_UA_TERMIO		= 0x09,
163 
164 	/* Target Selection Timeout */
165 	CAM_SEL_TIMEOUT		= 0x0a,
166 
167 	/* Command timeout */
168 	CAM_CMD_TIMEOUT		= 0x0b,
169 
170 	/* SCSI error, look at error code in CCB */
171 	CAM_SCSI_STATUS_ERROR	= 0x0c,
172 
173 	/* Message Reject Received */
174 	CAM_MSG_REJECT_REC	= 0x0d,
175 
176 	/* SCSI Bus Reset Sent/Received */
177 	CAM_SCSI_BUS_RESET	= 0x0e,
178 
179 	/* Uncorrectable parity error occurred */
180 	CAM_UNCOR_PARITY	= 0x0f,
181 
182 	/* Autosense: request sense cmd fail */
183 	CAM_AUTOSENSE_FAIL	= 0x10,
184 
185 	/* No HBA Detected error */
186 	CAM_NO_HBA		= 0x11,
187 
188 	/* Data Overrun error */
189 	CAM_DATA_RUN_ERR	= 0x12,
190 
191 	/* Unexpected Bus Free */
192 	CAM_UNEXP_BUSFREE	= 0x13,
193 
194 	/* Target Bus Phase Sequence Failure */
195 	CAM_SEQUENCE_FAIL	= 0x14,
196 
197 	/* CCB length supplied is inadequate */
198 	CAM_CCB_LEN_ERR		= 0x15,
199 
200 	/* Unable to provide requested capability*/
201 	CAM_PROVIDE_FAIL	= 0x16,
202 
203 	/* A SCSI BDR msg was sent to target */
204 	CAM_BDR_SENT		= 0x17,
205 
206 	/* CCB request terminated by the host */
207 	CAM_REQ_TERMIO		= 0x18,
208 
209 	/* Unrecoverable Host Bus Adapter Error */
210 	CAM_UNREC_HBA_ERROR	= 0x19,
211 
212 	/* Request was too large for this host */
213 	CAM_REQ_TOO_BIG		= 0x1a,
214 
215 	/*
216 	 * This request should be requeued to preserve
217 	 * transaction ordering.  This typically occurs
218 	 * when the SIM recognizes an error that should
219 	 * freeze the queue and must place additional
220 	 * requests for the target at the sim level
221 	 * back into the XPT queue.
222 	 */
223 	CAM_REQUEUE_REQ		= 0x1b,
224 
225 	/* ATA error, look at error code in CCB */
226 	CAM_ATA_STATUS_ERROR	= 0x1c,
227 
228 	/* Initiator/Target Nexus lost. */
229 	CAM_SCSI_IT_NEXUS_LOST	= 0x1d,
230 
231 	/* SMP error, look at error code in CCB */
232 	CAM_SMP_STATUS_ERROR	= 0x1e,
233 
234 	/*
235 	 * Command completed without error but  exceeded the soft
236 	 * timeout threshold.
237 	 */
238 	CAM_REQ_SOFTTIMEOUT	= 0x1f,
239 
240 	/*
241 	 * NVME error, look at errro code in CCB
242 	 */
243 	CAM_NVME_STATUS_ERROR	= 0x20,
244 
245 	/*
246 	 * 0x21 - 0x32 are unassigned
247 	 */
248 
249 	/* Initiator Detected Error */
250 	CAM_IDE			= 0x33,
251 
252 	/* Resource Unavailable */
253 	CAM_RESRC_UNAVAIL	= 0x34,
254 
255 	/* Unacknowledged Event by Host */
256 	CAM_UNACKED_EVENT	= 0x35,
257 
258 	/* Message Received in Host Target Mode */
259 	CAM_MESSAGE_RECV	= 0x36,
260 
261 	/* Invalid CDB received in Host Target Mode */
262 	CAM_INVALID_CDB		= 0x37,
263 
264 	/* Lun supplied is invalid */
265 	CAM_LUN_INVALID		= 0x38,
266 
267 	/* Target ID supplied is invalid */
268 	CAM_TID_INVALID		= 0x39,
269 
270 	/* The requested function is not available */
271 	CAM_FUNC_NOTAVAIL	= 0x3a,
272 
273 	/* Nexus is not established */
274 	CAM_NO_NEXUS		= 0x3b,
275 
276 	/* The initiator ID is invalid */
277 	CAM_IID_INVALID		= 0x3c,
278 
279 	/* The SCSI CDB has been received */
280 	CAM_CDB_RECVD		= 0x3d,
281 
282 	/* The LUN is already enabled for target mode */
283 	CAM_LUN_ALRDY_ENA	= 0x3e,
284 
285 	/* SCSI Bus Busy */
286 	CAM_SCSI_BUSY		= 0x3f,
287 
288 	/*
289 	 * Flags
290 	 */
291 
292 	/* The DEV queue is frozen w/this err */
293 	CAM_DEV_QFRZN		= 0x40,
294 
295 	/* Autosense data valid for target */
296 	CAM_AUTOSNS_VALID	= 0x80,
297 
298 	/* SIM ready to take more commands */
299 	CAM_RELEASE_SIMQ	= 0x100,
300 
301 	/* SIM has this command in its queue */
302 	CAM_SIM_QUEUED		= 0x200,
303 
304 	/* Quality of service data is valid */
305 	CAM_QOS_VALID		= 0x400,
306 
307 	/* Mask bits for just the status # */
308 	CAM_STATUS_MASK = 0x3F,
309 
310 	/*
311 	 * Target Specific Adjunct Status
312 	 */
313 
314 	/* sent sense with status */
315 	CAM_SENT_SENSE		= 0x40000000
316 } cam_status;
317 
318 typedef enum {
319 	CAM_ESF_NONE		= 0x00,
320 	CAM_ESF_COMMAND		= 0x01,
321 	CAM_ESF_CAM_STATUS	= 0x02,
322 	CAM_ESF_PROTO_STATUS	= 0x04,
323 	CAM_ESF_ALL		= 0xff
324 } cam_error_string_flags;
325 
326 typedef enum {
327 	CAM_EPF_NONE		= 0x00,
328 	CAM_EPF_MINIMAL		= 0x01,
329 	CAM_EPF_NORMAL		= 0x02,
330 	CAM_EPF_ALL		= 0x03,
331 	CAM_EPF_LEVEL_MASK	= 0x0f
332 	/* All bits above bit 3 are protocol-specific */
333 } cam_error_proto_flags;
334 
335 typedef enum {
336 	CAM_ESF_PRINT_NONE	= 0x00,
337 	CAM_ESF_PRINT_STATUS	= 0x10,
338 	CAM_ESF_PRINT_SENSE	= 0x20
339 } cam_error_scsi_flags;
340 
341 typedef enum {
342 	CAM_ESMF_PRINT_NONE	= 0x00,
343 	CAM_ESMF_PRINT_STATUS	= 0x10,
344 	CAM_ESMF_PRINT_FULL_CMD	= 0x20,
345 } cam_error_smp_flags;
346 
347 typedef enum {
348 	CAM_EAF_PRINT_NONE	= 0x00,
349 	CAM_EAF_PRINT_STATUS	= 0x10,
350 	CAM_EAF_PRINT_RESULT	= 0x20
351 } cam_error_ata_flags;
352 
353 typedef enum {
354 	CAM_STRVIS_FLAG_NONE		= 0x00,
355 	CAM_STRVIS_FLAG_NONASCII_MASK	= 0x03,
356 	CAM_STRVIS_FLAG_NONASCII_TRIM	= 0x00,
357 	CAM_STRVIS_FLAG_NONASCII_RAW	= 0x01,
358 	CAM_STRVIS_FLAG_NONASCII_SPC	= 0x02,
359 	CAM_STRVIS_FLAG_NONASCII_ESC	= 0x03
360 } cam_strvis_flags;
361 
362 struct cam_status_entry
363 {
364 	cam_status  status_code;
365 	const char *status_text;
366 };
367 
368 extern const struct cam_status_entry cam_status_table[];
369 extern const int num_cam_status_entries;
370 #ifdef _KERNEL
371 extern int cam_sort_io_queues;
372 #endif
373 union ccb;
374 struct sbuf;
375 
376 #ifdef SYSCTL_DECL	/* from sysctl.h */
377 SYSCTL_DECL(_kern_cam);
378 #endif
379 
380 __BEGIN_DECLS
381 typedef int (cam_quirkmatch_t)(caddr_t, caddr_t);
382 
383 caddr_t	cam_quirkmatch(caddr_t target, caddr_t quirk_table, int num_entries,
384 		       int entry_size, cam_quirkmatch_t *comp_func);
385 
386 void	cam_strvis(uint8_t *dst, const uint8_t *src, int srclen, int dstlen);
387 void	cam_strvis_flag(uint8_t *dst, const uint8_t *src, int srclen,
388 			int dstlen, uint32_t flags);
389 void	cam_strvis_sbuf(struct sbuf *sb, const uint8_t *src, int srclen,
390 			uint32_t flags);
391 
392 int	cam_strmatch(const uint8_t *str, const uint8_t *pattern, int str_len);
393 const struct cam_status_entry*
394 	cam_fetch_status_entry(cam_status status);
395 #ifdef _KERNEL
396 char *	cam_error_string(union ccb *ccb, char *str, int str_len,
397 			 cam_error_string_flags flags,
398 			 cam_error_proto_flags proto_flags);
399 void	cam_error_print(union ccb *ccb, cam_error_string_flags flags,
400 			cam_error_proto_flags proto_flags);
401 #else /* _KERNEL */
402 struct cam_device;
403 
404 char *	cam_error_string(struct cam_device *device, union ccb *ccb, char *str,
405 			 int str_len, cam_error_string_flags flags,
406 			 cam_error_proto_flags proto_flags);
407 void	cam_error_print(struct cam_device *device, union ccb *ccb,
408 			cam_error_string_flags flags,
409 			cam_error_proto_flags proto_flags, FILE *ofile);
410 #endif /* _KERNEL */
411 __END_DECLS
412 
413 #ifdef _KERNEL
414 static __inline void cam_init_pinfo(cam_pinfo *pinfo)
415 {
416 	pinfo->priority = CAM_PRIORITY_NONE;
417 	pinfo->index = CAM_UNQUEUED_INDEX;
418 }
419 #endif
420 
421 #endif /* _CAM_CAM_H */
422