scst/scst/SysfsRules

		SCST SYSFS interface rules
		==========================

This file describes SYSFS interface rules, which all SCST target
drivers, dev handlers and management utilities MUST follow. This allows
to have a simple, self-documented, target drivers and dev handlers
independent management interface.

Words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.

In this document "key attribute" means a configuration attribute with
not default value, which must be configured during the target driver's
initialization. A key attribute MUST have in the last line keyword
"[key]". If a default value set to a key attribute, it becomes a regular
none-key attribute. For instance, iSCSI target has attribute DataDigest.
Default value for this attribute is "None". It value "CRC32C" is set to
this attribute, it will become a key attribute. If value "None" is again
set, this attribute will become back to a none-key attribute.

Each user configurable attribute with a not default value MUST be marked
as key attribute.


I. Rules for target drivers
===========================

SCST core for each target driver (struct scst_tgt_template) creates a
root subdirectory in /sys/kernel/scst_tgt/targets with name
scst_tgt_template.name (called "target_driver_name" further in this
document).

For each target (struct scst_tgt) SCST core creates a root subdirectory
in /sys/kernel/scst_tgt/targets/target_driver_name with name
scst_tgt.tgt_name (called "target_name" further in this document).

There are 2 type of targets possible: hardware and virtual targets.
Hardware targets are targets corresponding to real hardware, for
instance, a Fibre Channel adapter's port. Virtual targets are hardware
independent targets, which can be dynamically added or removed, for
instance, an iSCSI target, or NPIV Fibre Channel target.

A target driver supporting virtual targets must support "mgmt" attribute
and "add_target"/"del_target" commands.

If target driver supports both hardware and virtual targets (for
instance, an FC adapter supporting NPIV, which has hardware targets for
its physical ports as well as virtual NPIV targets), it MUST create each
hardware target with hw_target mark to make SCST core create "hw_target"
attribute (see below).

Attributes for target drivers
-----------------------------

A target driver MAY support in its root subdirectory the following
optional attributes. Target drivers MAY also support there other
read-only or read-writable attributes.

1. "enabled" - this attribute MUST allow to enable and disable target
driver as a whole, i.e. if disabled, the target driver MUST NOT accept
new connections. The goal of this attribute is to allow the target
driver's initial configuration. For instance, iSCSI target may need to
have discovery user names and passwords set before it starts serving
discovery connections.

This attribute MUST have read and write permissions for superuser and be
read-only for other users.

On read it MUST return 0, if the target driver is disabled, and 1, if it
is enabled.

On write it MUST accept '0' character as request to disable and '1' as
request to enable, but MAY also accept other driver specific commands.

During disabling the target driver MAY close already connected sessions
in all targets, but this is OPTIONAL.

MUST be 0 by default.

2. "trace_level" - this attribute SHOULD allow to change log level of this
driver.

This attribute SHOULD have read and write permissions for superuser and be
read-only for other users.

On read it SHOULD return a help text about available command and log levels.

On write it SHOULD accept commands to change log levels according to the
help text.

For example:

out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg | flow_control | conn

Usage:
        echo "all|none|default" >trace_level
        echo "value DEC|0xHEX|0OCT" >trace_level
        echo "add|del TOKEN" >trace_level

where TOKEN is one of [debug, function, line, pid,
		       entryexit, buff, mem, sg, out_of_mem,
		       special, scsi, mgmt, minor,
		       mgmt_dbg, scsi_serializing,
		       retry, recv_bot, send_bot, recv_top,
		       send_top, d_read, d_write, conn, conn_dbg, iov, pdu, net_page]


3. "version" - this read-only for all attribute SHOULD return version of
the target driver and some info about its enabled compile time facilities.

For example:

2.0.0
EXTRACHECKS
DEBUG

4. "mgmt" - this attribute MUST allow to add and delete targets, if
virtual targets are supported by this driver, as well as it MAY allow to
add and delete the target driver's or its targets' attributes.

This attribute MUST have read and write permissions for superuser and be
read-only for other users.

