e38657a268f645119e40cb983a3ee3a92f0bc9a4
[mirror/scst/.git] / scst / include / scsi_tgt.h
1 /*
2  *  include/scsi_tgt.h
3  *  
4  *  Copyright (C) 2004-2006 Vladislav Bolkhovitin <vst@vlnb.net>
5  *                 and Leonid Stoljar
6  *  
7  *  Main SCSI target mid-level include file.
8  * 
9  *  This program is free software; you can redistribute it and/or
10  *  modify it under the terms of the GNU General Public License
11  *  as published by the Free Software Foundation, version 2
12  *  of the License.
13  * 
14  *  This program is distributed in the hope that it will be useful,
15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  *  GNU General Public License for more details.
18  */
19
20 #ifndef __SCST_H
21 #define __SCST_H
22
23 #include <linux/types.h>
24 #include <linux/version.h>
25 #include <linux/blkdev.h>
26 #include <linux/interrupt.h>
27 #ifdef SCST_HIGHMEM
28 #include <asm/kmap_types.h>
29 #endif
30 #include <../drivers/scsi/scsi.h>
31
32 /* Version numbers, the same as for the kernel */
33 #define SCST_VERSION_CODE 0x000905
34 #define SCST_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
35 #define SCST_VERSION_STRING "0.9.5-pre2"
36
37 /*************************************************************
38  ** States of command processing state machine
39  *************************************************************/
40
41 /* A cmd is created, but scst_cmd_init_done() not called */
42 #define SCST_CMD_STATE_INIT_WAIT     1
43
44 /* LUN translation (cmd->tgt_dev assignment) */
45 #define SCST_CMD_STATE_INIT          2
46
47 /* 
48  * Again LUN translation (cmd->tgt_dev assignment), used if dev handler
49  * wants to restart cmd on another LUN
50  */
51 #define SCST_CMD_STATE_REINIT        3
52
53 /* Dev handler's parse() is going to be called */
54 #define SCST_CMD_STATE_DEV_PARSE     4
55
56 /* Allocation of the cmd's data buffer */
57 #define SCST_CMD_STATE_PREPARE_SPACE 5
58
59 /* Target driver's rdy_to_xfer() is going to be called */
60 #define SCST_CMD_STATE_RDY_TO_XFER   6
61
62 /* Waiting for data from the initiator (until scst_rx_data() called) */
63 #define SCST_CMD_STATE_DATA_WAIT     7
64
65 /* CDB is going to be sent to SCSI mid-level for execution */
66 #define SCST_CMD_STATE_SEND_TO_MIDLEV 8
67
68 /* Waiting for CDB's execution finish */
69 #define SCST_CMD_STATE_EXECUTING     9
70
71 /* Dev handler's dev_done() is going to be called */
72 #define SCST_CMD_STATE_DEV_DONE      10
73
74 /* Target driver's xmit_response() is going to be called */
75 #define SCST_CMD_STATE_XMIT_RESP     11
76
77 /* Waiting for response's transmission finish */
78 #define SCST_CMD_STATE_XMIT_WAIT     12
79
80 /* The cmd finished */
81 #define SCST_CMD_STATE_FINISHED      14
82
83 /************************************************************* 
84  ** Can be retuned instead of cmd's state by dev handlers' 
85  ** functions, if the command's state should be set by default
86  *************************************************************/
87 #define SCST_CMD_STATE_DEFAULT       0
88
89 /************************************************************* 
90  ** Can be retuned instead of cmd's state by dev handlers' 
91  ** functions, if it is impossible to complete requested
92  ** task in atomic context. The cmd will be restarted in thread 
93  ** context.
94  *************************************************************/
95 #define SCST_CMD_STATE_NEED_THREAD_CTX       100
96
97 /*************************************************************
98  ** States of mgmt command processing state machine
99  *************************************************************/
100
101 /* LUN translation (mcmd->tgt_dev assignment) */
102 #define SCST_MGMT_CMD_STATE_INIT     1
103
104 /* Mgmt cmd is ready for processing */
105 #define SCST_MGMT_CMD_STATE_READY    2
106
107 /* Mgmt cmd is being executing */
108 #define SCST_MGMT_CMD_STATE_EXECUTING 3
109
110 /* Target driver's task_mgmt_fn_done() is going to be called */
111 #define SCST_MGMT_CMD_STATE_DONE     4
112
113 /* The mcmd finished */
114 #define SCST_MGMT_CMD_STATE_FINISHED 5
115
116 /*************************************************************
117  ** Constants for "atomic" parameter of SCST's functions
118  *************************************************************/
119 #define SCST_NON_ATOMIC              0
120 #define SCST_ATOMIC                  1
121
122 /************************************************************* 
123  ** Values for pref_context parameter of scst_cmd_init_done() and 
124  ** scst_rx_data() 
125  *************************************************************/
126
127 /* 
128  * Direct cmd's processing (i.e. regular function calls in the current 
129  * context), sleeping is allowed, no restrictions
130  */
131 #define SCST_CONTEXT_DIRECT          0
132
133 /* 
134  * Direct cmd's processing (i.e. regular function calls in the current 
135  * context) sleeping is not allowed
136  */
137 #define SCST_CONTEXT_DIRECT_ATOMIC   1
138
139 /* Tasklet or thread context required for cmd's processing */
140 #define SCST_CONTEXT_TASKLET         2
141
142 /* Thread context required for cmd's processing */
143 #define SCST_CONTEXT_THREAD          3
144
145 /*
146  * Additional bit to set processible environment.
147  * Private for SCST, ie must not be used target drivers.
148  */
149 #define SCST_PROCESSIBLE_ENV         0x10000000
150
151 /************************************************************* 
152  ** Values for status parameter of scst_rx_data() 
153  *************************************************************/
154
155 /* Success */
156 #define SCST_RX_STATUS_SUCCESS       0
157
158 /* 
159  * Data receiving finished with error, so set the sense and 
160  * finish the command, including xmit_response() call
161  */
162 #define SCST_RX_STATUS_ERROR         1
163
164 /* 
165  * Data receiving finished with error and the sense is set,  
166  * so finish the command, including xmit_response() call
167  */
168 #define SCST_RX_STATUS_ERROR_SENSE_SET 2
169
170 /* 
171  * Data receiving finished with fatal error, so finish the command, 
172  * but don't call xmit_response()
173  */
174 #define SCST_RX_STATUS_ERROR_FATAL   3
175
176 /*************************************************************
177  ** Allowed return codes for xmit_response(), rdy_to_xfer(), 
178  ** report_aen() 
179  *************************************************************/
180
181 /* Success */
182 #define SCST_TGT_RES_SUCCESS         0
183
184 /* Internal device queue is full, retry again later */
185 #define SCST_TGT_RES_QUEUE_FULL      -1
186
187 /* 
188  * It is impossible to complete requested task in atomic context. 
189  * The cmd will be restarted in thread  context.
190  */
191 #define SCST_TGT_RES_NEED_THREAD_CTX -2
192
193 /* 
194  * Fatal error, if returned by xmit_response() the cmd will 
195  * be destroyed, if by any other function, xmit_response() 
196  * will be called with HARDWARE ERROR sense data
197  */
198 #define SCST_TGT_RES_FATAL_ERROR     -3
199
200 /*************************************************************
201  ** Allowed return codes for dev handler's exec()
202  *************************************************************/
203
204 /* The cmd is done, go to other ones */
205 #define SCST_EXEC_COMPLETED          0
206
207 /* The cmd should be sent to SCSI mid-level */
208 #define SCST_EXEC_NOT_COMPLETED      1
209
210 /* 
211  * Thread context is required to execute the command. 
212  * Exec() will be called again in the thread context.
213  */
214 #define SCST_EXEC_NEED_THREAD        2
215
216 /*************************************************************
217  ** Allowed return codes for dev handler's task_mgmt_fn()
218  *************************************************************/
219
220 /* The command is done with success, no firther actions required */
221 #define SCST_DEV_TM_COMPLETED_SUCCESS 0
222
223 /* The command is failed, no firther actions required */
224 #define SCST_DEV_TM_COMPLETED_FAILED  -1
225
226 /* Regular standard actions for the command should be done */
227 #define SCST_DEV_TM_NOT_COMPLETED     1
228
229 /************************************************************* 
230  ** Default timeout and retries count for cmd's CDB execution 
231  ** by SCSI mid-level (cmd's "timeout" and "retries" fields).
232  *************************************************************/
233 #define SCST_DEFAULT_RETRIES         5
234 #define SCST_DEFAULT_TIMEOUT         (30*HZ)
235
236 /************************************************************* 
237  ** Data direction aliases 
238  *************************************************************/
239 #define SCST_DATA_UNKNOWN            DMA_BIDIRECTIONAL
240 #define SCST_DATA_WRITE              DMA_TO_DEVICE
241 #define SCST_DATA_READ               DMA_FROM_DEVICE
242 #define SCST_DATA_NONE               DMA_NONE
243
244 /*************************************************************
245  ** Flags of cmd->tgt_resp_flags
246  *************************************************************/
247
248 /* 
249  * Set if cmd is finished and there is status/sense to be sent. 
250  * The status should be not sent (i.e. the flag not set) if the 
251  * possibility to perform a command in "chunks" (i.e. with multiple 
252  * xmit_response()/rdy_to_xfer()) is used (not implemented and,
253  * probably, will never be).
254  */
255 #define SCST_TSC_FLAG_STATUS         0x2
256
257 /************************************************************* 
258  ** Values for management functions
259  *************************************************************/
260 #define SCST_ABORT_TASK              0
261 #define SCST_ABORT_TASK_SET          1
262 #define SCST_CLEAR_ACA               2
263 #define SCST_CLEAR_TASK_SET          3
264 #define SCST_LUN_RESET               4
265 #define SCST_TARGET_RESET            5
266
267 /** SCST extensions **/
268
269 /* 
270  * Notifies about I_T nexus loss event in the corresponding session.
271  * Aborts all tasks there, resets the reservation, if any, and sets
272  * up the I_T Nexus loss UA.
273  */
274 #define SCST_NEXUS_LOSS_SESS         6
275
276 /* Aborts all tasks in the corresponding session with TASK_ABORTED status */
277 #define SCST_ABORT_ALL_TASKS_SESS    7
278
279 /* 
280  * Notifies about I_T nexus loss event. Aborts all tasks in all sessions
281  * of the tgt, resets the reservations, if any,  and sets up the I_T Nexus
282  * loss UA.
283  */
284 #define SCST_NEXUS_LOSS              8
285
286 /* Aborts all tasks in all sessions of the tgt with TASK_ABORTED status */
287 #define SCST_ABORT_ALL_TASKS         9
288
289 /************************************************************* 
290  ** Values for mgmt cmd's "status"
291  *************************************************************/
292 #define SCST_MGMT_STATUS_SUCCESS     0
293 #define SCST_MGMT_STATUS_FAILED     -1
294
295 /************************************************************* 
296  ** Session initialization phases
297  *************************************************************/
298
299 /* Set if session is being initialized */
300 #define SCST_SESS_IPH_INITING        0
301
302 /* Set if the session is successfully initialized */
303 #define SCST_SESS_IPH_SUCCESS        1
304
305 /* Set if the session initialization failed */
306 #define SCST_SESS_IPH_FAILED         2
307
308 /* Set if session is initialized and ready */
309 #define SCST_SESS_IPH_READY          3
310
311 /*************************************************************
312  ** Cmd's async (atomic) flags 
313  *************************************************************/
314
315 /* Set if the cmd is aborted and ABORTED sense will be sent as the result */
316 #define SCST_CMD_ABORTED                0
317
318 /* Set if the cmd is aborted by other initiator */
319 #define SCST_CMD_ABORTED_OTHER          1
320
321 /* Set if no response should be sent to the target about this cmd */
322 #define SCST_CMD_NO_RESP                2
323
324 /*
325  * Set if the cmd is being executed. Needed to guarantee that 
326  * "no further responses from the task are sent to
327  * the SCSI initiator port" after response from the TM function is 
328  * sent (SAM) as well as correct ABORT TASK status code
329  */
330 #define SCST_CMD_EXECUTING              3
331
332 /*
333  * Set if the cmd status/data are being xmitted. The purpose is the
334  * same as for SCST_CMD_EXECUTING
335  */
336 #define SCST_CMD_XMITTING               4
337
338 /* Set if the cmd was done or aborted out of its SN */
339 #define SCST_CMD_OUT_OF_SN              5
340
341 /* Set if the cmd is dead and can be destroyed at any time */
342 #define SCST_CMD_CAN_BE_DESTROYED       6
343
344 /*
345  * Set if the cmd is throtteled, ie put on hold since there
346  * are too many pending commands.
347  */
348 #define SCST_CMD_THROTTELED             7
349
350 /*************************************************************
351  ** Tgt_dev's flags 
352  *************************************************************/
353
354 /* Set if tgt_dev has Unit Attention sense */
355 #define SCST_TGT_DEV_UA_PENDING      0
356
357 /* Set if tgt_dev is RESERVED by another session */
358 #define SCST_TGT_DEV_RESERVED        1
359
360 #ifdef DEBUG_TM
361 #define SCST_TGT_DEV_UNDER_TM_DBG    10
362 #endif
363
364 /************************************************************* 
365  ** Commands that are not listed anywhere else 
366  *************************************************************/
367 #ifndef REPORT_DEVICE_IDENTIFIER
368 #define REPORT_DEVICE_IDENTIFIER    0xA3
369 #endif
370 #ifndef INIT_ELEMENT_STATUS
371 #define INIT_ELEMENT_STATUS         0x07
372 #endif
373 #ifndef INIT_ELEMENT_STATUS_RANGE
374 #define INIT_ELEMENT_STATUS_RANGE   0x37
375 #endif
376 #ifndef PREVENT_ALLOW_MEDIUM
377 #define PREVENT_ALLOW_MEDIUM        0x1E
378 #endif
379 #ifndef READ_ATTRIBUTE
380 #define READ_ATTRIBUTE              0x8C
381 #endif
382 #ifndef REQUEST_VOLUME_ADDRESS
383 #define REQUEST_VOLUME_ADDRESS      0xB5
384 #endif
385 #ifndef WRITE_ATTRIBUTE
386 #define WRITE_ATTRIBUTE             0x8D
387 #endif
388 #ifndef WRITE_VERIFY_16
389 #define WRITE_VERIFY_16             0x8E
390 #endif
391 #ifndef VERIFY_6
392 #define VERIFY_6                    0x13
393 #endif
394 #ifndef VERIFY_12
395 #define VERIFY_12                   0xAF
396 #endif
397
398 /*************************************************************
399  ** Control byte field in CDB
400  *************************************************************/
401 #ifndef CONTROL_BYTE_LINK_BIT
402 #define CONTROL_BYTE_LINK_BIT       0x01
403 #endif
404 #ifndef CONTROL_BYTE_NACA_BIT
405 #define CONTROL_BYTE_NACA_BIT       0x04
406 #endif
407
408 /*************************************************************
409  ** Byte 1 in INQUIRY CDB
410  *************************************************************/
411 #define SCST_INQ_EVPD                0x01
412
413 /*************************************************************
414  ** Byte 3 in Standard INQUIRY data
415  *************************************************************/
416 #define SCST_INQ_BYTE3               3
417
418 #define SCST_INQ_NORMACA_BIT         0x20
419
420 /*************************************************************
421  ** Byte 2 in RESERVE_10 CDB
422  *************************************************************/
423 #define SCST_RES_3RDPTY              0x10
424 #define SCST_RES_LONGID              0x02
425
426 /************************************************************* 
427  ** Misc SCSI constants
428  *************************************************************/
429 #define SCST_SENSE_ASC_UA_RESET      0x29
430
431 /*************************************************************
432  ** Name of the entry in /proc
433  *************************************************************/
434 #define SCST_PROC_ENTRY_NAME         "scsi_tgt"
435
436 /*************************************************************
437  ** Used with scst_set_cmd_error() 
438  *************************************************************/
439 #define SCST_LOAD_SENSE(key_asc_ascq) key_asc_ascq
440
441 #define SCST_SENSE_VALID(sense)      ((((uint8_t *)(sense))[0] & 0x70) == 0x70)
442
443 #define SCST_NO_SENSE(sense)         (((uint8_t *)(sense))[2] == 0)
444
445 /*************************************************************
446  *                     TYPES
447  *************************************************************/
448
449 struct scst_tgt;
450 struct scst_session;
451 struct scst_cmd;
452 struct scst_mgmt_cmd;
453 struct scst_device;
454 struct scst_tgt_dev;
455 struct scst_dev_type;
456 struct scst_info_cdb;
457 struct scst_acg;
458 struct scst_acg_dev;
459 struct scst_acn;
460
461 typedef uint32_t lun_t;
462
463 typedef enum dma_data_direction scst_data_direction;
464
465 /* 
466  * Scsi_Target_Template: defines what functions a target driver will
467  * have to provide in order to work with the target mid-level. 
468  * MUST HAVEs define functions that are expected to be in order to work. 
469  * OPTIONAL says that there is a choice.
470  * Also, pay attention to the fact that a command is BLOCKING or NON-BLOCKING.
471  * NON-BLOCKING means that a function returns immediately and will not wait
472  * for actual data transfer to finish. Blocking in such command could have 
473  * negative impact on overall system performance. If blocking is necessary, 
474  * it is worth to consider creating dedicated thread(s) in target driver, to 
475  * which the commands would be passed and which would perform blocking 
476  * operations instead of SCST.
477  * If the function allowed to sleep or not is determined by its last 
478  * argument, which is true, if sleeping is not allowed. In this case, 
479  * if the function requires sleeping, it  can return 
480  * SCST_TGT_RES_NEED_THREAD_CTX, and it will be recalled in the thread context,
481  * where sleeping is allowed.
482  */
483 struct scst_tgt_template
484 {
485         /* public: */
486
487         /* 
488          * Name of the template. Must be unique to identify
489          * the template. MUST HAVE
490          */
491         const char name[15];
492
493         /* 
494          * SG tablesize allows to check whether scatter/gather can be used
495          * or not. 
496          */
497         int sg_tablesize;
498
499         /*
500          * True, if this target adapter uses unchecked DMA onto an ISA bus.
501          */
502         unsigned unchecked_isa_dma:1;
503
504         /*
505          * True, if this target adapter wants to use clustering 
506          * (i.e. smaller number of segments).
507          */
508         unsigned use_clustering:1;
509
510         /*
511          * True, if corresponding function supports execution in
512          * the atomic (non-sleeping) context
513          */
514         unsigned xmit_response_atomic:1;
515         unsigned rdy_to_xfer_atomic:1;
516
517         /* True, if the template doesn't need the entry in /proc */
518         unsigned no_proc_entry:1;
519
520         /*
521          * True, if the target requires that *ALL* affecting by a task
522          * management command outstanding SCSI commands finished before
523          * sending the TM command reply. Otherwise, the TM reply will be
524          * send immediately after it is insured, that the affecting SCSI
525          * commands will reach xmit_response() with ABORTED flag set (see
526          * also scst_cmd_aborted()).
527          */
528         unsigned tm_sync_reply:1;
529
530         /*
531          * This function should detect the target adapters that
532          * are present in the system. The function should return a value
533          * >= 0 to signify the number of detected target adapters. 
534          * A negative value should be returned whenever there is
535          * an error. 
536          *
537          * MUST HAVE
538          */
539         int (*detect) (struct scst_tgt_template *tgt_template);
540
541         /*
542          * This function should free up the resources allocated to the device. 
543          * The function should return 0 to indicate successful release 
544          * or a negative value if there are some issues with the release. 
545          * In the current version the return value is ignored.
546          *
547          * MUST HAVE
548          */
549         int (*release) (struct scst_tgt *tgt);
550
551         /*
552          * This function is equivalent to the SCSI
553          * queuecommand. The target should transmit the response
554          * buffer and the status in the scst_cmd struct. 
555          * The expectation is that this executing this command is NON-BLOCKING. 
556          * 
557          * After the response is actually transmitted, the target 
558          * should call the scst_tgt_cmd_done() function of the 
559          * mid-level, which will allow it to free up the command.
560          * Returns one of the SCST_TGT_RES_* constants.
561          *
562          * Pay attention to "atomic" attribute of the cmd, which can be get
563          * by scst_cmd_atomic(): it is true if the function called in the
564          * atomic (non-sleeping) context.
565          *
566          * MUST HAVE
567          */
568         int (*xmit_response) (struct scst_cmd *cmd);
569
570         /*
571          * This function allows the target driver to handle data buffer
572          * allocations on its own.
573          * Shall return 0 in case of success, and != 0 (preferrably -ENOMEM)
574          * in case of error. In case of returning successfully,
575          * scst_cmd->data_buf_alloced will be set by SCST.
576          *
577          * If allocation in atomic context - cf. scst_cmd_atomic() - is not
578          * desired or fails and consequently != 0 is returned, this function
579          * will be re-called in thread context.
580          *
581          * Please note that the driver will have to handle all relevant details
582          * such as scatterlist setup, highmem, freeing the allocated memory, ...
583          * itself.
584          *
585          * OPTIONAL.
586          */
587         int (*alloc_data_buf) (struct scst_cmd *cmd);
588
589         /*
590          * This function informs the driver that data
591          * buffer corresponding to the said command have now been
592          * allocated and it is OK to receive data for this command.
593          * This function is necessary because a SCSI target does not
594          * have any control over the commands it receives. Most lower
595          * level protocols have a corresponding function which informs
596          * the initiator that buffers have been allocated e.g., XFER_
597          * RDY in Fibre Channel. After the data is actually received
598          * the low-level driver needs to call scst_rx_data() in order to 
599          * continue processing this command.
600          * Returns one of the SCST_TGT_RES_* constants.
601          * This command is expected to be NON-BLOCKING.
602          *
603          * Pay attention to "atomic" attribute of the cmd, which can be get
604          * by scst_cmd_atomic(): it is true if the function called in the
605          * atomic (non-sleeping) context.
606          *
607          * MUST HAVE.
608          */
609         int (*rdy_to_xfer) (struct scst_cmd *cmd);
610
611         /* 
612          * Called to notify the driver that the command is about to be freed.
613          * Necessary, because for aborted commands xmit_response() could not
614          * be called. Could be called on IRQ context.
615          *
616          * MUST HAVE
617          */
618         void (*on_free_cmd) (struct scst_cmd *cmd);
619
620         /*
621          * This function informs the driver that a
622          * received task management function has been completed. This
623          * function is necessary because low-level protocols have some
624          * means of informing the initiator about the completion of a
625          * Task Management function. This function being called will
626          * signify that a Task Management function is completed as far
627          * as the mid-level is concerned. Any information that must be
628          * stored about the command is the responsibility of the low-
629          * level driver. No return value expected. 
630          * This function is expected to be NON-BLOCKING
631          *
632          * Pay attention to "atomic" attribute of the cmd, which can be get
633          * by scst_cmd_atomic(): it is true if the function called in the
634          * atomic (non-sleeping) context.
635          *
636          * MUST HAVE if the target supports ABORTs
637          */
638         void (*task_mgmt_fn_done) (struct scst_mgmt_cmd *mgmt_cmd);
639
640         /*
641          * This function is used for Asynchronous Event Notification. 
642          * It is the responsibility of the driver to notify any/all
643          * initiators about the Asynchronous Event reported.
644          * Returns one of the SCST_TGT_RES_* constants.
645          * This command is expected to be NON-BLOCKING, but can sleep.
646          *
647          * MUST HAVE if low-level protocol supports AEN
648          *
649          * ToDo
650          */
651         int (*report_aen) (int mgmt_fn, const uint8_t *lun, int lun_len);
652
653         /* 
654          * This function can be used to export the driver's statistics and 
655          * other infos to the world outside the kernel. 
656          *
657          * OPTIONAL
658          */
659         int (*proc_info) (char *buffer, char **start, off_t offset, 
660                 int length, int *eof, struct scst_tgt *tgt, int inout);
661
662         /* Private, must be inited to 0 by memset() */
663
664         /* List of targets per template, protected by scst_mutex */
665         struct list_head tgt_list;
666
667         /* List entry of global templates list */
668         struct list_head scst_template_list_entry;
669
670         /* The pointer to the /proc directory entry */
671         struct proc_dir_entry *proc_tgt_root;
672
673         /* Dedicated thread number */
674         int thread_num;
675         
676         /* Device number in /proc */
677         int proc_dev_num;
678 };
679
680 struct scst_dev_type
681 {
682         /* Name of the dev handler. Must be unique. MUST HAVE */
683         char name[15];
684
685         /* SCSI type of the supported device. MUST HAVE */
686         int type;
687
688         /*
689          * True, if corresponding function supports execution in
690          * the atomic (non-sleeping) context
691          */
692         unsigned parse_atomic:1;
693         unsigned exec_atomic:1;
694         unsigned dev_done_atomic:1;
695
696         /* 
697          * Called when new device is attaching to the dev handler
698          * Returns 0 on success, error code otherwise.
699          */
700         int (*attach) (struct scst_device *dev);
701
702         /* Called when new device is detaching from the dev handler */
703         void (*detach) (struct scst_device *dev);
704
705         /* 
706          * Called when new tgt_dev (session) is attaching to the dev handler.
707          * Returns 0 on success, error code otherwise.
708          */
709         int (*attach_tgt) (struct scst_tgt_dev *tgt_dev);
710
711         /* Called when tgt_dev (session) is detaching from the dev handler */
712         void (*detach_tgt) (struct scst_tgt_dev *tgt_dev);
713
714         /* 
715          * Called to parse CDB from the cmd and initialize 
716          * cmd->bufflen and cmd->data_direction (both - REQUIRED).
717          * Returns the command's next state or SCST_CMD_STATE_DEFAULT, 
718          * if the next default state should be used, or 
719          * SCST_CMD_STATE_NEED_THREAD_CTX if the function called in atomic 
720          * context, but requires sleeping. In the last case, the function 
721          * will be recalled in the thread context, where sleeping is allowed.
722          *
723          * Pay attention to "atomic" attribute of the cmd, which can be get
724          * by scst_cmd_atomic(): it is true if the function called in the
725          * atomic (non-sleeping) context.
726          *
727          * MUST HAVE
728          */
729         int (*parse) (struct scst_cmd *cmd,
730                       const struct scst_info_cdb *cdb_info);
731
732         /* 
733          * Called to execute CDB. Useful, for instance, to implement 
734          * data caching. The result of CDB execution is reported via 
735          * cmd->scst_cmd_done() callback.
736          * Returns: 
737          *  - SCST_EXEC_COMPLETED - the cmd is done, go to other ones
738          *  - SCST_EXEC_NEED_THREAD - thread context is required to execute
739          *    the command. Exec() will be called again in the thread context.
740          *  - SCST_EXEC_NOT_COMPLETED - the cmd should be sent to SCSI mid-level.
741          *
742          * Pay attention to "atomic" attribute of the cmd, which can be get
743          * by scst_cmd_atomic(): it is true if the function called in the
744          * atomic (non-sleeping) context.
745          *
746          * OPTIONAL, if not set, the commands will be sent directly to SCSI
747          * device.
748          */
749         int (*exec) (struct scst_cmd *cmd);
750
751         /* 
752          * Called to notify dev handler about the result of cmd execution
753          * and perform some post processing. Cmd's fields tgt_resp_flags and
754          * resp_data_len should be set by this function, but SCST offers good
755          * defaults.
756          * Returns the command's next state or SCST_CMD_STATE_DEFAULT, 
757          * if the next default state should be used, or 
758          * SCST_CMD_STATE_NEED_THREAD_CTX if the function called in atomic 
759          * context, but requires sleeping. In the last case, the function 
760          * will be recalled in the thread context, where sleeping is allowed.
761          *
762          * Pay attention to "atomic" attribute of the cmd, which can be get
763          * by scst_cmd_atomic(): it is true if the function called in the
764          * atomic (non-sleeping) context.
765          */
766         int (*dev_done) (struct scst_cmd *cmd);
767
768         /* 
769          * Called to notify dev hander that the command is about to be freed.
770          * Could be called on IRQ context.
771          */
772         void (*on_free_cmd) (struct scst_cmd *cmd);
773
774         /* 
775          * Called to execute a task management command. 
776          * Returns: 
777          *  - SCST_DEV_TM_COMPLETED_SUCCESS - the command is done with success,
778          *      no firther actions required
779          *  - SCST_DEV_TM_COMPLETED_FAILED - the command is failed, 
780          *      no firther actions required
781          *  - SCST_DEV_TM_NOT_COMPLETED - regular standard actions for the command
782          *      should be done
783          *
784          * NOTE: for SCST_ABORT_TASK called under spinlock
785          */
786         int (*task_mgmt_fn) (struct scst_mgmt_cmd *mgmt_cmd, 
787                 struct scst_tgt_dev *tgt_dev);
788
789         /* 
790          * This function can be used to export the handler's statistics and 
791          * other infos to the world outside the kernel. 
792          *
793          * OPTIONAL
794          */
795         int (*proc_info) (char *buffer, char **start, off_t offset,
796                 int length, int *eof, struct scst_dev_type *dev_type, 
797                 int inout);
798
799         struct module *module;
800
801         /* private: */
802
803         /* list entry in scst_dev_type_list */
804         struct list_head dev_type_list_entry;
805         
806         /* The pointer to the /proc directory entry */
807         struct proc_dir_entry *proc_dev_type_root;
808 };
809
810 struct scst_tgt
811 {
812         /* List of remote sessions per target, protected by scst_mutex */
813         struct list_head sess_list;
814
815         /* List entry of targets per template (tgts_list) */
816         struct list_head tgt_list_entry;
817
818         struct scst_tgt_template *tgtt; /* corresponding target template */
819
820         /* Used to wait until session finished to unregister */
821         wait_queue_head_t unreg_waitQ;
822
823         /* Device number in /proc */
824         int proc_num;
825
826         /*
827          * The following fields used to store and retry cmds if
828          * target's internal queue is full, so the target is unable to accept
829          * the cmd returning QUEUE FULL
830          */
831         atomic_t finished_cmds;
832         int retry_cmds;         /* protected by tgt_lock */
833         spinlock_t tgt_lock;
834         struct list_head retry_cmd_list; /* protected by tgt_lock */
835         struct timer_list retry_timer;
836         int retry_timer_active;
837
838         /* Maximum SG table size */
839         int sg_tablesize;
840
841         /* Used for storage of target specific stuff */
842         void *tgt_specific;
843 };
844
845 struct scst_session
846 {
847         /* Initialization phase, one of SCST_SESS_IPH_* constants */
848         int init_phase;
849
850         atomic_t refcnt;                /* get/put counter */
851
852         /* Alive commands for this session. Serialized by scst_list_lock */
853         int sess_cmd_count;             
854
855         /************************************************************* 
856          ** Session's flags. Serialized by scst_list_lock
857          *************************************************************/
858
859         /* Set if the session is shutting down */
860         unsigned int shutting_down:1;
861
862         /* Set if the session is waiting in suspended state */
863         unsigned int waiting:1;
864
865         /**************************************************************/
866
867         /*
868          * List of tgt_dev's for this session, protected by scst_mutex
869          * and suspended activity
870          */
871         struct list_head sess_tgt_dev_list;
872
873         /* Access control for this session and list entry there */
874         struct scst_acg *acg;
875
876         /* List entry for the sessions list inside ACG */
877         struct list_head acg_sess_list_entry;
878
879         /* Used for storage of target specific stuff */
880         void *tgt_specific;
881
882         /* 
883          * List of cmds in this session. Used to find a cmd in the
884          * session. Protected by scst_list_lock.
885          *
886          * ToDo: make it protected by own lock.
887          */
888         struct list_head search_cmd_list;
889         
890         struct scst_tgt *tgt;   /* corresponding target */
891
892         /*
893          * List entry for the list that keeps all sessions, which were
894          * stopped due to device block
895          */
896         struct list_head dev_wait_sess_list_entry;
897
898         /* Name of attached initiator */
899         const char *initiator_name;
900
901         /* Used if scst_unregister_session() called in wait mode */
902         struct semaphore *shutdown_mutex;
903         
904         /* List entry of sessions per target */
905         struct list_head sess_list_entry;
906
907         /* List entry for the list that keeps session, waiting for the init */
908         struct list_head sess_mgmt_list_entry;
909
910         /* 
911          * Lists of deffered during session initialization commands.
912          * Protected by scst_list_lock.
913          */
914         struct list_head init_deferred_cmd_list;
915         struct list_head init_deferred_mcmd_list;
916
917         /*
918          * Functions and data for user callbacks from scst_register_session()
919          * and scst_unregister_session()
920          */
921         void *reg_sess_data;
922         void (*init_result_fn) (struct scst_session *sess, void *data,
923                                 int result);
924         void (*unreg_done_fn) (struct scst_session *sess);
925 };
926
927 enum scst_cmd_queue_type
928 {
929         SCST_CMD_QUEUE_UNTAGGED = 0,
930         SCST_CMD_QUEUE_SIMPLE,
931         SCST_CMD_QUEUE_ORDERED,
932         SCST_CMD_QUEUE_HEAD_OF_QUEUE,
933         SCST_CMD_QUEUE_ACA
934 };
935
936 struct scst_cmd
937 {
938         /* List entry for global *_cmd_list */
939         struct list_head cmd_list_entry;
940
941         struct scst_session *sess;      /* corresponding session */
942
943         /* Cmd state, one of SCST_CMD_STATE_* constants */
944         int state;
945
946         /*************************************************************
947          ** Cmd's flags 
948          *************************************************************/
949         /* 
950          * Set if expected_sn was incremented, i.e. cmd was sent to 
951          * SCSI mid-level for execution
952          */
953         unsigned int sent_to_midlev:1;
954
955         /* Set if the cmd's action is completed */
956         unsigned int completed:1;
957
958         /* Set if we should ignore Unit Attention in scst_check_sense() */
959         unsigned int ua_ignore:1;
960
961         /* Set if cmd is being processed in atomic context */
962         unsigned int atomic:1;
963
964         /* Set if cmd must be processed only in non-atomic context */
965         unsigned int non_atomic_only:1;
966
967         /* Set if cmd is internally generated */
968         unsigned int internal:1;
969
970         /* Set if cmd is being retried */
971         unsigned int retry:1;
972
973         /* Set if the device should be unblock after cmd's finish */
974         unsigned int blocking:1;
975
976         /*
977          * Set if the target driver wants to alloc data buffers on its own.
978          * In this case alloc_data_buf() must be provided in the target driver
979          * template.
980          */
981         unsigned int data_buf_tgt_alloc:1;
982
983         /*
984          * Set by SCST if the custom data buffer allocation by the target driver
985          * succeeded.
986          */
987         unsigned int data_buf_alloced:1;
988
989         /* Set if the target driver called scst_set_expected() */
990         unsigned int expected_values_set:1;
991
992         /*
993          * Set if the cmd is being processed from the thread/tasklet,
994          * i.e. if another cmd is moved to the active list during processing
995          * of the current one, then another cmd will be processed after
996          * the current. Helps to save some context switches.
997          */
998         unsigned int processible_env:1;
999
1000         /*
1001          * Set if the cmd was delayed by task management debugging code.
1002          * Used only if DEBUG_TM is on.
1003          */
1004         unsigned int tm_dbg_delayed:1;
1005
1006         /*
1007          * Set if the cmd must be ignored by task management debugging code.
1008          * Used only if DEBUG_TM is on.
1009          */
1010         unsigned int tm_dbg_immut:1;
1011
1012         /*
1013          * Set if the SG buffer was modified by scst_set_resp_data_len()
1014          */
1015         unsigned int sg_buff_modified:1;
1016
1017         /**************************************************************/
1018
1019         unsigned long cmd_flags;        /* cmd's async flags */
1020
1021         struct scst_tgt_template *tgtt; /* to save extra dereferences */
1022         struct scst_tgt *tgt;           /* to save extra dereferences */
1023         struct scst_device *dev;        /* to save extra dereferences */
1024
1025         lun_t lun;              /* LUN for this cmd */
1026
1027         struct scst_tgt_dev *tgt_dev; /* corresponding device for this cmd */
1028
1029         struct scsi_request *scsi_req;  /* SCSI request */
1030
1031         /* List entry for tgt_dev's SN related lists */
1032         struct list_head sn_cmd_list_entry;
1033
1034         /* Cmd's serial number, used to execute cmd's in order of arrival */
1035         unsigned int sn;
1036
1037         /* List entry for session's search_cmd_list */
1038         struct list_head search_cmd_list_entry;
1039
1040         /* 
1041          * Used to found the cmd by scst_find_cmd_by_tag(). Set by the
1042          * target driver on the cmd's initialization time
1043          */
1044         uint32_t tag;
1045
1046         /* CDB and its len */
1047         uint8_t cdb[MAX_COMMAND_SIZE];
1048         int cdb_len;
1049
1050         enum scst_cmd_queue_type queue_type;
1051
1052         int timeout;    /* CDB execution timeout */
1053         int retries;    /* Amount of retries that will be done by SCSI mid-level */
1054
1055         /* SCSI data direction, one of SCST_DATA_* constants */
1056         scst_data_direction data_direction;
1057         
1058         /* Remote initiator supplied values, if any */
1059         scst_data_direction expected_data_direction;
1060         unsigned int expected_transfer_len;
1061
1062         /* cmd data length */
1063         size_t data_len;
1064
1065         /* Completition routine */
1066         void (*scst_cmd_done) (struct scst_cmd *cmd, int next_state);
1067
1068         struct sgv_pool_obj *sgv;       /* sgv object */
1069
1070         size_t bufflen;                 /* cmd buffer length */
1071         struct scatterlist *sg;         /* cmd data buffer SG vector */
1072         int sg_cnt;                     /* SG segments count */
1073         
1074         /* scst_get_sg_buf_[first,next]() support */
1075         int get_sg_buf_entry_num;
1076
1077         /*
1078          * The following two fields should be corrected by the dev_done(),
1079          * if necessary
1080          */
1081         int tgt_resp_flags;     /* response flags (SCST_TSC_FLAG_* constants) */
1082
1083         /* 
1084          * Response data length in data buffer. This field must not be set
1085          * directly, use scst_set_resp_data_len() for that
1086          */
1087         int resp_data_len;
1088
1089         uint8_t status;         /* status byte from target device */
1090         uint8_t masked_status;  /* set from host device by status_byte() */
1091         uint8_t msg_status;     /* return status from host adapter itself */
1092         uint16_t host_status;   /* set by low-level driver to indicate status */
1093         uint16_t driver_status; /* set by mid-level */
1094
1095         /* 
1096          * Used to restore the SG vector if it was modified by
1097          * scst_set_resp_data_len()
1098          */
1099         int orig_sg_cnt, orig_sg_entry, orig_entry_len;
1100
1101         uint8_t sense_buffer[SCSI_SENSE_BUFFERSIZE];    /* sense buffer */
1102
1103         /* The corresponding mgmt cmd, if any. Protected by scst_list_lock */
1104         struct scst_mgmt_cmd *mgmt_cmnd;
1105
1106         /* List entry for dev's blocked_cmd_list */
1107         struct list_head blocked_cmd_list_entry;
1108
1109         /*
1110          * Fileio private fields
1111          */
1112         struct list_head fileio_cmd_list_entry;
1113         int fileio_in_list;
1114
1115         /* Used for storage of target specific stuff */
1116         void *tgt_specific;
1117
1118         /* Used for storage of dev handler specific stuff */
1119         void *tgt_dev_specific;
1120
1121         /* 
1122          * Used to store previous tgt_dev if dev handler returns 
1123          * SCST_CMD_STATE_REINIT state
1124          */
1125         struct scst_tgt_dev *tgt_dev_saved;
1126
1127         struct scst_cmd *orig_cmd; /* Used to issue REQUEST SENSE */
1128 };
1129
1130 struct scst_mgmt_cmd
1131 {
1132         /* List entry for *_mgmt_cmd_list */
1133         struct list_head mgmt_cmd_list_entry;
1134
1135         struct scst_session *sess;
1136
1137         /* Mgmt cmd state, one of SCST_MGMT_CMD_STATE_* constants */
1138         int state;
1139
1140         int fn;
1141
1142         unsigned int completed:1;       /* set, if the mcmd is completed */
1143
1144         /* Number of commands to complete before sending response */
1145         int cmd_wait_count;
1146
1147         /* Number of completed commands */
1148         int completed_cmd_count;
1149
1150         lun_t lun;      /* LUN for this mgmt cmd */
1151         /* or */
1152         uint32_t tag;   /* tag of the corresponding cmd */
1153
1154         /* corresponding cmd (to be aborted, found by tag) */
1155         struct scst_cmd *cmd_to_abort;
1156
1157         /* corresponding device for this mgmt cmd (found by lun) */
1158         struct scst_tgt_dev *mcmd_tgt_dev;
1159
1160         /* completition status, one of the SCST_MGMT_STATUS_* constants */
1161         int status;
1162
1163         /* Used for storage of target specific stuff */
1164         void *tgt_specific;
1165 };
1166
1167 struct scst_device
1168 {
1169         struct scst_dev_type *handler;  /* corresponding dev handler */
1170
1171         /* Used to translate SCSI's cmd to SCST's cmd */
1172         struct gendisk *rq_disk;
1173
1174         /*************************************************************
1175          ** Dev's flags. Updates serialized by dev_lock or suspended
1176          ** activity
1177          *************************************************************/
1178
1179         /* Set if dev is RESERVED */
1180         unsigned int dev_reserved:1;
1181
1182         /* Set if dev accepts only one command at time  */
1183         unsigned int dev_serialized:1;
1184
1185         /* Set if double reset UA is possible */
1186         unsigned int dev_double_ua_possible:1;
1187
1188         /* Set if reset UA sent (to avoid double reset UAs) */
1189         unsigned int dev_reset_ua_sent:1;
1190
1191         /**************************************************************/
1192
1193         spinlock_t dev_lock;            /* device lock */
1194
1195         /* 
1196          * How many times device was blocked for new cmds execution.
1197          * Protected by dev_lock
1198          */
1199         int block_count;
1200
1201         /* 
1202          * How many there are "on_dev" commands, i.e. ones those are being
1203          * executed by the underlying SCSI/virtual device.
1204          */
1205         atomic_t on_dev_count;
1206
1207         struct list_head blocked_cmd_list; /* protected by dev_lock */
1208         
1209         /* Corresponding real SCSI device, could be NULL for virtual devices */
1210         struct scsi_device *scsi_dev;
1211         
1212         /* Used for storage of dev handler specific stuff */
1213         void *tgt_dev_specific;
1214
1215         /* Used to wait for requested amount of "on_dev" commands */
1216         wait_queue_head_t on_dev_waitQ;
1217
1218         /* A list entry used during RESETs, protected by scst_mutex */
1219         struct list_head reset_dev_list_entry;
1220
1221         /* Virtual device internal ID */
1222         int virt_id;
1223         
1224         /* Pointer to virtual device name, for convenience only */
1225         const char *virt_name;
1226         
1227         /* List entry in global devices list */
1228         struct list_head dev_list_entry;
1229         
1230         /*
1231          * List of tgt_dev's, one per session, protected by scst_mutex and
1232          * suspended activity
1233          */
1234         struct list_head dev_tgt_dev_list;
1235         
1236         /* List of acg_dev's, one per acg, protected by scst_mutex */
1237         struct list_head dev_acg_dev_list;
1238 };
1239
1240 /* 
1241  * Used to store per-session specific device information
1242  */
1243 struct scst_tgt_dev
1244 {
1245         /* List entry in sess->sess_tgt_dev_list */
1246         struct list_head sess_tgt_dev_list_entry;
1247         
1248         struct scst_acg_dev *acg_dev;   /* corresponding acg_dev */
1249
1250         /* 
1251          * How many cmds alive on this dev in this session.
1252          * Protected by scst_list_lock.
1253          */
1254         int cmd_count; 
1255
1256         /* Throttled commands, protected by scst_list_lock */
1257         struct list_head thr_cmd_list;
1258
1259         spinlock_t tgt_dev_lock;        /* per-session device lock */
1260
1261         /* List of UA's for this device, protected by tgt_dev_lock */
1262         struct list_head UA_list;
1263
1264         unsigned long tgt_dev_flags;    /* tgt_dev's flags */
1265         
1266         /* Used for storage of dev handler specific stuff */
1267         void *tgt_dev_specific;
1268
1269         /* 
1270          * Used to execute cmd's in order of arrival.
1271          *
1272          * Protected by sn_lock, except next_sn and expected_sn.
1273          * Expected_sn protected by itself, since only one thread, which
1274          * processes SN matching command, can increment it at any time.
1275          * Next_sn must be the same type as expected_sn to overflow
1276          * simultaneously.
1277          */
1278         int next_sn; /* protected by scst_list_lock */
1279         int expected_sn;
1280         spinlock_t sn_lock;
1281         int def_cmd_count;
1282         struct list_head deferred_cmd_list;
1283         struct list_head skipped_sn_list;
1284         
1285         struct scst_session *sess;      /* corresponding session */
1286         
1287         /* list entry in dev->dev_tgt_dev_list */
1288         struct list_head dev_tgt_dev_list_entry;
1289         
1290         /* internal tmp list entry */
1291         struct list_head extra_tgt_dev_list_entry;
1292 };
1293
1294 /*
1295  * Used to store ACG-specific device information, like LUN
1296  */
1297 struct scst_acg_dev
1298 {
1299         struct scst_device *dev; /* corresponding device */
1300         lun_t lun;              /* device's LUN in this acg */
1301         unsigned int rd_only_flag:1; /* if != 0, then read only */
1302         struct scst_acg *acg;   /* parent acg */
1303         
1304         /* list entry in dev->dev_acg_dev_list */
1305         struct list_head dev_acg_dev_list_entry;
1306         
1307         /* list entry in acg->acg_dev_list */
1308         struct list_head acg_dev_list_entry;
1309 };
1310
1311 /*
1312  * ACG - access control group. Used to store group related
1313  * control information.
1314  */
1315 struct scst_acg
1316 {
1317         /* List of acg_dev's in this acg, protected by scst_mutex */
1318         struct list_head acg_dev_list;
1319
1320         /* List of attached sessions, protected by scst_mutex */
1321         struct list_head acg_sess_list;
1322
1323         /* List of attached acn's, protected by scst_mutex */
1324         struct list_head acn_list;
1325
1326         /* List entry in scst_acg_list */
1327         struct list_head scst_acg_list_entry;
1328
1329         /* Name of this acg */
1330         const char *acg_name;
1331
1332         /* The pointer to the /proc directory entry */
1333         struct proc_dir_entry *acg_proc_root;
1334 };
1335
1336 /*
1337  * ACN - access control name. Used to store names, by which
1338  * incoming sessions will be assigned to appropriate ACG.
1339  */
1340 struct scst_acn
1341 {
1342         /* Initiator's name */
1343         const char *name;
1344         /* List entry in acg->acn_list */
1345         struct list_head acn_list_entry;
1346 };
1347
1348 /* 
1349  * Used to store per-session UNIT ATTENTIONs
1350  */
1351 struct scst_tgt_dev_UA
1352 {
1353         /* List entry in tgt_dev->UA_list */
1354         struct list_head UA_list_entry;
1355         /* Unit Attention sense */
1356         uint8_t UA_sense_buffer[SCSI_SENSE_BUFFERSIZE];
1357 };
1358
1359 enum scst_cdb_flags
1360 {
1361         SCST_TRANSFER_LEN_TYPE_FIXED = 0x01, /* must be equviv 1 (FIXED_BIT in cdb) */
1362         SCST_SMALL_TIMEOUT = 0x02,
1363         SCST_LONG_TIMEOUT = 0x04,
1364         SCST_UNKNOWN_LENGTH = 0x08,
1365 };
1366
1367 struct scst_info_cdb
1368 {
1369         enum scst_cdb_flags flags;
1370         scst_data_direction direction;
1371         unsigned int transfer_len;
1372         unsigned short cdb_len;
1373         const char *op_name;
1374 };
1375
1376 /*
1377  * Sense data for the appropriate errors. Can be used with
1378  * scst_set_cmd_error()
1379  */
1380 #define scst_sense_no_sense                     NO_SENSE,        0x00, 0
1381 #define scst_sense_hardw_error                  HARDWARE_ERROR,  0x44, 0
1382 #define scst_sense_aborted_command              ABORTED_COMMAND, 0x00, 0
1383 #define scst_sense_invalid_opcode               ILLEGAL_REQUEST, 0x20, 0
1384 #define scst_sense_invalid_field_in_cdb         ILLEGAL_REQUEST, 0x24, 0
1385 #define scst_sense_invalid_field_in_parm_list   ILLEGAL_REQUEST, 0x26, 0
1386 #define scst_sense_reset_UA                     UNIT_ATTENTION,  0x29, 0
1387 #define scst_sense_nexus_loss_UA                UNIT_ATTENTION,  0x29, 0x7
1388 #define scst_sense_saving_params_unsup          ILLEGAL_REQUEST, 0x39, 0
1389 #define scst_sense_lun_not_supported            ILLEGAL_REQUEST, 0x25, 0
1390 #define scst_sense_data_protect                 DATA_PROTECT,    0x00, 0
1391 #define scst_sense_miscompare_error             MISCOMPARE,      0x1D, 0
1392 #define scst_sense_block_out_range_error        ILLEGAL_REQUEST, 0x21, 0
1393 #define scst_sense_medium_changed_UA            UNIT_ATTENTION,  0x28, 0
1394
1395 #ifndef smp_mb__after_set_bit
1396 /* There is no smp_mb__after_set_bit() in the kernel */
1397 #define smp_mb__after_set_bit()                 smp_mb();
1398 #endif
1399
1400 /* 
1401  * Registers target template
1402  * Returns 0 on success or appropriate error code otherwise
1403  */
1404 int scst_register_target_template(struct scst_tgt_template *vtt);
1405
1406 /* 
1407  * Unregisters target template
1408  */
1409 void scst_unregister_target_template(struct scst_tgt_template *vtt);
1410
1411 /* 
1412  * Registers and returns target adapter
1413  * Returns new target structure on success or NULL otherwise
1414  */
1415 struct scst_tgt *scst_register(struct scst_tgt_template *vtt);
1416
1417 /* 
1418  * Unregisters target adapter
1419  */
1420 void scst_unregister(struct scst_tgt *tgt);
1421
1422 /* 
1423  * Registers and returns a session
1424  *
1425  * Returns new session on success or NULL otherwise
1426  *
1427  * Parameters:
1428  *   tgt    - target
1429  *   atomic - true, if the function called in the atomic context
1430  *   initiator_name - remote initiator's name, any NULL-terminated string,
1431  *      e.g. iSCSI name, which used as the key to found appropriate access
1432  *      control group. Could be NULL, then "default" group is used. 
1433  *      The groups are set up via /proc interface.
1434  *   data - any target driver supplied data
1435  *   result_fn - pointer to the function that will be 
1436  *      asynchronously called when session initialization finishes.
1437  *      Can be NULL. Parameters:
1438  *       - sess - session
1439  *       - data - target driver supplied to scst_register_session() data
1440  *       - result - session initialization result, 0 on success or 
1441  *                  appropriate error code otherwise
1442  *
1443  * Note: A session creation and initialization is a complex task, 
1444  *       which requires sleeping state, so it can't be fully done
1445  *       in interrupt context. Therefore the "bottom half" of it, if
1446  *       scst_register_session() is called from atomic context, will be
1447  *       done in SCST thread context. In this case scst_register_session()
1448  *       will return not completely initialized session, but the target
1449  *       driver can supply commands to this session via scst_rx_cmd().
1450  *       Those commands processing will be delayed inside SCST until
1451  *       the session initialization is finished, then their processing
1452  *       will be restarted. The target driver will be notified about
1453  *       finish of the session initialization by function result_fn(). 
1454  *       On success the target driver could do nothing, but if the
1455  *       initialization fails, the target driver must ensure that
1456  *       no more new commands being sent or will be sent to SCST after
1457  *       result_fn() returns. All already sent to SCST commands for
1458  *       failed session will be returned in xmit_response() with BUSY status.
1459  *       In case of failure the driver shall call scst_unregister_session()
1460  *       inside result_fn(), it will NOT be called automatically.
1461  */
1462 struct scst_session *scst_register_session(struct scst_tgt *tgt, int atomic,
1463         const char *initiator_name, void *data,
1464         void (*result_fn) (struct scst_session *sess, void *data, int result));
1465
1466 /* 
1467  * Unregisters a session.
1468  * Parameters:
1469  *   sess - session to be unregistered
1470  *   wait - if true, instructs to wait until all commands, which
1471  *      currently is being executed and belonged to the session, finished.
1472  *      Otherwise, target driver should be prepared to receive
1473  *      xmit_response() for the session's command after 
1474  *      scst_unregister_session() returns.
1475  *   unreg_done_fn - pointer to the function that will be 
1476  *      asynchronously called when the last session's command finishes and
1477  *      the session is about to be completely freed. Can be NULL. 
1478  *      Parameter:
1479  *       - sess - session
1480  *
1481  * Note: All outstanding commands will be finished regularly. After
1482  *       scst_unregister_session() returned no new commands must be sent to
1483  *       SCST via scst_rx_cmd(). Also, the caller must ensure that no
1484  *       scst_rx_cmd() or scst_rx_mgmt_fn_*() is called in paralell with
1485  *       scst_unregister_session().
1486  *       Can be called before result_fn() of scst_register_session() called,
1487  *       i.e. during the session registration/initialization.
1488  */
1489 void scst_unregister_session(struct scst_session *sess, int wait,
1490         void (*unreg_done_fn) (struct scst_session *sess));
1491
1492 /* 
1493  * Registers dev handler driver
1494  * Returns 0 on success or appropriate error code otherwise
1495  */
1496 int scst_register_dev_driver(struct scst_dev_type *dev_type);
1497
1498 /* 
1499  * Unregisters dev handler driver
1500  */
1501 void scst_unregister_dev_driver(struct scst_dev_type *dev_type);
1502
1503 /* 
1504  * Registers dev handler driver for virtual devices (eg FILEIO)
1505  * Returns 0 on success or appropriate error code otherwise
1506  */
1507 int scst_register_virtual_dev_driver(struct scst_dev_type *dev_type);
1508
1509 /* 
1510  * Unregisters dev handler driver for virtual devices
1511  */
1512 void scst_unregister_virtual_dev_driver(struct scst_dev_type *dev_type);
1513
1514 /* 
1515  * Creates and sends new command to SCST.
1516  * Must not been called in parallel with scst_unregister_session() for the
1517  * same sess. Returns the command on success or NULL otherwise
1518  */
1519 struct scst_cmd *scst_rx_cmd(struct scst_session *sess,
1520                              const uint8_t *lun, int lun_len,
1521                              const uint8_t *cdb, int cdb_len, int atomic);
1522
1523 /* 
1524  * Notifies SCST that the driver finished its part of the command 
1525  * initialization, and the command is ready for execution.
1526  * The second argument sets preferred command execition context. 
1527  * See SCST_CONTEXT_* constants for details
1528  */
1529 void scst_cmd_init_done(struct scst_cmd *cmd, int pref_context);
1530
1531 /* 
1532  * Notifies SCST that the driver received all the necessary data 
1533  * and the command is ready for further processing.
1534  * The second argument sets data receiving completion status
1535  * (see SCST_RX_STATUS_* constants for details)
1536  * The third argument sets preferred command execition context
1537  * (see SCST_CONTEXT_* constants for details)
1538  */
1539 void scst_rx_data(struct scst_cmd *cmd, int status, int pref_context);
1540
1541 /* 
1542  * Notifies SCST that the driver sent the response and the command
1543  * can be freed now.
1544  */
1545 void scst_tgt_cmd_done(struct scst_cmd *cmd);
1546
1547 /* 
1548  * Creates new management command using tag and sends it for execution.
1549  * Can be used for SCST_ABORT_TASK only.
1550  * Must not been called in parallel with scst_unregister_session() for the 
1551  * same sess. Returns 0 for success, error code otherwise.
1552  */
1553 int scst_rx_mgmt_fn_tag(struct scst_session *sess, int fn, uint32_t tag,
1554                        int atomic, void *tgt_specific);
1555
1556 /* 
1557  * Creates new management command using LUN and sends it for execution.
1558  * Currently can be used for any fn, except SCST_ABORT_TASK.
1559  * Must not been called in parallel with scst_unregister_session() for the 
1560  * same sess. Returns 0 for success, error code otherwise.
1561  */
1562 int scst_rx_mgmt_fn_lun(struct scst_session *sess, int fn,
1563                         const uint8_t *lun, int lun_len,
1564                         int atomic, void *tgt_specific);
1565
1566 /*
1567  * Provides various CDB info
1568  * Parameters:
1569  *   cdb_p - pointer to CDB
1570  *   dev_type - SCSI device type
1571  *   info_p - the result structure (output)
1572  * Returns 0 on success, -1 otherwise
1573  */
1574 int scst_get_cdb_info(const uint8_t *cdb_p, int dev_type,
1575                       struct scst_info_cdb *info_p);
1576
1577 /* 
1578  * Set error SCSI status in the command and prepares it for returning it
1579  */
1580 void scst_set_cmd_error_status(struct scst_cmd *cmd, int status);
1581
1582 /* 
1583  * Set error in the command and fill the sense buffer
1584  */
1585 void scst_set_cmd_error(struct scst_cmd *cmd, int key, int asc, int ascq);
1586
1587 /* 
1588  * Sets BUSY or TASK QUEUE FULL status
1589  */
1590 void scst_set_busy(struct scst_cmd *cmd);
1591
1592 /* 
1593  * Finds a command based on the supplied tag comparing it with one
1594  * that previously set by scst_cmd_set_tag(). 
1595  * Returns the command on success or NULL otherwise
1596  */
1597 struct scst_cmd *scst_find_cmd_by_tag(struct scst_session *sess, uint32_t tag);
1598
1599 /* 
1600  * Finds a command based on user supplied data and comparision
1601  * callback function, that should return true, if the command is found.
1602  * Returns the command on success or NULL otherwise
1603  */
1604 struct scst_cmd *scst_find_cmd(struct scst_session *sess, void *data,
1605                                int (*cmp_fn) (struct scst_cmd *cmd,
1606                                               void *data));
1607
1608 /*
1609  * Translates SCST's data direction to DMA one
1610  */
1611 static inline int scst_to_dma_dir(int scst_dir)
1612 {
1613         return scst_dir;
1614 }
1615
1616 /*
1617  * Translates SCST data direction to DMA one from the perspective
1618  * of the target device.
1619  */
1620 static inline int scst_to_tgt_dma_dir(int scst_dir)
1621 {
1622         if (scst_dir == SCST_DATA_WRITE)
1623                 return DMA_FROM_DEVICE;
1624         else if (scst_dir == SCST_DATA_READ)
1625                 return DMA_TO_DEVICE;
1626         return scst_dir;
1627 }
1628
1629 /*
1630  * Registers a virtual device.
1631  * Parameters:
1632  *   dev_type - the device's device handler
1633  *   dev_name - the new device name, NULL-terminated string. Must be uniq
1634  *              among all virtual devices in the system. The value isn't
1635  *              copied, only the reference is stored, so the value must
1636  *              remain valid during the device lifetime.
1637  * Returns assinged to the device ID on success, or negative value otherwise
1638  */
1639 int scst_register_virtual_device(struct scst_dev_type *dev_handler, 
1640         const char *dev_name);
1641
1642 /*
1643  * Unegisters a virtual device.
1644  * Parameters:
1645  *   id - the device's ID, returned by the registration function
1646  */
1647 void scst_unregister_virtual_device(int id);
1648
1649 /*
1650  * Get/Set functions for tgt's target specific data
1651  */
1652 static inline void *scst_tgt_get_tgt_specific(struct scst_tgt *tgt)
1653 {
1654         return tgt->tgt_specific;
1655 }
1656
1657 static inline void scst_tgt_set_tgt_specific(struct scst_tgt *tgt, void *val)
1658 {
1659         tgt->tgt_specific = val;
1660 }
1661
1662 /*
1663  * Get/Set functions for session's target specific data
1664  */
1665 static inline void *scst_sess_get_tgt_specific(struct scst_session *sess)
1666 {
1667         return sess->tgt_specific;
1668 }
1669
1670 static inline void scst_sess_set_tgt_specific(struct scst_session *sess,
1671                                               void *val)
1672 {
1673         sess->tgt_specific = val;
1674 }
1675
1676 /* Returns TRUE if cmd is being executed in atomic context */
1677 static inline int scst_cmd_atomic(struct scst_cmd *cmd)
1678 {
1679         int res = cmd->atomic;
1680 #ifdef EXTRACHECKS
1681         if (unlikely(in_atomic() && !res)) {
1682                 printk(KERN_ERR "ERROR: in_atomic() and non-atomic cmd\n");
1683                 dump_stack();
1684                 cmd->atomic = 1;
1685                 res = 1;
1686         }
1687 #endif
1688         return res;
1689 }
1690
1691 /* Returns cmd's session */
1692 static inline struct scst_session *scst_cmd_get_session(struct scst_cmd *cmd)
1693 {
1694         return cmd->sess;
1695 }
1696
1697 /* Returns cmd's response data length */
1698 static inline int scst_cmd_get_resp_data_len(struct scst_cmd *cmd)
1699 {
1700         return cmd->resp_data_len;
1701 }
1702
1703 /* Returns cmd's response flags (SCST_TSC_FLAG_* constants) */
1704 static inline int scst_cmd_get_tgt_resp_flags(struct scst_cmd *cmd)
1705 {
1706         return cmd->tgt_resp_flags;
1707 }
1708
1709 /*
1710  * Returns pointer to cmd's SG data buffer.
1711  *
1712  * Usage of this function is not recommended, use scst_get_buf_*()
1713  * family of functions instead.
1714  */
1715 static inline struct scatterlist *scst_cmd_get_sg(struct scst_cmd *cmd)
1716 {
1717         return cmd->sg;
1718 }
1719
1720 /*
1721  * Returns cmd's data buffer length.
1722  *
1723  * In case if you need to iterate over data in the buffer, usage of
1724  * this function is not recommended, use scst_get_buf_*()
1725  * family of functions instead.
1726  */
1727 static inline unsigned int scst_cmd_get_bufflen(struct scst_cmd *cmd)
1728 {
1729         return cmd->bufflen;
1730 }
1731
1732 /* 
1733  * Returns cmd's sg_cnt.
1734  *
1735  * Usage of this function is not recommended, use scst_get_buf_*()
1736  * family of functions instead.
1737  */
1738 static inline unsigned short scst_cmd_get_sg_cnt(struct scst_cmd *cmd)
1739 {
1740         return cmd->sg_cnt;
1741 }
1742
1743 /* Returns cmd's data direction */
1744 static inline scst_data_direction scst_cmd_get_data_direction(
1745         struct scst_cmd *cmd)
1746 {
1747         return cmd->data_direction;
1748 }
1749
1750 /* Returns cmd's relative data offset */
1751 static inline unsigned int scst_cmd_get_offset(struct scst_cmd *cmd)
1752 {
1753         return 0;
1754 }
1755
1756 /* Returns cmd's status byte from host device */
1757 static inline uint8_t scst_cmd_get_status(struct scst_cmd *cmd)
1758 {
1759         return cmd->status;
1760 }
1761
1762 /* Returns cmd's status byte set from host device by status_byte() */
1763 static inline uint8_t scst_cmd_get_masked_status(struct scst_cmd *cmd)
1764 {
1765         return cmd->masked_status;
1766 }
1767
1768 /* Returns cmd's status from host adapter itself */
1769 static inline uint8_t scst_cmd_get_msg_status(struct scst_cmd *cmd)
1770 {
1771         return cmd->msg_status;
1772 }
1773
1774 /* Returns cmd's status set by low-level driver to indicate its status */
1775 static inline uint16_t scst_cmd_get_host_status(struct scst_cmd *cmd)
1776 {
1777         return cmd->host_status;
1778 }
1779
1780 /* Returns cmd's status set by SCSI mid-level */
1781 static inline uint16_t scst_cmd_get_driver_status(struct scst_cmd *cmd)
1782 {
1783         return cmd->driver_status;
1784 }
1785
1786 /* Returns pointer to cmd's sense buffer */
1787 static inline uint8_t *scst_cmd_get_sense_buffer(struct scst_cmd *cmd)
1788 {
1789         return cmd->sense_buffer;
1790 }
1791
1792 /* Returns cmd's sense buffer length */
1793 static inline int scst_cmd_get_sense_buffer_len(struct scst_cmd *cmd)
1794 {
1795         return sizeof(cmd->sense_buffer);
1796 }
1797
1798 /*
1799  * Get/Set functions for cmd's target SN
1800  */
1801 static inline uint32_t scst_cmd_get_tag(struct scst_cmd *cmd)
1802 {
1803         return cmd->tag;
1804 }
1805
1806 static inline void scst_cmd_set_tag(struct scst_cmd *cmd, uint32_t tag)
1807 {
1808         cmd->tag = tag;
1809 }
1810
1811 /*
1812  * Get/Set functions for cmd's target specific data.
1813  * Variant with *_lock must be used if target driver uses
1814  * scst_find_cmd() to avoid race with it, except inside scst_find_cmd()'s
1815  * callback, where lock is already taken.
1816  */
1817 static inline void *scst_cmd_get_tgt_specific(struct scst_cmd *cmd)
1818 {
1819         return cmd->tgt_specific;
1820 }
1821
1822 static inline void scst_cmd_set_tgt_specific(struct scst_cmd *cmd, void *val)
1823 {
1824         cmd->tgt_specific = val;
1825 }
1826
1827 void *scst_cmd_get_tgt_specific_lock(struct scst_cmd *cmd);
1828 void scst_cmd_set_tgt_specific_lock(struct scst_cmd *cmd, void *val);
1829
1830 /*
1831  * Get/Set functions for data_buf_tgt_alloc flag
1832  */
1833 static inline int scst_cmd_get_data_buf_tgt_alloc(struct scst_cmd *cmd)
1834 {
1835         return cmd->data_buf_tgt_alloc;
1836 }
1837
1838 static inline void scst_cmd_set_data_buf_tgt_alloc(struct scst_cmd *cmd)
1839 {
1840         cmd->data_buf_tgt_alloc = 1;
1841 }
1842
1843 /*
1844  * Get/Set functions for data_buf_alloced flag
1845  */
1846 static inline int scst_cmd_get_data_buff_alloced(struct scst_cmd *cmd)
1847 {
1848         return cmd->data_buf_alloced;
1849 }
1850
1851 static inline void scst_cmd_set_data_buff_alloced(struct scst_cmd *cmd)
1852 {
1853         cmd->data_buf_alloced = 1;
1854 }
1855
1856 /*
1857  * Returns 1 if the cmd was aborted, so its status is invalid and no
1858  * reply shall be sent to the remote initiator. A target driver should
1859  * only clear internal resources, associated with cmd.
1860  */
1861 static inline int scst_cmd_aborted(struct scst_cmd *cmd)
1862 {
1863         return test_bit(SCST_CMD_ABORTED, &cmd->cmd_flags) &&
1864                 !test_bit(SCST_CMD_ABORTED_OTHER, &cmd->cmd_flags);
1865 }
1866
1867 /*
1868  * Get/Set functions for expected data direction, transfer length
1869  * and its validity flag
1870  */
1871 static inline int scst_cmd_is_expected_set(struct scst_cmd *cmd)
1872 {
1873         return cmd->expected_values_set;
1874 }
1875  
1876 static inline scst_data_direction scst_cmd_get_expected_data_direction(
1877         struct scst_cmd *cmd)
1878 {
1879         return cmd->expected_data_direction;
1880 }
1881
1882 static inline unsigned int scst_cmd_get_expected_transfer_len(
1883         struct scst_cmd *cmd)
1884 {
1885         return cmd->expected_transfer_len;
1886 }
1887
1888 static inline void scst_cmd_set_expected(struct scst_cmd *cmd,
1889         scst_data_direction expected_data_direction,
1890         unsigned int expected_transfer_len)
1891 {
1892         cmd->expected_data_direction = expected_data_direction;
1893         cmd->expected_transfer_len = expected_transfer_len;
1894         cmd->expected_values_set = 1;
1895 }
1896
1897 /*
1898  * Get/Set function for mgmt cmd's target specific data
1899  */
1900 static inline void *scst_mgmt_cmd_get_tgt_specific(struct scst_mgmt_cmd *mcmd)
1901 {
1902         return mcmd->tgt_specific;
1903 }
1904
1905 static inline void scst_mgmt_cmd_set_tgt_specific(struct scst_mgmt_cmd *mcmd,
1906         void *val)
1907 {
1908         mcmd->tgt_specific = val;
1909 }
1910
1911 /*
1912  * Returns mgmt cmd's completition status (SCST_MGMT_STATUS_* constants)
1913  */
1914 static inline int scst_mgmt_cmd_get_status(struct scst_mgmt_cmd *mcmd)
1915 {
1916         return mcmd->status;
1917 }
1918
1919 /*
1920  * Functions for access to the commands data (SG) buffer,
1921  * including HIGHMEM environment. Should be used instead of direct
1922  * access. Returns the mapped buffer length for success, 0 for EOD,
1923  * negative error code otherwise. 
1924  *
1925  * "Buf" argument returns the mapped buffer
1926  *
1927  * The "put" function unmaps the buffer.
1928  */
1929 int __scst_get_buf(struct scst_cmd *cmd, uint8_t **buf);
1930 static inline int scst_get_buf_first(struct scst_cmd *cmd, uint8_t **buf)
1931 {
1932         cmd->get_sg_buf_entry_num = 0;
1933         return __scst_get_buf(cmd, buf);
1934 }
1935
1936 static inline int scst_get_buf_next(struct scst_cmd *cmd, uint8_t **buf)
1937 {
1938         return __scst_get_buf(cmd, buf);
1939 }
1940
1941 static inline void scst_put_buf(struct scst_cmd *cmd, void *buf)
1942 {
1943 #ifdef SCST_HIGHMEM
1944         if (cmd->sg_cnt) {
1945                 if (scst_cmd_atomic(cmd)) {
1946                         enum km_type km;
1947                         BUG_ON(in_irq());
1948                         if (in_softirq())
1949                                 km = KM_SOFTIRQ0;
1950                         else
1951                                 km = KM_USER0;
1952                         kunmap_atomic(buf, km);
1953                 } else
1954                         kunmap(buf);
1955         }
1956 #endif
1957 }
1958
1959 /*
1960  * Returns approximate higher rounded buffers count that 
1961  * scst_get_buf_[first|next]() return.
1962  */
1963 static inline int scst_get_buf_count(struct scst_cmd *cmd)
1964 {
1965         int res;
1966 #ifdef SCST_HIGHMEM
1967         res = (cmd->bufflen >> PAGE_SHIFT) + 1;
1968 #else
1969         res = (cmd->sg_cnt == 0) ? 1 : cmd->sg_cnt;
1970 #endif
1971         return res;
1972 }
1973
1974 /* 
1975  * Suspends and resumes any activity. 
1976  * scst_suspend_activity() doesn't return until there are any
1977  * active commands (state after SCST_CMD_STATE_INIT). New arriving
1978  * commands stay in that state until scst_resume_activity() is called.
1979  */
1980 void scst_suspend_activity(void);
1981 void scst_resume_activity(void);
1982
1983 /* 
1984  * Returns target driver's root entry in SCST's /proc hierarchy.
1985  * The driver can create own files/directoryes here, which should
1986  * be deleted in the driver's release().
1987  */
1988 static inline struct proc_dir_entry *scst_proc_get_tgt_root(
1989         struct scst_tgt_template *vtt)
1990 {
1991         return vtt->proc_tgt_root;
1992 }
1993
1994 /* 
1995  * Returns device handler's root entry in SCST's /proc hierarchy.
1996  * The driver can create own files/directoryes here, which should
1997  * be deleted in the driver's detach()/release().
1998  */
1999 static inline struct proc_dir_entry *scst_proc_get_dev_type_root(
2000         struct scst_dev_type *dtt)
2001 {
2002         return dtt->proc_dev_type_root;
2003 }
2004
2005 /**
2006  ** Two library functions and the structure to help the drivers 
2007  ** that use scst_debug.* facilities manage "trace_level" /proc entry.
2008  ** The functions service "standard" log levels and allow to work
2009  ** with driver specific levels, which should be passed inside as
2010  ** NULL-terminated array of struct scst_proc_log's, where:
2011  **   - val - the level's numeric value
2012  **   - token - its string representation
2013  **/
2014
2015 struct scst_proc_log {
2016         unsigned int val;
2017         const char *token;
2018 };
2019
2020 int scst_proc_log_entry_read(char *buffer, char **start,
2021         off_t offset, int length, int *eof, void *data,
2022         unsigned long log_level, const struct scst_proc_log *tbl);
2023
2024 int scst_proc_log_entry_write(struct file *file, const char *buf,
2025         unsigned long length, void *data, unsigned long *log_level,
2026         unsigned long default_level, const struct scst_proc_log *tbl);
2027
2028 /*
2029  * Adds and deletes (stops) num SCST's threads. Returns 0 on success,
2030  * error code otherwise.
2031  */
2032 int scst_add_threads(int num);
2033 void scst_del_threads(int num);
2034
2035 void scst_set_cmd_error_sense(struct scst_cmd *cmd, uint8_t *sense, 
2036         unsigned int len);
2037
2038 /*
2039  * Returnes a pseudo-random number for debugging purposes. Available only with
2040  * DEBUG on
2041  */
2042 unsigned long scst_random(void);
2043
2044 /*
2045  * Sets response data length for cmd and truncates its SG vector accordingly.
2046  * The cmd->resp_data_len must not be set directly, it must be set only
2047  * using this function. Value of resp_data_len must be <= cmd->bufflen.
2048  */
2049 void scst_set_resp_data_len(struct scst_cmd *cmd, int resp_data_len);
2050
2051 #endif /* __SCST_H */