xref: /illumos-gate/usr/src/uts/common/sys/scsi/scsi_pkt.h (revision 1cba8b6c)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef	_SYS_SCSI_SCSI_PKT_H
27 #define	_SYS_SCSI_SCSI_PKT_H
28 
29 #include <sys/scsi/scsi_types.h>
30 
31 #ifdef	__cplusplus
32 extern "C" {
33 #endif
34 
35 #ifdef	_KERNEL
36 /*
37  * SCSI packet definition.
38  *
39  *	This structure defines the packet which is allocated by a library
40  *	function and handed to a target driver. The target driver fills
41  *	in some information, and passes it to the library for transport
42  *	to an addressed SCSI device. The host adapter found by
43  *	the library fills in some other information as the command is
44  *	processed. When the command completes (or can be taken no further)
45  *	the function specified in the packet is called with a pointer to
46  *	the packet as it argument. From fields within the packet, the target
47  *	driver can determine the success or failure of the command.
48  */
49 struct scsi_pkt {
50 	opaque_t pkt_ha_private;	/* private data for host adapter */
51 	struct scsi_address pkt_address;	/* destination packet is for */
52 	opaque_t pkt_private;		/* private data for target driver */
53 	void	(*pkt_comp)(struct scsi_pkt *);	/* completion routine */
54 	uint_t	pkt_flags;		/* flags */
55 	int	pkt_time;		/* time allotted to complete command */
56 	uchar_t	*pkt_scbp;		/* pointer to status block */
57 	uchar_t	*pkt_cdbp;		/* pointer to command block */
58 	ssize_t	pkt_resid;		/* data bytes not transferred */
59 	uint_t	pkt_state;		/* state of command */
60 	uint_t	pkt_statistics;		/* statistics */
61 	uchar_t	pkt_reason;		/* reason completion called */
62 
63 	/*
64 	 * The DDI does not allow a driver to allocate it's own scsi_pkt(9S),
65 	 * a driver should not have *any* compiled in dependencies on
66 	 * "sizeof (struct scsi_pkt)". If the driver has such dependencies, it
67 	 * limits SCSA's ability to evolve. The proper way for an HBA to
68 	 * allocate a scsi_pkt is via scsi_hba_pkt_alloc(9F), or the newer
69 	 * tran_setup_pkt(9E) interfaces. Allocation rules have been in place
70 	 * for many years, unfortunately a significant number of drivers
71 	 * are still broken.
72 	 *
73 	 * NB: Until we can trust drivers to follow DDI scsi_pkt(9S) allocation
74 	 * rules, access to all fields below require special consideration.
75 	 * Access to these fields is limited to code paths that 'know' correct
76 	 * scsi_pkt allocation interfaces must have been used. This means that
77 	 * any target driver access to these fields is suspect, since a target
78 	 * knows nothing about how an HBA drivers performs scsi_pkt allocation.
79 	 *
80 	 * NB: A private scsi_pkt_size() interface has been added to simplify
81 	 * 'fixing' legacy HBA drivers.  Use of scsi_pkt_size() is only
82 	 * appropriate when the effort/cost of fixing a legacy driver to use
83 	 * proper DDI scsi_pkt allocation interfaces is too great given the
84 	 * remaining driver life. New HBA drivers should *not* use
85 	 * scsi_pkt_size().
86 	 *
87 	 * NB: While HBA drivers with violations are being fixed, in
88 	 * rare cases access conditioned by scsi_pkt_allocated_correctly() is
89 	 * permitted.
90 	 */
91 	/* HBA driver only, iff scsi_hba_pkt_alloc(9F)|tran_seup_pkt(9E) used */
92 	uint_t	pkt_cdblen;		/* length of pkt_cdbp */
93 	uint_t	pkt_tgtlen;		/* length of pkt_private */
94 	uint_t	pkt_scblen;		/* lenght of pkt_scbp */
95 
96 	/* HBA driver only, iff tran_seup_pkt(9E) used */
97 	ddi_dma_handle_t pkt_handle;	/* private */
98 	uint_t	pkt_numcookies;		/* number of DMA cookies */
99 	off_t	pkt_dma_offset;		/* private */
100 	size_t	pkt_dma_len;		/* private */
101 	uint_t	pkt_dma_flags;		/* DMA flags */
102 	ddi_dma_cookie_t *pkt_cookies;	/* array of DMA cookies */
103 
104 	/* private: iff scsi_pkt_allocated_correctly() */
105 	int	pkt_path_instance;	/* pHCI transport path */
106 
107 	/* stage-temporary: iff scsi_pkt_allocated_correctly() */
108 	void	*pkt_stmp;		/* temporary for current pkt stage */
109 
110 #ifdef	SCSI_SIZE_CLEAN_VERIFY
111 	/*
112 	 * Must be last: Building a driver with-and-without
113 	 * -DSCSI_SIZE_CLEAN_VERIFY, and checking driver modules for
114 	 * differences with a tools like 'wsdiff' allows a developer to verify
115 	 * that their driver has no dependencies on scsi*(9S) size.
116 	 */
117 	int			i_pkt_pad[8];
118 #endif	/* SCSI_SIZE_CLEAN_VERIFY */
119 };
120 #endif	/* _KERNEL */
121 
122 /*
123  * Definitions for the pkt_flags field.
124  */
125 
126 /*
127  * Following defines are generic.
128  */
129 #define	FLAG_STAG	0x4000	/* Run command with Simple attribute */
130 #define	FLAG_OTAG	0x2000	/* Run command with Ordered attribute */
131 #define	FLAG_HTAG	0x1000	/* Run command with Head of Queue attribute */
132 #define	FLAG_TAGMASK	(FLAG_HTAG|FLAG_OTAG|FLAG_STAG)
133 
134 #define	FLAG_ACA	0x0100	/* internal; do not use */
135 #define	FLAG_HEAD	0x8000	/* This cmd should be put at the head	*/
136 				/* of the HBA driver's queue		*/
137 #define	FLAG_SENSING	0x0400	/* Running request sense for failed pkt */
138 #define	FLAG_NOINTR	0x0001	/* Run command with no cmd completion	*/
139 				/* callback; command has been completed	*/
140 				/* upon	return from scsi_transport(9F)	*/
141 
142 /*
143  * Following defines are appropriate for SCSI parallel bus.
144  */
145 #define	FLAG_NODISCON	0x0002	/* Run command without disconnects	*/
146 #define	FLAG_NOPARITY	0x0008	/* Run command without parity checking	*/
147 #define	FLAG_RENEGOTIATE_WIDE_SYNC \
148 			0x1000000 /* Do wide and sync renegotiation before */
149 				/* transporting this command to target */
150 
151 /*
152  * Following defines are internal i.e. not part of DDI.
153  */
154 #define	FLAG_IMMEDIATE_CB \
155 			0x0800	/* Immediate callback on command */
156 				/* completion, ie. do not defer */
157 
158 /*
159  * Following defines are for USCSI options.
160  */
161 #define	FLAG_SILENT		0x00010000
162 #define	FLAG_DIAGNOSE		0x00020000
163 #define	FLAG_ISOLATE		0x00040000
164 
165 /*
166  * pkg_flag for TLR
167  */
168 #define	FLAG_TLR		0x00080000
169 
170 
171 /*
172  * Following define is for scsi_vhci.
173  *   NOQUEUE            If pHCI cannot transport the command to the device,
174  *                      do not queue the pkt in pHCI. Return immediately with
175  *                      TRAN_BUSY.
176  *   PATH_INSTANCE      Select specific path (pkt_path_instance).
177  *                      We need both a pkt_path_instance field and flag bit so
178  *                      that a retry after a path failure, which sets
179  *                      pkt_path_instance to failed path, does not select the
180  *                      failed path.
181  */
182 #define	FLAG_NOQUEUE		0x80000000
183 #define	FLAG_PKT_PATH_INSTANCE	0x40000000	/* Tell vhci the path to use */
184 #define	FLAG_PKT_COMP_CALLED	0x20000000	/* Set once pkt_comp called */
185 
186 /*
187  * Definitions for the pkt_reason field.
188  */
189 
190 /*
191  * Following defines are generic.
192  */
193 #define	CMD_CMPLT	0	/* no transport errors- normal completion */
194 #define	CMD_INCOMPLETE	1	/* transport stopped with not normal state */
195 #define	CMD_DMA_DERR	2	/* dma direction error occurred */
196 #define	CMD_TRAN_ERR	3	/* unspecified transport error */
197 #define	CMD_RESET	4	/* Target completed hard reset sequence */
198 #define	CMD_ABORTED	5	/* Command transport aborted on request */
199 #define	CMD_TIMEOUT	6	/* Command timed out */
200 #define	CMD_DATA_OVR	7	/* Data Overrun */
201 #define	CMD_CMD_OVR	8	/* Command Overrun */
202 #define	CMD_STS_OVR	9	/* Status Overrun */
203 #define	CMD_TERMINATED	22	/* Command transport terminated on request */
204 #define	CMD_TLR_OFF	23	/* don't support TLR */
205 
206 /*
207  * Following defines are appropriate for SCSI parallel bus.
208  */
209 #define	CMD_BADMSG	10	/* Message not Command Complete */
210 #define	CMD_NOMSGOUT	11	/* Target refused to go to Message Out phase */
211 #define	CMD_XID_FAIL	12	/* Extended Identify message rejected */
212 #define	CMD_IDE_FAIL	13	/* Initiator Detected Error message rejected */
213 #define	CMD_ABORT_FAIL	14	/* Abort message rejected */
214 #define	CMD_REJECT_FAIL 15	/* Reject message rejected */
215 #define	CMD_NOP_FAIL	16	/* No Operation message rejected */
216 #define	CMD_PER_FAIL	17	/* Message Parity Error message rejected */
217 #define	CMD_BDR_FAIL	18	/* Bus Device Reset message rejected */
218 #define	CMD_ID_FAIL	19	/* Identify message rejected */
219 #define	CMD_UNX_BUS_FREE	20	/* Unexpected Bus Free Phase occurred */
220 #define	CMD_TAG_REJECT	21	/* Target rejected our tag message */
221 #define	CMD_DEV_GONE	24	/* The device has been removed */
222 
223 /* Used by scsi_rname(9F) */
224 #define	CMD_REASON_ASCII	{ \
225 	    "cmplt", "incomplete", "dma_derr", "tran_err", "reset", \
226 	    "aborted", "timeout", "data_ovr", "cmd_ovr", "sts_ovr", \
227 	    "badmsg", "nomsgout", "xid_fail", "ide_fail", "abort_fail", \
228 	    "reject_fail", "nop_fail", "per_fail", "bdr_fail", "id_fail", \
229 	    "unexpected_bus_free", "tag reject", "terminated", "", "gone", \
230 	    NULL }
231 
232 /*
233  * Definitions for the pkt_state field
234  */
235 #define	STATE_GOT_BUS		0x01	/* Success in getting SCSI bus */
236 #define	STATE_GOT_TARGET	0x02	/* Successfully connected with target */
237 #define	STATE_SENT_CMD		0x04	/* Command successfully sent */
238 #define	STATE_XFERRED_DATA	0x08	/* Data transfer took place */
239 #define	STATE_GOT_STATUS	0x10	/* SCSI status received */
240 #define	STATE_ARQ_DONE		0x20	/* auto rqsense took place */
241 #define	STATE_XARQ_DONE		0X40	/* extra auto rqsense took place */
242 
243 /*
244  * Definitions for the pkt_statistics field
245  */
246 
247 /*
248  * Following defines are generic.
249  */
250 #define	STAT_BUS_RESET	0x8	/* Reset operation on interconnect */
251 #define	STAT_DEV_RESET	0x10	/* Target completed hard reset sequence */
252 #define	STAT_ABORTED	0x20	/* Command was aborted */
253 #define	STAT_TERMINATED	0x80	/* Command was terminated */
254 #define	STAT_TIMEOUT	0x40	/* Command experienced a timeout */
255 
256 /*
257  * Following defines are appropriate for SCSI parallel bus.
258  */
259 #define	STAT_DISCON	0x1	/* Command experienced a disconnect */
260 #define	STAT_SYNC	0x2	/* Command did a synchronous data transfer */
261 #define	STAT_PERR	0x4	/* Command experienced a SCSI parity error */
262 
263 /*
264  * Definitions for what scsi_transport returns
265  */
266 #define	TRAN_ACCEPT		1
267 #define	TRAN_BUSY		0
268 #define	TRAN_BADPKT		-1
269 #define	TRAN_FATAL_ERROR	-2	/* HBA cannot accept any pkts */
270 
271 #ifdef	_KERNEL
272 /*
273  * Kernel function declarations
274  */
275 int	scsi_transport(struct scsi_pkt *pkt);
276 
277 #define	pkt_transport	scsi_transport
278 
279 #define	SCSI_POLL_TIMEOUT	60
280 
281 #endif	/* _KERNEL */
282 
283 #ifdef	__cplusplus
284 }
285 #endif
286 
287 #endif	/* _SYS_SCSI_SCSI_PKT_H */
288