On read it MUST return a help string describing available commands and
parameters.

For example:

Usage: echo "add_target target_name [parameters]" >mgmt
       echo "del_target target_name" >mgmt
       echo "add_attribute IncomingUser name password" >mgmt
       echo "del_attribute IncomingUser name" >mgmt
       echo "add_attribute OutgoingUser name password" >mgmt
       echo "del_attribute OutgoingUser name" >mgmt
       echo "add_target_attribute target_name IncomingUser name password" >mgmt
       echo "del_target_attribute target_name IncomingUser name" >mgmt
       echo "add_target_attribute target_name OutgoingUser name password" >mgmt
       echo "del_target_attribute target_name OutgoingUser name" >mgmt

where parameters are one or more param_name=value pairs separated by ';'

4.1. "add_target" - if supported, this command MUST add new target with
name "target_name" and specified optional or required parameters. Each
parameter MUST be in form "parameter=value". All parameters MUST be
separated by ';' symbol.

All target drivers supporting creation of virtual targets MUST support
this command.

All target drivers supporting "add_target" command MUST support all
read-only targets' key attributes as parameters to "add_target" command
with the attributes' names as parameters' names and the attributes'
values as parameters' values.

For example:

echo "add_target TARGET1 parameter1=1; parameter2=2" >mgmt

will add target with name "TARGET1" and parameters with names
"parameter1" and "parameter2" with values 1 and 2 correspondingly.

4.2. "del_target" - if supported, this command MUST delete target with
name "target_name". If "add_target" command is supported "del_target"
MUST also be supported.

4.3. "add_attribute" - if supported, this command MUST add a target
driver's attribute with the specified name and one or more values.

All target drivers supporting run time creation of the target driver's
key attributes MUST support this command.

For example, for iSCSI target:

echo "add_attribute IncomingUser name password" >mgmt

will add for discovery sessions an incoming user (attribute
/sys/kernel/scst_tgt/targets/iscsi/IncomingUser) with name "name" and
password "password".

4.4. "del_attribute" - if supported, this command MUST delete  target
driver's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. For instance, iSCSI target might have several
incoming users. If not needed, target driver might ignore the values.

If "add_attribute" command is supported "del_attribute" MUST
also be supported.

4.5. "add_target_attribute" - if supported, this command MUST add new
attribute for the specified target with the specified name and one or
more values.

All target drivers supporting run time creation of targets' key
attributes MUST support this command.

For example:

echo "add_target_attribute iqn.2006-10.net.vlnb:tgt IncomingUser name password" >mgmt

will add for target with name "iqn.2006-10.net.vlnb:tgt" an incoming
user (attribute
/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/IncomingUser)
with name "name" and password "password".

4.6. "del_target_attribute" - if supported, this command MUST delete
target's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. For instance, iSCSI target might have several
incoming users. If not needed, target driver might ignore the values.

If "add_target_attribute" command is supported "del_target_attribute"
MUST also be supported.

Attributes for targets
----------------------

Each target MAY support in its root subdirectory the following optional
attributes. Target drivers MAY also support there other read-only or
read-writable attributes.

1. "enabled" - this attribute MUST allow to enable and disable the
corresponding target, i.e. if disabled, the target MUST NOT accept new
connections. The goal of this attribute is to allow the target's initial
configuration. For instance, each target needs to have its LUNs setup
before it starts serving initiators. Another example is iSCSI target,
which may need to have initialized a number of iSCSI parameters before
it starts accepting new iSCSI connections.

This attribute MUST have read and write permissions for superuser and be
read-only for other users.

On read it MUST return 0, if the target is disabled, and 1, if it is
enabled.

On write it MUST accept '0' character as request to disable and '1' as
request to enable. Other requests MUST be rejected.

SCST core provides some facilities, which MUST be used to implement this
attribute.

During disabling the target driver MAY close already connected sessions
to the target, but this is OPTIONAL.

MUST be 0 by default.

SCST core will automatically create for all targets the following
attributes:

