xref: /linux/include/scsi/scsi_cmnd.h (revision 891e811ad604805b2c706f85480e38961b706a70)
1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _SCSI_SCSI_CMND_H
3 #define _SCSI_SCSI_CMND_H
4 
5 #include <linux/dma-mapping.h>
6 #include <linux/blkdev.h>
7 #include <linux/t10-pi.h>
8 #include <linux/list.h>
9 #include <linux/types.h>
10 #include <linux/timer.h>
11 #include <linux/scatterlist.h>
12 #include <scsi/scsi_device.h>
13 
14 struct Scsi_Host;
15 
16 /*
17  * MAX_COMMAND_SIZE is:
18  * The longest fixed-length SCSI CDB as per the SCSI standard.
19  * fixed-length means: commands that their size can be determined
20  * by their opcode and the CDB does not carry a length specifier, (unlike
21  * the VARIABLE_LENGTH_CMD(0x7f) command). This is actually not exactly
22  * true and the SCSI standard also defines extended commands and
23  * vendor specific commands that can be bigger than 16 bytes. The kernel
24  * will support these using the same infrastructure used for VARLEN CDB's.
25  * So in effect MAX_COMMAND_SIZE means the maximum size command scsi-ml
26  * supports without specifying a cmd_len by ULD's
27  */
28 #define MAX_COMMAND_SIZE 16
29 
30 struct scsi_data_buffer {
31 	struct sg_table table;
32 	unsigned length;
33 };
34 
35 /* embedded in scsi_cmnd */
36 struct scsi_pointer {
37 	char *ptr;		/* data pointer */
38 	int this_residual;	/* left in this buffer */
39 	struct scatterlist *buffer;	/* which buffer */
40 	int buffers_residual;	/* how many buffers left */
41 
42         dma_addr_t dma_handle;
43 
44 	volatile int Status;
45 	volatile int Message;
46 	volatile int have_data_in;
47 	volatile int sent_command;
48 	volatile int phase;
49 };
50 
51 /* for scmd->flags */
52 #define SCMD_TAGGED		(1 << 0)
53 #define SCMD_INITIALIZED	(1 << 1)
54 #define SCMD_LAST		(1 << 2)
55 /*
56  * libata uses SCSI EH to fetch sense data for successful commands.
57  * SCSI EH should not overwrite scmd->result when SCMD_FORCE_EH_SUCCESS is set.
58  */
59 #define SCMD_FORCE_EH_SUCCESS	(1 << 3)
60 #define SCMD_FAIL_IF_RECOVERING	(1 << 4)
61 /* flags preserved across unprep / reprep */
62 #define SCMD_PRESERVED_FLAGS	(SCMD_INITIALIZED | SCMD_FAIL_IF_RECOVERING)
63 
64 /* for scmd->state */
65 #define SCMD_STATE_COMPLETE	0
66 #define SCMD_STATE_INFLIGHT	1
67 
68 enum scsi_cmnd_submitter {
69 	SUBMITTED_BY_BLOCK_LAYER = 0,
70 	SUBMITTED_BY_SCSI_ERROR_HANDLER = 1,
71 	SUBMITTED_BY_SCSI_RESET_IOCTL = 2,
72 } __packed;
73 
74 struct scsi_cmnd {
75 	struct scsi_device *device;
76 	struct list_head eh_entry; /* entry for the host eh_abort_list/eh_cmd_q */
77 	struct delayed_work abort_work;
78 
79 	struct rcu_head rcu;
80 
81 	int eh_eflags;		/* Used by error handlr */
82 
83 	int budget_token;
84 
85 	/*
86 	 * This is set to jiffies as it was when the command was first
87 	 * allocated.  It is used to time how long the command has
88 	 * been outstanding
89 	 */
90 	unsigned long jiffies_at_alloc;
91 
92 	int retries;
93 	int allowed;
94 
95 	unsigned char prot_op;
96 	unsigned char prot_type;
97 	unsigned char prot_flags;
98 	enum scsi_cmnd_submitter submitter;
99 
100 	unsigned short cmd_len;
101 	enum dma_data_direction sc_data_direction;
102 
103 	unsigned char cmnd[32]; /* SCSI CDB */
104 
105 	/* These elements define the operation we ultimately want to perform */
106 	struct scsi_data_buffer sdb;
107 	struct scsi_data_buffer *prot_sdb;
108 
109 	unsigned underflow;	/* Return error if less than
110 				   this amount is transferred */
111 
112 	unsigned transfersize;	/* How much we are guaranteed to
113 				   transfer with each SCSI transfer
114 				   (ie, between disconnect /
115 				   reconnects.   Probably == sector
116 				   size */
117 	unsigned resid_len;	/* residual count */
118 	unsigned sense_len;
119 	unsigned char *sense_buffer;
120 				/* obtained by REQUEST SENSE when
121 				 * CHECK CONDITION is received on original
122 				 * command (auto-sense). Length must be
123 				 * SCSI_SENSE_BUFFERSIZE bytes. */
124 
125 	int flags;		/* Command flags */
126 	unsigned long state;	/* Command completion state */
127 
128 	unsigned int extra_len;	/* length of alignment and padding */
129 
130 	/*
131 	 * The fields below can be modified by the LLD but the fields above
132 	 * must not be modified.
133 	 */
134 
135 	unsigned char *host_scribble;	/* The host adapter is allowed to
136 					 * call scsi_malloc and get some memory
137 					 * and hang it here.  The host adapter
138 					 * is also expected to call scsi_free
139 					 * to release this memory.  (The memory
140 					 * obtained by scsi_malloc is guaranteed
141 					 * to be at an address < 16Mb). */
142 
143 	int result;		/* Status code from lower level driver */
144 };
145 
146 /* Variant of blk_mq_rq_from_pdu() that verifies the type of its argument. */
scsi_cmd_to_rq(struct scsi_cmnd * scmd)147 static inline struct request *scsi_cmd_to_rq(struct scsi_cmnd *scmd)
148 {
149 	return blk_mq_rq_from_pdu(scmd);
150 }
151 
152 /*
153  * Return the driver private allocation behind the command.
154  * Only works if cmd_size is set in the host template.
155  */
scsi_cmd_priv(struct scsi_cmnd * cmd)156 static inline void *scsi_cmd_priv(struct scsi_cmnd *cmd)
157 {
158 	return cmd + 1;
159 }
160 
161 void scsi_done(struct scsi_cmnd *cmd);
162 void scsi_done_direct(struct scsi_cmnd *cmd);
163 
164 extern void scsi_finish_command(struct scsi_cmnd *cmd);
165 
166 extern void *scsi_kmap_atomic_sg(struct scatterlist *sg, int sg_count,
167 				 size_t *offset, size_t *len);
168 extern void scsi_kunmap_atomic_sg(void *virt);
169 
170 blk_status_t scsi_alloc_sgtables(struct scsi_cmnd *cmd);
171 void scsi_free_sgtables(struct scsi_cmnd *cmd);
172 
173 #ifdef CONFIG_SCSI_DMA
174 extern int scsi_dma_map(struct scsi_cmnd *cmd);
175 extern void scsi_dma_unmap(struct scsi_cmnd *cmd);
176 #else /* !CONFIG_SCSI_DMA */
scsi_dma_map(struct scsi_cmnd * cmd)177 static inline int scsi_dma_map(struct scsi_cmnd *cmd) { return -ENOSYS; }
scsi_dma_unmap(struct scsi_cmnd * cmd)178 static inline void scsi_dma_unmap(struct scsi_cmnd *cmd) { }
179 #endif /* !CONFIG_SCSI_DMA */
180 
scsi_sg_count(struct scsi_cmnd * cmd)181 static inline unsigned scsi_sg_count(struct scsi_cmnd *cmd)
182 {
183 	return cmd->sdb.table.nents;
184 }
185 
scsi_sglist(struct scsi_cmnd * cmd)186 static inline struct scatterlist *scsi_sglist(struct scsi_cmnd *cmd)
187 {
188 	return cmd->sdb.table.sgl;
189 }
190 
scsi_bufflen(struct scsi_cmnd * cmd)191 static inline unsigned scsi_bufflen(struct scsi_cmnd *cmd)
192 {
193 	return cmd->sdb.length;
194 }
195 
scsi_set_resid(struct scsi_cmnd * cmd,unsigned int resid)196 static inline void scsi_set_resid(struct scsi_cmnd *cmd, unsigned int resid)
197 {
198 	cmd->resid_len = resid;
199 }
200 
scsi_get_resid(struct scsi_cmnd * cmd)201 static inline unsigned int scsi_get_resid(struct scsi_cmnd *cmd)
202 {
203 	return cmd->resid_len;
204 }
205 
206 #define scsi_for_each_sg(cmd, sg, nseg, __i)			\
207 	for_each_sg(scsi_sglist(cmd), sg, nseg, __i)
208 
scsi_sg_copy_from_buffer(struct scsi_cmnd * cmd,const void * buf,int buflen)209 static inline int scsi_sg_copy_from_buffer(struct scsi_cmnd *cmd,
210 					   const void *buf, int buflen)
211 {
212 	return sg_copy_from_buffer(scsi_sglist(cmd), scsi_sg_count(cmd),
213 				   buf, buflen);
214 }
215 
scsi_sg_copy_to_buffer(struct scsi_cmnd * cmd,void * buf,int buflen)216 static inline int scsi_sg_copy_to_buffer(struct scsi_cmnd *cmd,
217 					 void *buf, int buflen)
218 {
219 	return sg_copy_to_buffer(scsi_sglist(cmd), scsi_sg_count(cmd),
220 				 buf, buflen);
221 }
222 
scsi_get_sector(struct scsi_cmnd * scmd)223 static inline sector_t scsi_get_sector(struct scsi_cmnd *scmd)
224 {
225 	return blk_rq_pos(scsi_cmd_to_rq(scmd));
226 }
227 
scsi_get_lba(struct scsi_cmnd * scmd)228 static inline sector_t scsi_get_lba(struct scsi_cmnd *scmd)
229 {
230 	unsigned int shift = ilog2(scmd->device->sector_size) - SECTOR_SHIFT;
231 
232 	return blk_rq_pos(scsi_cmd_to_rq(scmd)) >> shift;
233 }
234 
scsi_logical_block_count(struct scsi_cmnd * scmd)235 static inline unsigned int scsi_logical_block_count(struct scsi_cmnd *scmd)
236 {
237 	unsigned int shift = ilog2(scmd->device->sector_size);
238 
239 	return blk_rq_bytes(scsi_cmd_to_rq(scmd)) >> shift;
240 }
241 
242 /*
243  * The operations below are hints that tell the controller driver how
244  * to handle I/Os with DIF or similar types of protection information.
245  */
246 enum scsi_prot_operations {
247 	/* Normal I/O */
248 	SCSI_PROT_NORMAL = 0,
249 
250 	/* OS-HBA: Protected, HBA-Target: Unprotected */
251 	SCSI_PROT_READ_INSERT,
252 	SCSI_PROT_WRITE_STRIP,
253 
254 	/* OS-HBA: Unprotected, HBA-Target: Protected */
255 	SCSI_PROT_READ_STRIP,
256 	SCSI_PROT_WRITE_INSERT,
257 
258 	/* OS-HBA: Protected, HBA-Target: Protected */
259 	SCSI_PROT_READ_PASS,
260 	SCSI_PROT_WRITE_PASS,
261 };
262 
scsi_set_prot_op(struct scsi_cmnd * scmd,unsigned char op)263 static inline void scsi_set_prot_op(struct scsi_cmnd *scmd, unsigned char op)
264 {
265 	scmd->prot_op = op;
266 }
267 
scsi_get_prot_op(struct scsi_cmnd * scmd)268 static inline unsigned char scsi_get_prot_op(struct scsi_cmnd *scmd)
269 {
270 	return scmd->prot_op;
271 }
272 
273 enum scsi_prot_flags {
274 	SCSI_PROT_TRANSFER_PI		= 1 << 0,
275 	SCSI_PROT_GUARD_CHECK		= 1 << 1,
276 	SCSI_PROT_REF_CHECK		= 1 << 2,
277 	SCSI_PROT_REF_INCREMENT		= 1 << 3,
278 	SCSI_PROT_IP_CHECKSUM		= 1 << 4,
279 };
280 
281 /*
282  * The controller usually does not know anything about the target it
283  * is communicating with.  However, when DIX is enabled the controller
284  * must be know target type so it can verify the protection
285  * information passed along with the I/O.
286  */
287 enum scsi_prot_target_type {
288 	SCSI_PROT_DIF_TYPE0 = 0,
289 	SCSI_PROT_DIF_TYPE1,
290 	SCSI_PROT_DIF_TYPE2,
291 	SCSI_PROT_DIF_TYPE3,
292 };
293 
scsi_set_prot_type(struct scsi_cmnd * scmd,unsigned char type)294 static inline void scsi_set_prot_type(struct scsi_cmnd *scmd, unsigned char type)
295 {
296 	scmd->prot_type = type;
297 }
298 
scsi_get_prot_type(struct scsi_cmnd * scmd)299 static inline unsigned char scsi_get_prot_type(struct scsi_cmnd *scmd)
300 {
301 	return scmd->prot_type;
302 }
303 
scsi_prot_ref_tag(struct scsi_cmnd * scmd)304 static inline u32 scsi_prot_ref_tag(struct scsi_cmnd *scmd)
305 {
306 	struct request *rq = blk_mq_rq_from_pdu(scmd);
307 
308 	return t10_pi_ref_tag(rq);
309 }
310 
scsi_prot_interval(struct scsi_cmnd * scmd)311 static inline unsigned int scsi_prot_interval(struct scsi_cmnd *scmd)
312 {
313 	return scmd->device->sector_size;
314 }
315 
scsi_prot_sg_count(struct scsi_cmnd * cmd)316 static inline unsigned scsi_prot_sg_count(struct scsi_cmnd *cmd)
317 {
318 	return cmd->prot_sdb ? cmd->prot_sdb->table.nents : 0;
319 }
320 
scsi_prot_sglist(struct scsi_cmnd * cmd)321 static inline struct scatterlist *scsi_prot_sglist(struct scsi_cmnd *cmd)
322 {
323 	return cmd->prot_sdb ? cmd->prot_sdb->table.sgl : NULL;
324 }
325 
scsi_prot(struct scsi_cmnd * cmd)326 static inline struct scsi_data_buffer *scsi_prot(struct scsi_cmnd *cmd)
327 {
328 	return cmd->prot_sdb;
329 }
330 
331 #define scsi_for_each_prot_sg(cmd, sg, nseg, __i)		\
332 	for_each_sg(scsi_prot_sglist(cmd), sg, nseg, __i)
333 
set_status_byte(struct scsi_cmnd * cmd,char status)334 static inline void set_status_byte(struct scsi_cmnd *cmd, char status)
335 {
336 	cmd->result = (cmd->result & 0xffffff00) | status;
337 }
338 
get_status_byte(struct scsi_cmnd * cmd)339 static inline u8 get_status_byte(struct scsi_cmnd *cmd)
340 {
341 	return cmd->result & 0xff;
342 }
343 
set_host_byte(struct scsi_cmnd * cmd,char status)344 static inline void set_host_byte(struct scsi_cmnd *cmd, char status)
345 {
346 	cmd->result = (cmd->result & 0xff00ffff) | (status << 16);
347 }
348 
get_host_byte(struct scsi_cmnd * cmd)349 static inline u8 get_host_byte(struct scsi_cmnd *cmd)
350 {
351 	return (cmd->result >> 16) & 0xff;
352 }
353 
354 /**
355  * scsi_msg_to_host_byte() - translate message byte
356  * @cmd: the SCSI command
357  * @msg: the SCSI parallel message byte to translate
358  *
359  * Translate the SCSI parallel message byte to a matching
360  * host byte setting. A message of COMMAND_COMPLETE indicates
361  * a successful command execution, any other message indicate
362  * an error. As the messages themselves only have a meaning
363  * for the SCSI parallel protocol this function translates
364  * them into a matching host byte value for SCSI EH.
365  */
scsi_msg_to_host_byte(struct scsi_cmnd * cmd,u8 msg)366 static inline void scsi_msg_to_host_byte(struct scsi_cmnd *cmd, u8 msg)
367 {
368 	switch (msg) {
369 	case COMMAND_COMPLETE:
370 		break;
371 	case ABORT_TASK_SET:
372 		set_host_byte(cmd, DID_ABORT);
373 		break;
374 	case TARGET_RESET:
375 		set_host_byte(cmd, DID_RESET);
376 		break;
377 	default:
378 		set_host_byte(cmd, DID_ERROR);
379 		break;
380 	}
381 }
382 
scsi_transfer_length(struct scsi_cmnd * scmd)383 static inline unsigned scsi_transfer_length(struct scsi_cmnd *scmd)
384 {
385 	unsigned int xfer_len = scmd->sdb.length;
386 	unsigned int prot_interval = scsi_prot_interval(scmd);
387 
388 	if (scmd->prot_flags & SCSI_PROT_TRANSFER_PI)
389 		xfer_len += (xfer_len >> ilog2(prot_interval)) * 8;
390 
391 	return xfer_len;
392 }
393 
394 extern void scsi_build_sense(struct scsi_cmnd *scmd, int desc,
395 			     u8 key, u8 asc, u8 ascq);
396 
397 struct request *scsi_alloc_request(struct request_queue *q, blk_opf_t opf,
398 				   blk_mq_req_flags_t flags);
399 
400 #endif /* _SCSI_SCSI_CMND_H */
401