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