1. "rel_tgt_id" - allows to read or write SCSI Relative Target Port
Identifier attribute.

2. "hw_target" - allows to distinguish hardware and virtual targets, if
the target driver supports both.

To provide OPTIONAL force close session functionality target drivers
MUST implement it using "force_close" write only session's attribute,
which on write to it MUST close the corresponding session.

See SCST core's README for more info about those attributes.

II. Rules for dev handlers
==========================

There are 2 types of dev handlers: parent dev handlers and children dev
handlers. The children dev handlers depend from the parent dev handlers.

SCST core for each parent dev handler (struct scst_dev_type with
parent member with value NULL) creates a root subdirectory in
/sys/kernel/scst_tgt/handlers with name scst_dev_type.name (called
"dev_handler_name" further in this document).

Parent dev handlers can have one or more subdirectories for children dev
handlers with names scst_dev_type.name of them.

Only one level of the dev handlers' parent/children hierarchy is
allowed. Parent dev handlers, which support children dev handlers, MUST
NOT handle devices and MUST be only placeholders for the children dev
handlers.

Further in this document children dev handlers or parent dev handlers,
which don't support children, will be called "end level dev handlers".

End level dev handlers can be recognized by existence of the "mgmt"
attribute.

For each device (struct scst_device) SCST core creates a root
subdirectory in /sys/kernel/scst_tgt/devices/device_name with name
scst_device.virt_name (called "device_name" further in this document).

Attributes for dev handlers
---------------------------

Each dev handler MUST have it in its root subdirectory "mgmt" attribute,
which MUST support "add_device" and "del_device" attributes as described
below.

Parent dev handlers and end level dev handlers without parents MAY
support in its root subdirectory the following optional attributes. They
MAY also support there other read-only or read-writable attributes.

1. "trace_level" - this attribute SHOULD allow to change log level of this
driver.

This attribute SHOULD have read and write permissions for superuser and be
read-only for other users.

On read it SHOULD return a help text about available command and log levels.

On write it SHOULD accept commands to change log levels according to the
help text.

For example:

out_of_mem | minor | pid | line | function | special | mgmt | mgmt_dbg


Usage:
	echo "all|none|default" >trace_level
	echo "value DEC|0xHEX|0OCT" >trace_level
	echo "add|del TOKEN" >trace_level

where TOKEN is one of [debug, function, line, pid,
		       entryexit, buff, mem, sg, out_of_mem,
		       special, scsi, mgmt, minor,
		       mgmt_dbg, scsi_serializing,
		       retry, recv_bot, send_bot, recv_top,
		       send_top]

2. "version" - this read-only for all attribute SHOULD return version of
the dev handler and some info about its enabled compile time facilities.

For example:

2.0.0
EXTRACHECKS
DEBUG

End level dev handlers in their root subdirectories MUST support "mgmt"
attribute and MAY support other read-only or read-writable attributes.
This attribute MUST have read and write permissions for superuser and be
read-only for other users.

Attribute "mgmt" for virtual devices dev handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For virtual devices dev handlers "mgmt" attribute MUST allow to add and
delete devices as well as it MAY allow to add and delete the dev
handler's or its devices' attributes.

On read it MUST return a help string describing available commands and
parameters.

For example:

Usage: echo "add_device device_name [parameters]" >mgmt
       echo "del_device device_name" >mgmt
       echo "add_attribute AttributeX ValueX" >mgmt
       echo "del_attribute AttributeX ValueX" >mgmt
       echo "add_attribute AttributeY ValueY1 ValueY2" >mgmt
       echo "del_attribute AttributeY" >mgmt
       echo "add_device_attribute device_name AttributeDX ValueDX" >mgmt
       echo "del_device_attribute device_name AttributeDX ValueDX" >mgmt
       echo "add_device_attribute device_name AttributeDY ValueY1 ValueY2" >mgmt
       echo "del_device_attribute device_name AttributeDY" >mgmt

where parameters are one or more param_name=value pairs separated by ';'

The following parameters available: filename, blocksize, write_through, nv_cache, o_direct, read_only, removable

