- SysfsRules file added
[mirror/scst/.git] / scst / SysfsRules
1                 SCST SYSFS interface rules
2                 ==========================
3
4 This file describes SYSFS interface rules, which all SCST target
5 drivers, dev handlers and management utilities MUST follow. This allows
6 to have a simple, self-documented, target drivers and dev handlers
7 independent management interface.
8
9 Words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
10 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
11 document are to be interpreted as described in RFC 2119.
12
13 In this document "key attribute" means a configuration attribute with
14 not default value, which must be configured during the target driver's
15 initialization. A key attribute MUST have in the last line keyword
16 "[key]". If a default value set to a key attribute, it becomes a regular
17 none-key attribute. For instance, iSCSI target has attribute DataDigest.
18 Default value for this attribute is "None". It value "CRC32C" is set to
19 this attribute, it will become a key attribute. If value "None" is again
20 set, this attribute will become back to a none-key attribute.
21
22 Each user configurable attribute with a not default value MUST be marked
23 as key attribute.
24
25
26 I. Rules for target drivers
27 ===========================
28
29 SCST core for each target driver (struct scst_tgt_template) creates a
30 root subdirectory in /sys/kernel/scst_tgt/targets with name
31 scst_tgt_template.name (called "target_driver_name" further in this
32 document). 
33
34 For each target (struct scst_tgt) SCST core creates a root subdirectory
35 in /sys/kernel/scst_tgt/targets/target_driver_name with name
36 scst_tgt.tgt_name (called "target_name" further in this document).
37
38 There are 2 type of targets possible: hardware and virtual targets.
39 Hardware targets are targets corresponding to real hardware, for
40 instance, a Fibre Channel adapter's port. Virtual targets are hardware
41 independent targets, which can be dynamically added or removed, for
42 instance, an iSCSI target, or NPIV Fibre Channel target.
43
44 A target driver supporting virtual targets must support "mgmt" attribute
45 and "add_target"/"del_target" commands.
46
47 If target driver supports both hardware and virtual targets (for
48 instance, an FC adapter supporting NPIV, which has hardware targets for
49 its physical ports as well as virtual NPIV targets), it MUST create each
50 hardware target with hw_target mark to make SCST core create "hw_target"
51 attribute (see below).
52
53 Attributes for target drivers
54 -----------------------------
55
56 A target driver MAY support in its root subdirectory the following
57 optional attributes. Target drivers MAY also support there other
58 read-only or read-writable attributes.
59
60 1. "enabled" - this attribute MUST allow to enable and disable target
61 driver as a whole, i.e. if disabled, the target driver MUST NOT accept
62 new connections. The goal of this attribute is to allow the target
63 driver's initial configuration. For instance, iSCSI target may need to
64 have discovery user names and passwords set before it starts serving
65 discovery connections.
66
67 This attribute MUST have read and write permissions for superuser and be
68 read-only for other users.
69
70 On read it MUST return 0, if the target driver is disabled, and 1, if it
71 is enabled.
72
73 On write it MUST accept '0' character as request to disable and '1' as
74 request to enable, but MAY also accept other driver specific commands.
75
76 During disabling the target driver MAY close already connected sessions
77 in all targets, but this is OPTIONAL.
78
79 MUST be 0 by default.
80
81 2. "trace_level" - this attribute SHOULD allow to change log level of this
82 driver. 
83
84 This attribute SHOULD have read and write permissions for superuser and be
85 read-only for other users.
86
87 On read it SHOULD return a help text about available command and log levels.
88
89 On write it SHOULD accept commands to change log levels according to the
90 help text.
91
92 For example:
93
94 out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg | flow_control | conn
95
96 Usage:
97         echo "all|none|default" >trace_level
98         echo "value DEC|0xHEX|0OCT" >trace_level
99         echo "add|del TOKEN" >trace_level
100
101 where TOKEN is one of [debug, function, line, pid,
102                        entryexit, buff, mem, sg, out_of_mem,
103                        special, scsi, mgmt, minor,
104                        mgmt_dbg, scsi_serializing,
105                        retry, recv_bot, send_bot, recv_top,
106                        send_top, d_read, d_write, conn, conn_dbg, iov, pdu, net_page]
107
108
109 3. "version" - this read-only for all attribute SHOULD return version of
110 the target driver and some info about its enabled compile time facilities.
111
112 For example:
113
114 2.0.0
115 EXTRACHECKS
116 DEBUG
117  
118 4. "mgmt" - this attribute MUST allow to add and delete targets, if
119 virtual targets are supported by this driver, as well as it MAY allow to
120 add and delete the target driver's or its targets' attributes.
121
122 This attribute MUST have read and write permissions for superuser and be
123 read-only for other users.
124
125 On read it MUST return a help string describing available commands and
126 parameters.
127
128 For example:
129
130 Usage: echo "add_target target_name [parameters]" >mgmt
131        echo "del_target target_name" >mgmt
132        echo "add_attribute IncomingUser name password" >mgmt
133        echo "del_attribute IncomingUser name" >mgmt
134        echo "add_attribute OutgoingUser name password" >mgmt
135        echo "del_attribute OutgoingUser name" >mgmt
136        echo "add_target_attribute target_name IncomingUser name password" >mgmt
137        echo "del_target_attribute target_name IncomingUser name" >mgmt
138        echo "add_target_attribute target_name OutgoingUser name password" >mgmt
139        echo "del_target_attribute target_name OutgoingUser name" >mgmt
140
141 where parameters are one or more param_name=value pairs separated by ';'                                                                
142
143 4.1. "add_target" - if supported, this command MUST add new target with
144 name "target_name" and specified optional or required parameters. Each
145 parameter MUST be in form "parameter=value". All parameters MUST be
146 separated by ';' symbol.
147
148 All target drivers supporting creation of virtual targets MUST support
149 this command.
150
151 All target drivers supporting "add_target" command MUST support all
152 read-only targets' key attributes as parameters to "add_target" command
153 with the attributes' names as parameters' names and the attributes'
154 values as parameters' values. 
155
156 For example:
157
158 echo "add_target TARGET1 parameter1=1; parameter2=2" >mgmt
159
160 will add target with name "TARGET1" and parameters with names
161 "parameter1" and "parameter2" with values 1 and 2 correspondingly.
162
163 4.2. "del_target" - if supported, this command MUST delete target with
164 name "target_name". If "add_target" command is supported "del_target"
165 MUST also be supported.
166
167 4.3. "add_attribute" - if supported, this command MUST add a target
168 driver's attribute with the specified name and one or more values.
169
170 All target drivers supporting run time creation of the target driver's
171 key attributes MUST support this command.
172
173 For example, for iSCSI target:
174
175 echo "add_attribute IncomingUser name password" >mgmt
176
177 will add for discovery sessions an incoming user (attribute
178 /sys/kernel/scst_tgt/targets/iscsi/IncomingUser) with name "name" and
179 password "password".
180
181 4.4. "del_attribute" - if supported, this command MUST delete  target
182 driver's attribute with the specified name and values. The values MUST
183 be specified, because in some cases attributes MAY internally be
184 distinguished by values. For instance, iSCSI target might have several
185 incoming users. If not needed, target driver might ignore the values.
186
187 If "add_attribute" command is supported "del_attribute" MUST
188 also be supported.
189
190 4.5. "add_target_attribute" - if supported, this command MUST add new
191 attribute for the specified target with the specified name and one or
192 more values.
193
194 All target drivers supporting run time creation of targets' key
195 attributes MUST support this command.
196
197 For example:
198
199 echo "add_target_attribute iqn.2006-10.net.vlnb:tgt IncomingUser name password" >mgmt
200
201 will add for target with name "iqn.2006-10.net.vlnb:tgt" an incoming
202 user (attribute
203 /sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/IncomingUser)
204 with name "name" and password "password".
205
206 4.6. "del_target_attribute" - if supported, this command MUST delete 
207 target's attribute with the specified name and values. The values MUST
208 be specified, because in some cases attributes MAY internally be
209 distinguished by values. For instance, iSCSI target might have several
210 incoming users. If not needed, target driver might ignore the values.
211
212 If "add_target_attribute" command is supported "del_target_attribute"
213 MUST also be supported.
214
215 Attributes for targets
216 ----------------------
217
218 Each target MAY support in its root subdirectory the following optional
219 attributes. Target drivers MAY also support there other read-only or
220 read-writable attributes.
221
222 1. "enabled" - this attribute MUST allow to enable and disable the
223 corresponding target, i.e. if disabled, the target MUST NOT accept new
224 connections. The goal of this attribute is to allow the target's initial
225 configuration. For instance, each target needs to have its LUNs setup
226 before it starts serving initiators. Another example is iSCSI target,
227 which may need to have initialized a number of iSCSI parameters before
228 it starts accepting new iSCSI connections.
229
230 This attribute MUST have read and write permissions for superuser and be
231 read-only for other users.
232
233 On read it MUST return 0, if the target is disabled, and 1, if it is
234 enabled.
235
236 On write it MUST accept '0' character as request to disable and '1' as
237 request to enable. Other requests MUST be rejected.
238
239 SCST core provides some facilities, which MUST be used to implement this
240 attribute.
241
242 During disabling the target driver MAY close already connected sessions
243 to the target, but this is OPTIONAL.
244
245 MUST be 0 by default.
246
247 SCST core will automatically create for all targets the following
248 attributes:
249
250 1. "rel_tgt_id" - allows to read or write SCSI Relative Target Port
251 Identifier attribute.
252
253 2. "hw_target" - allows to distinguish hardware and virtual targets, if
254 the target driver supports both.
255
256 To provide OPTIONAL force close session functionality target drivers
257 MUST implement it using "force_close" write only session's attribute,
258 which on write to it MUST close the corresponding session.
259
260 See SCST core's README for more info about those attributes.
261
262 II. Rules for dev handlers
263 ==========================
264
265 There are 2 types of dev handlers: parent dev handlers and children dev
266 handlers. The children dev handlers depend from the parent dev handlers.
267
268 SCST core for each parent dev handler (struct scst_dev_type with
269 parent member with value NULL) creates a root subdirectory in
270 /sys/kernel/scst_tgt/handlers with name scst_dev_type.name (called
271 "dev_handler_name" further in this document). 
272
273 Parent dev handlers can have one or more subdirectories for children dev
274 handlers with names scst_dev_type.name of them.
275
276 Only one level of the dev handlers' parent/children hierarchy is
277 allowed. Parent dev handlers, which support children dev handlers, MUST
278 NOT handle devices and MUST be only placeholders for the children dev
279 handlers.
280
281 Further in this document children dev handlers or parent dev handlers,
282 which don't support children, will be called "end level dev handlers".
283
284 Each end level dev handler MUST be either for pass-through, or for
285 virtual devices.
286
287 End level dev handlers can be recognized by existence of the "mgmt"
288 attribute.
289
290 For each device (struct scst_device) SCST core creates a root
291 subdirectory in /sys/kernel/scst_tgt/devices/device_name with name
292 scst_device.virt_name (called "device_name" further in this document).
293
294 Attributes for dev handlers
295 ---------------------------
296
297 Each pass-through dev handler MUST have in its root subdirectory
298 "pass-through" and "mgmt" attributes and the "mgmt" attribute MUST
299 support "assign" and "unassign" commands as described below.
300
301 Each virtual devices dev handler MUST have it in its root subdirectory
302 "mgmt" attribute, which MUST support "add_device" and "del_device"
303 attributes as described below.
304
305 Parent dev handlers and end level dev handlers without parents MAY
306 support in its root subdirectory the following optional attributes. They
307 MAY also support there other read-only or read-writable attributes.
308
309 1. "trace_level" - this attribute SHOULD allow to change log level of this
310 driver. 
311
312 This attribute SHOULD have read and write permissions for superuser and be
313 read-only for other users.
314
315 On read it SHOULD return a help text about available command and log levels.
316
317 On write it SHOULD accept commands to change log levels according to the
318 help text.
319
320 For example:
321
322 out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg
323
324
325 Usage:
326         echo "all|none|default" >trace_level
327         echo "value DEC|0xHEX|0OCT" >trace_level
328         echo "add|del TOKEN" >trace_level
329
330 where TOKEN is one of [debug, function, line, pid,
331                        entryexit, buff, mem, sg, out_of_mem,
332                        special, scsi, mgmt, minor,
333                        mgmt_dbg, scsi_serializing,
334                        retry, recv_bot, send_bot, recv_top,
335                        send_top]
336
337 2. "version" - this read-only for all attribute SHOULD return version of
338 the dev handler and some info about its enabled compile time facilities.
339
340 For example:
341
342 2.0.0
343 EXTRACHECKS
344 DEBUG
345
346 End level dev handlers in their root subdirectories MUST support "mgmt"
347 attribute and MAY support other read-only or read-writable attributes.
348 This attribute MUST have read and write permissions for superuser and be
349 read-only for other users.
350
351 Attribute "mgmt" for virtual devices dev handlers
352 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353
354 For virtual devices dev handlers "mgmt" attribute MUST allow to add and
355 delete devices as well as it MAY allow to add and delete the dev
356 handler's or its devices' attributes.
357
358 On read it MUST return a help string describing available commands and
359 parameters.
360
361 For example:
362
363 Usage: echo "add_device device_name [parameters]" >mgmt
364        echo "del_device device_name" >mgmt
365        echo "add_attribute AttributeX ValueX" >mgmt
366        echo "del_attribute AttributeX ValueX" >mgmt
367        echo "add_attribute AttributeY ValueY1 ValueY2" >mgmt
368        echo "del_attribute AttributeY" >mgmt
369        echo "add_device_attribute device_name AttributeDX ValueDX" >mgmt
370        echo "del_device_attribute device_name AttributeDX ValueDX" >mgmt
371        echo "add_device_attribute device_name AttributeDY ValueY1 ValueY2" >mgmt
372        echo "del_device_attribute device_name AttributeDY" >mgmt
373
374 where parameters are one or more param_name=value pairs separated by ';'
375
376 The following parameters available: filename, blocksize, write_through, nv_cache, o_direct, read_only, removable
377
378 1. "add_device" - this command MUST add new device with name
379 "device_name" and specified optional or required parameters. Each
380 parameter MUST be in form "parameter=value". All parameters MUST be
381 separated by ';' symbol.
382
383 All dev handlers supporting "add_device" command MUST support all
384 read-only devices' key attributes as parameters to "add_device" command
385 with the attributes' names as parameters' names and the attributes'
386 values as parameters' values. 
387
388 For example:
389
390 echo "add_device device1 parameter1=1; parameter2=2" >mgmt
391
392 will add device with name "device1" and parameters with names
393 "parameter1" and "parameter2" with values 1 and 2 correspondingly.
394
395 2. "del_device" - this command MUST delete device with name
396 "device_name".
397
398 3. "add_attribute" - if supported, this command MUST add a device
399 driver's attribute with the specified name and one or more values.
400
401 All dev handlers supporting run time creation of the dev handler's
402 key attributes MUST support this command.
403
404 For example:
405
406 echo "add_attribute AttributeX ValueX" >mgmt
407
408 will add attribute
409 /sys/kernel/scst_tgt/handlers/dev_handler_name/AttributeX with value ValueX.
410
411 4. "del_attribute" - if supported, this command MUST delete device
412 driver's attribute with the specified name and values. The values MUST
413 be specified, because in some cases attributes MAY internally be
414 distinguished by values. If not needed, dev handler might ignore the
415 values.
416
417 If "add_attribute" command is supported "del_attribute" MUST also be
418 supported.
419
420 5. "add_device_attribute" - if supported, this command MUST add new
421 attribute for the specified device with the specified name and one or
422 more values.
423
424 All dev handlers supporting run time creation of devices' key attributes
425 MUST support this command.
426
427 For example:
428
429 echo "add_device_attribute device1 AttributeDX ValueDX" >mgmt
430
431 will add for device with name "device1" attribute
432 /sys/kernel/scst_tgt/devices/device_name/AttributeDX) with value
433 ValueDX.
434
435 6. "del_device_attribute" - if supported, this command MUST delete 
436 device's attribute with the specified name and values. The values MUST
437 be specified, because in some cases attributes MAY internally be
438 distinguished by values. If not needed, dev handler might ignore the
439 values.
440
441 If "add_device_attribute" command is supported "del_device_attribute"
442 MUST also be supported.
443
444 Attribute "mgmt" for pass-through devices dev handlers
445 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
446
447 For pass-through devices dev handlers "mgmt" attribute MUST allow to
448 assign and unassign this dev handler to existing SCSI devices.
449
450 On read it MUST return a help string describing available commands and
451 parameters.
452
453 For example:
454
455 Usage: echo "assign H:C:I:L" >mgmt
456        echo "unassign H:C:I:L" >mgmt
457
458 1. "assign" - this command MUST assign SCSI device with
459 host:channel:id:lun numbers to this dev handler.
460
461 All pass-through dev handlers MUST support this command.
462
463 For example:
464
465 echo "assign 1:0:0:0" >mgmt
466
467 will assign SCSI device 1:0:0:0 to this dev handler.
468
469 2. "unassign" - this command MUST unassign SCSI device with
470 host:channel:id:lun numbers from this dev handler.
471
472 SCST core will automatically create for all dev handlers the following
473 attributes:
474
475 1. "pass_through" - if the dev handler is a handler for pass-through
476 devices, SCST core create this attribute. This attribute will have value
477 1.
478
479 2. "type" - SCSI type of device this dev handler can handle.
480
481 See SCST core's README for more info about those attributes.
482
483 Attributes for devices
484 ----------------------
485
486 Each device MAY support in its root subdirectory any read-only or
487 read-writable attributes.
488
489 SCST core will automatically create for all devices the following
490 attributes:
491
492 1. "type" - SCSI type of this device
493
494 See SCST core's README for more info about those attributes.
495
496
497 III. Rules for management utilities
498 ===================================
499
500 Rules summary
501 -------------
502
503 A management utility (scstadmin) SHOULD NOT keep any knowledge specific
504 to any device, dev handler, target or target driver. It SHOULD only know
505 the common SCST SYSFS rules, which all dev handlers target drivers MUST
506 follow. Namely:
507
508 Common rules:
509 ~~~~~~~~~~~~~
510
511 1. All key attributes MUST be marked by mark "[key]" in the last line of
512 the attribute.
513
514 2. All not key attributes don't matter and SHOULD be ignored.
515
516 For target drivers and targets:
517 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
518
519 1. If target driver supports adding new targets, it MUST have "mgmt"
520 attribute, which MUST support "add_target" and "del_target" commands as
521 specified above.
522
523 2. If target driver supports run time adding new key attributes, it MUST
524 have "mgmt" attribute, which MUST support "add_attribute" and
525 "del_attribute" commands as specified above.
526
527 3. If target driver supports both hardware and virtual targets, all its
528 hardware targets MUST have "hw_target" attribute with value 1.
529
530 4. If target has read-only key attributes, the add_target command MUST
531 support them as parameters.
532
533 5. If target supports run time adding new key attributes, the target
534 driver MUST have "mgmt" attribute, which MUST support
535 "add_target_attribute" and "del_target_attribute" commands as specified
536 above.
537
538 6. Both target drivers and targets MAY support "enable" attribute. If
539 supported, after configuring the corresponding target driver or target
540 "1" MUST be written to this attribute in the following order: at first,
541 for all targets of the target driver, then for the target driver.
542
543 For devices and dev handlers:
544 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
545
546 1. Each dev handler in its root subdirectory MUST have "mgmt" attribute.
547
548 2. All pass-through dev handlers MUST have "pass_through" attribute.
549
550 3. Each virtual devices dev handler MUST support "add_device" and
551 "del_device" commands to the "mgmt" attribute as specified above.
552
553 4. Each pass-through dev handler MUST support "assign" and "unassign"
554 commands to the "mgmt" attribute as specified above.
555
556 5. If dev handler driver supports run time adding new key attributes, it
557 MUST support "add_attribute" and "del_attribute" commands to the "mgmt"
558 attribute as specified above.
559
560 6. All device handlers have links in the root subdirectory pointing to
561 their devices.
562
563 7. If device has read-only key attributes, the "add_device" command MUST
564 support them as parameters.
565
566 8. If device supports run time adding new key attributes, its dev
567 handler MUST support "add_device_attribute" and "del_device_attribute"
568 commands to the "mgmt" attribute as specified above.
569
570 9. Each device has "handler" link to its dev handler's root
571 subdirectory.
572
573 Algorithm to convert current SCST configuration to config file
574 --------------------------------------------------------------
575
576 A management utility SHOULD use the following algorithm when converting
577 current SCST configuration to a config file:
578
579 1. Scan all attributes in /sys/kernel/scst_tgt (not requirsive) and store
580 all found key attributes.
581
582 2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each
583 subdirectory with "mgmt" attribute is a root subdirectory of a dev
584 handler with name the name of the subdirectory. For each found dev
585 handler do the following:
586
587 2.1. Store the dev handler's name. Store also its path to the root
588 subdirectory, if it isn't default (/sys/kernel/scst_tgt/handlers/handler_name).
589
590 2.2. Store all dev handler's key attributes.
591
592 2.3. Go through all links in the root subdirectory pointing to
593 /sys/kernel/scst_tgt/devices and for each device:
594
595 2.3.1. For virtual devices dev handlers:
596
597 2.3.1.1. Store the name of the device.
598
599 2.3.1.2. Store all key attributes. Mark all read only key attributes
600 during storing, they will be parameters for the device's creation.
601
602 2.3.2. For pass-through devices dev handlers:
603
604 2.3.2.1. Store the H:C:I:L name of the device. Optionally, instead of
605 the name unique T10 vendor device ID found using command:
606
607 sg_inq -p 0x83 /dev/sdX
608
609 can be stored. It will allow to reliably find out this device if on the
610 next reboot it will have another host:channel:id:lin numbers. The sdX
611 device can be found as the last letters after ':' in
612 /sys/kernel/scst_tgt/devices/H:C:I:L/scsi_device/device/block:sdX.
613
614 3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For
615 each target driver:
616
617 3.1. Store the name of the target driver.
618
619 3.2. Store all its key attributes.
620
621 3.3. Go through all target's subdirectories. For each target:
622
623 3.3.1. Store the name of the target.
624
625 3.3.2. Mark if the target is hardware or virtual target. The target is a
626 hardware target if it has "hw_target" attribute or its target driver
627 doesn't have "mgmt" attribute.
628
629 3.3.3. Store all key attributes. Mark all read only key attributes
630 during storing, they will be parameters for the target's creation.
631
632 3.3.4. Scan all "luns" subdirectory and store:
633
634  - LUN.
635
636  - LU's device name.
637
638  - Key attributes.
639
640 3.3.5. Scan all "ini_groups" subdirectories. For each group store the following:
641
642  - The group's name.
643
644  - The group's LUNs (the same info as for 3.3.4).
645
646  - The group's initiators.
647
648 3.3.6. Store value of "enabled" attribute, if it exists.
649
650 3.4. Store value of "enabled" attribute, if it exists.
651
652
653 Algorithm to initialize SCST from config file
654 ---------------------------------------------
655
656 A management utility SHOULD use the following algorithm when doing
657 initial SCST configuration from a config file. All necessary kernel
658 modules and user space programs supposed to be already loaded, hence all
659 dev handlers' entries in /sys/kernel/scst_tgt/handlers as well as all
660 entries for hardware targets already created.
661
662 1. Set stored values for all stored global (/sys/kernel/scst_tgt)
663 attributes.
664
665 2. For each dev driver:
666
667 2.1. Set stored values for all already existing stored attributes.
668
669 2.2. Create not existing stored attributes using "add_attribute" command.
670
671 2.3. For virtual devices dev handlers for each stored device:
672
673 2.3.1. Create the device using "add_device" command using marked read
674 only attributes as parameters.
675
676 2.3.2. Set stored values for all already existing stored attributes.
677
678 2.3.3. Create not existing stored attributes using
679 "add_device_attribute" command.
680
681 2.4. For pass-through dev handlers for each stores device:
682
683 2.4.1. Assign the corresponding pass-through device to this dev handler
684 using "assign" command, if it isn't already auto assigned to it.
685
686 3. For each target driver:
687
688 3.1. Set stored values for all already existing stored attributes.
689
690 3.2. Create not existing stored attributes using "add_attribute" command.
691
692 3.3. For each target:
693
694 3.3.1. For virtual targets:
695
696 3.3.1.1. Create the target using "add_target" command using marked read
697 only attributes as parameters.
698
699 3.3.1.2. Set stored values for all already existing stored attributes.
700
701 3.3.1.3. Create not existing stored attributes using
702 "add_target_attribute" command.
703
704 3.3.2. For hardware targets for each target:
705
706 3.3.2.1. Set stored values for all already existing stored attributes.
707
708 3.3.2.2. Create not existing stored attributes using
709 "add_target_attribute" command.
710
711 3.3.3. Setup LUNs
712
713 3.3.4. Setup ini_groups, their LUNs and initiators' names.
714
715 3.3.5. If this target supports enabling, enable it.
716
717 3.4. If this target driver supports enabling, enable it.
718
719
720 Algorithm to apply changes in config file to currently running SCST
721 -------------------------------------------------------------------
722
723 A management utility SHOULD use the following algorithm when applying
724 changes in config file to currently running SCST.
725
726 Not all changes can be applied on enabled targets or enabled target
727 drivers. From other side, for some target drivers enabling/disabling is
728 a very long and disruptive operation, which should be performed as rare
729 as possible. Thus, the management utility SHOULD support additional
730 option, which, if set, will make it to disable all affected targets
731 before doing any change with them.
732
733 1. Scan all attributes in /sys/kernel/scst_tgt (not requirsive) and
734 compare stored and actual key attributes. Apply all changes.
735
736 2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each
737 subdirectory with "mgmt" attribute is a root subdirectory of a dev
738 handler with name the name of the subdirectory. For each found dev
739 handler do the following:
740
741 2.1. Compare stored and actual key attributes. Apply all changes. Create
742 new attributes using "add_attribute" commands and delete not needed any
743 more attributes using "del_attribute" command.
744
745 2.2. Compare existing devices (links in the root subdirectory pointing
746 to /sys/kernel/scst_tgt/devices) and stored devices in the config file.
747 Delete all not needed devices and create new devices.
748
749 2.3. For all existing devices:
750
751 2.3.1. Compare stored and actual key attributes. Apply all changes.
752 Create new attributes using "add_device_attribute" commands and delete
753 not needed any more attributes using "del_device_attribute" command.
754
755 2.3.2. If any read only key attribute for virtual device should be
756 changed, delete the devices and recreate it.
757
758 2.3.3. For pass-through devices dev handlers reassign handlers if
759 necessary.
760
761 3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For
762 each target driver:
763
764 3.1. If this target driver should be disabled, disable it.
765
766 3.2. Compare stored and actual key attributes. Apply all changes. Create
767 new attributes using "add_attribute" commands and delete not needed any
768 more attributes using "del_attribute" command.
769
770 3.3. Go through all target's subdirectories. Compare existing and stored
771 targets. Delete all not needed targets and create new targets.
772
773 3.4. For all existing targets:
774
775 3.4.1. If this target should be disabled, disable it.
776
777 3.4.2. Compare stored and actual key attributes. Apply all changes.
778 Create new attributes using "add_target_attribute" commands and delete
779 not needed any more attributes using "del_target_attribute" command.
780
781 3.4.3. If any read only key attribute for virtual target should be
782 changed, delete the target and recreate it.
783
784 3.4.4. Scan all "luns" subdirectory and apply necessary changes, using
785 "replace" commands to replace one LUN by another, if needed.
786
787 3.4.5. Scan all "ini_groups" subdirectories and apply necessary changes,
788 using "replace" commands to replace one LUN by another and "move"
789 command to move initiator from one group to another, if needed. It MUST
790 be done in the following order:
791
792  - Necessary initiators deleted, if they aren't going to be moved
793
794  - LUNs updated
795  
796  - Necessary initiators added or moved
797
798 3.4.6. If this target should be enabled, enable it.
799
800 3.5. If this target driver should be enabled, enable it.
801