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