1. "add_device" - this command MUST add new device with name
"device_name" and specified optional or required parameters. Each
parameter MUST be in form "parameter=value". All parameters MUST be
separated by ';' symbol.

All dev handlers supporting "add_device" command MUST support all
read-only devices' key attributes as parameters to "add_device" command
with the attributes' names as parameters' names and the attributes'
values as parameters' values.

For example:

echo "add_device device1 parameter1=1; parameter2=2" >mgmt

will add device with name "device1" and parameters with names
"parameter1" and "parameter2" with values 1 and 2 correspondingly.

2. "del_device" - this command MUST delete device with name
"device_name".

3. "add_attribute" - if supported, this command MUST add a device
driver's attribute with the specified name and one or more values.

All dev handlers supporting run time creation of the dev handler's
key attributes MUST support this command.

For example:

echo "add_attribute AttributeX ValueX" >mgmt

will add attribute
/sys/kernel/scst_tgt/handlers/dev_handler_name/AttributeX with value ValueX.

4. "del_attribute" - if supported, this command MUST delete device
driver's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. If not needed, dev handler might ignore the
values.

If "add_attribute" command is supported "del_attribute" MUST also be
supported.

5. "add_device_attribute" - if supported, this command MUST add new
attribute for the specified device with the specified name and one or
more values.

All dev handlers supporting run time creation of devices' key attributes
MUST support this command.

For example:

echo "add_device_attribute device1 AttributeDX ValueDX" >mgmt

will add for device with name "device1" attribute
/sys/kernel/scst_tgt/devices/device_name/AttributeDX) with value
ValueDX.

6. "del_device_attribute" - if supported, this command MUST delete
device's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. If not needed, dev handler might ignore the
values.

If "add_device_attribute" command is supported "del_device_attribute"
MUST also be supported.

Attribute "mgmt" for pass-through devices dev handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For pass-through devices dev handlers "mgmt" attribute MUST allow to
assign and unassign this dev handler to existing SCSI devices via
"add_device" and "del_device" commands correspondingly.

On read it MUST return a help string describing available commands and
parameters.

For example:

Usage: echo "add_device H:C:I:L" >mgmt
       echo "del_device H:C:I:L" >mgmt

1. "add_device" - this command MUST assign SCSI device with
host:channel:id:lun numbers to this dev handler.

All pass-through dev handlers MUST support this command.

For example:

echo "add_device 1:0:0:0" >mgmt

will assign SCSI device 1:0:0:0 to this dev handler.

2. "del_device" - this command MUST unassign SCSI device with
host:channel:id:lun numbers from this dev handler.

SCST core will automatically create for all dev handlers the following
attributes:

1. "type" - SCSI type of device this dev handler can handle.

See SCST core's README for more info about those attributes.

Attributes for devices
----------------------

Each device MAY support in its root subdirectory any read-only or
read-writable attributes.

SCST core will automatically create for all devices the following
attributes:

1. "type" - SCSI type of this device

See SCST core's README for more info about those attributes.


III. Rules for management utilities
===================================

Rules summary
-------------

A management utility (scstadmin) SHOULD NOT keep any knowledge specific
to any device, dev handler, target or target driver. It SHOULD only know
the common SCST SYSFS rules, which all dev handlers and target drivers
MUST follow. Namely:

Common rules:
~~~~~~~~~~~~~

1. All key attributes MUST be marked by mark "[key]" in the last line of
the attribute.

2. All not key attributes don't matter and SHOULD be ignored.

For target drivers and targets:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. If target driver supports adding new targets, it MUST have "mgmt"
attribute, which MUST support "add_target" and "del_target" commands as
specified above.

2. If target driver supports run time adding new key attributes, it MUST
have "mgmt" attribute, which MUST support "add_attribute" and
"del_attribute" commands as specified above.

3. If target driver supports both hardware and virtual targets, all its
hardware targets MUST have "hw_target" attribute with value 1.

4. If target has read-only key attributes, the add_target command MUST
support them as parameters.

