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
43typedef u_int path_id_t;
44typedef u_int target_id_t;
45typedef 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 */
69struct cam_periph;
70
71/*
72 * Priority information for a CAM structure.
73 */
74typedef 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 */
86typedef 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 ??? */
116typedef enum {
117	CAM_FLAG_NONE		= 0x00,
118	CAM_EXPECT_INQ_CHANGE	= 0x01,
119	CAM_RETRY_SELTO		= 0x02 /* Retry Selection Timeouts */
120} cam_flags;
121
122enum {
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 */
133typedef 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
318typedef 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
326typedef 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
335typedef 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
341typedef 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
347typedef 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
353typedef 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
362struct cam_status_entry
363{
364	cam_status  status_code;
365	const char *status_text;
366};
367
368extern const struct cam_status_entry cam_status_table[];
369extern const int num_cam_status_entries;
370#ifdef _KERNEL
371extern int cam_sort_io_queues;
372#endif
373union ccb;
374struct sbuf;
375
376#ifdef SYSCTL_DECL	/* from sysctl.h */
377SYSCTL_DECL(_kern_cam);
378#endif
379
380__BEGIN_DECLS
381typedef int (cam_quirkmatch_t)(caddr_t, caddr_t);
382
383caddr_t	cam_quirkmatch(caddr_t target, caddr_t quirk_table, int num_entries,
384		       int entry_size, cam_quirkmatch_t *comp_func);
385
386void	cam_strvis(uint8_t *dst, const uint8_t *src, int srclen, int dstlen);
387void	cam_strvis_flag(uint8_t *dst, const uint8_t *src, int srclen,
388			int dstlen, uint32_t flags);
389void	cam_strvis_sbuf(struct sbuf *sb, const uint8_t *src, int srclen,
390			uint32_t flags);
391
392int	cam_strmatch(const uint8_t *str, const uint8_t *pattern, int str_len);
393const struct cam_status_entry*
394	cam_fetch_status_entry(cam_status status);
395#ifdef _KERNEL
396char *	cam_error_string(union ccb *ccb, char *str, int str_len,
397			 cam_error_string_flags flags,
398			 cam_error_proto_flags proto_flags);
399void	cam_error_print(union ccb *ccb, cam_error_string_flags flags,
400			cam_error_proto_flags proto_flags);
401#else /* _KERNEL */
402struct cam_device;
403
404char *	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);
407void	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
414static __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