5. If target supports run time adding new key attributes, the target
driver MUST have "mgmt" attribute, which MUST support
"add_target_attribute" and "del_target_attribute" commands as specified
above.

6. Both target drivers and targets MAY support "enable" attribute. If
supported, after configuring the corresponding target driver or target
"1" MUST be written to this attribute in the following order: at first,
for all targets of the target driver, then for the target driver.

For devices and dev handlers:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Each dev handler in its root subdirectory MUST have "mgmt" attribute.

2. Each dev handler MUST support "add_device" and "del_device" commands
to the "mgmt" attribute as specified above.

3. If dev handler driver supports run time adding new key attributes, it
MUST support "add_attribute" and "del_attribute" commands to the "mgmt"
attribute as specified above.

4. All device handlers have links in the root subdirectory pointing to
their devices.

5. If device has read-only key attributes, the "add_device" command MUST
support them as parameters.

6. If device supports run time adding new key attributes, its dev
handler MUST support "add_device_attribute" and "del_device_attribute"
commands to the "mgmt" attribute as specified above.

7. Each device has "handler" link to its dev handler's root
subdirectory.

Algorithm to convert current SCST configuration to config file
--------------------------------------------------------------

A management utility SHOULD use the following algorithm when converting
current SCST configuration to a config file:

1. Scan all attributes in /sys/kernel/scst_tgt (not requirsive) and store
all found key attributes.

2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each
subdirectory with "mgmt" attribute is a root subdirectory of a dev
handler with name the name of the subdirectory. For each found dev
handler do the following:

2.1. Store the dev handler's name. Store also its path to the root
subdirectory, if it isn't default (/sys/kernel/scst_tgt/handlers/handler_name).

2.2. Store all dev handler's key attributes.

2.3. Go through all links in the root subdirectory pointing to
/sys/kernel/scst_tgt/devices and for each device:

2.3.1. For virtual devices dev handlers:

2.3.1.1. Store the name of the device.

2.3.1.2. Store all key attributes. Mark all read only key attributes
during storing, they will be parameters for the device's creation.

2.3.2. For pass-through devices dev handlers:

2.3.2.1. Store the H:C:I:L name of the device. Optionally, instead of
the name unique T10 vendor device ID found using command:

sg_inq -p 0x83 /dev/sdX

can be stored. It will allow to reliably find out this device if on the
next reboot it will have another host:channel:id:lin numbers. The sdX
device can be found as the last letters after ':' in
/sys/kernel/scst_tgt/devices/H:C:I:L/scsi_device/device/block:sdX.

3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For
each target driver:

3.1. Store the name of the target driver.

3.2. Store all its key attributes.

3.3. Go through all target's subdirectories. For each target:

3.3.1. Store the name of the target.

3.3.2. Mark if the target is hardware or virtual target. The target is a
hardware target if it has "hw_target" attribute or its target driver
doesn't have "mgmt" attribute.

3.3.3. Store all key attributes. Mark all read only key attributes
during storing, they will be parameters for the target's creation.

3.3.4. Scan all "luns" subdirectory and store:

 - LUN.

 - LU's device name.

 - Key attributes.

3.3.5. Scan all "ini_groups" subdirectories. For each group store the following:

 - The group's name.

 - The group's LUNs (the same info as for 3.3.4).

 - The group's initiators.

3.3.6. Store value of "enabled" attribute, if it exists.

3.4. Store value of "enabled" attribute, if it exists.


Algorithm to initialize SCST from config file
---------------------------------------------

A management utility SHOULD use the following algorithm when doing
initial SCST configuration from a config file. All necessary kernel
modules and user space programs supposed to be already loaded, hence all
dev handlers' entries in /sys/kernel/scst_tgt/handlers as well as all
entries for hardware targets already created.

1. Set stored values for all stored global (/sys/kernel/scst_tgt)
attributes.

2. For each dev driver:

2.1. Set stored values for all already existing stored attributes.

2.2. Create not existing stored attributes using "add_attribute" command.

2.3. For virtual devices dev handlers for each stored device:

2.3.1. Create the device using "add_device" command using marked read
only attributes as parameters.

2.3.2. Set stored values for all already existing stored attributes.

2.3.3. Create not existing stored attributes using
"add_device_attribute" command.

2.4. For pass-through dev handlers for each stores device:

2.4.1. Assign the corresponding pass-through device to this dev handler
using "add_device" command, if it isn't already auto assigned to it.

3. For each target driver:

3.1. Set stored values for all already existing stored attributes.

3.2. Create not existing stored attributes using "add_attribute" command.

3.3. For each target:

3.3.1. For virtual targets:

3.3.1.1. Create the target using "add_target" command using marked read
only attributes as parameters.

3.3.1.2. Set stored values for all already existing stored attributes.

3.3.1.3. Create not existing stored attributes using
"add_target_attribute" command.

3.3.2. For hardware targets for each target:

3.3.2.1. Set stored values for all already existing stored attributes.

3.3.2.2. Create not existing stored attributes using
"add_target_attribute" command.

3.3.3. Setup LUNs

3.3.4. Setup ini_groups, their LUNs and initiators' names.

3.3.5. If this target supports enabling, enable it.

3.4. If this target driver supports enabling, enable it.


Algorithm to apply changes in config file to currently running SCST
-------------------------------------------------------------------

A management utility SHOULD use the following algorithm when applying
changes in config file to currently running SCST.

Not all changes can be applied on enabled targets or enabled target
drivers. From other side, for some target drivers enabling/disabling is
a very long and disruptive operation, which should be performed as rare
as possible. Thus, the management utility SHOULD support additional
option, which, if set, will make it to disable all affected targets
before doing any change with them.

1. Scan all attributes in /sys/kernel/scst_tgt (not requirsive) and
compare stored and actual key attributes. Apply all changes.

2. Scan all subdirectories of /sys/kernel/scst_tgt/handlers. Each
subdirectory with "mgmt" attribute is a root subdirectory of a dev
handler with name the name of the subdirectory. For each found dev
handler do the following:

2.1. Compare stored and actual key attributes. Apply all changes. Create
new attributes using "add_attribute" commands and delete not needed any
more attributes using "del_attribute" command.

2.2. Compare existing devices (links in the root subdirectory pointing
to /sys/kernel/scst_tgt/devices) and stored devices in the config file.
Delete all not needed devices and create new devices.

2.3. For all existing devices:

2.3.1. Compare stored and actual key attributes. Apply all changes.
Create new attributes using "add_device_attribute" commands and delete
not needed any more attributes using "del_device_attribute" command.

2.3.2. If any read only key attribute for virtual device should be
changed, delete the devices and recreate it.

3. Go through all subdirectories in /sys/kernel/scst_tgt/targets. For
each target driver:

3.1. If this target driver should be disabled, disable it.

3.2. Compare stored and actual key attributes. Apply all changes. Create
new attributes using "add_attribute" commands and delete not needed any
more attributes using "del_attribute" command.

3.3. Go through all target's subdirectories. Compare existing and stored
targets. Delete all not needed targets and create new targets.

3.4. For all existing targets:

3.4.1. If this target should be disabled, disable it.

3.4.2. Compare stored and actual key attributes. Apply all changes.
Create new attributes using "add_target_attribute" commands and delete
not needed any more attributes using "del_target_attribute" command.

3.4.3. If any read only key attribute for virtual target should be
changed, delete the target and recreate it.

3.4.4. Scan all "luns" subdirectory and apply necessary changes, using
"replace" commands to replace one LUN by another, if needed.

3.4.5. Scan all "ini_groups" subdirectories and apply necessary changes,
using "replace" commands to replace one LUN by another and "move"
command to move initiator from one group to another, if needed. It MUST
be done in the following order:

 - Necessary initiators deleted, if they aren't going to be moved

 - LUNs updated

 - Necessary initiators added or moved

3.4.6. If this target should be enabled, enable it.

3.5. If this target driver should be enabled, enable it.