SCST core / sysfs interface

new file mode 100644
index 0000000..2e594bd
@@ -0,0 +1,223 @@
+		SCST SYSFS interface rules
+		==========================
+
+This document explains the rules SCST target drivers, device handlers and
+management utilities must adhere to. These rules make it possible for a
+user space tool like scstadmin to save and restore the entire state of the
+SCST core, target drivers and device handlers.
+
+If the last line of a modifiable sysfs attribute contains the text "[key]",
+this means the value of that attribute is not the default value of that
+attribute. That text is added by SCST when such an attribute is read but
+must not be added when modifying an SCST sysfs attribute.
+
+I. Rules for target drivers
+===========================
+
+The SCST core creates a directory for each target driver (struct
+scst_tgt_template) in /sys/bus/scst_target. And for each SCSI target (struct
+scst_tgt) the SCST core creates a directory in /sys/bus/scst_target/devices/.
+
+There are two types of SCSI targets, namely hardware and virtual.  Hardware
+targets are targets corresponding to a hardware entity, e.g. a port of a Fibre
+Channel adapter or an InfiniBand HCA. Virtual targets can be added and removed
+dynamically and do not have a one-to-one correspondence to hardware. As an
+example, iSCSI targets and NPIV Fibre Channel targets are virtual targets.
+
+Virtual targets are created and removed via the commands "add_target" and
+"del_target" respectively.
+
+A target driver that supports both hardware targets and virtual targets
+(e.g. an FC adapter that supports NPIV) must mark each hardware target with
+"hw_target" (see further).
+
+Querying the current state
+--------------------------
+
+Querying the current state is possible by reading individual sysfs attributes.
+As an example, querying the state of the SCST core, all device drivers and
+target drivers is possible as follows:
+
+# find /sys/devices/scst /sys/bus/scst_target /sys/bus/scst_tgt_dev -type f -perm -u+r | xargs head
+
+Modifying the current state
+---------------------------
+
+If a sysfs attribute has write permission, it can be modified by writing a new
+value into that attribute. Many management actions though happen via the
+"mgmt" attribute of the SCST device itself. The documentation of the syntax of
+the management commands can be revealed by reading that attribute. An example:
+
+# cd /sys/devices/scst
+# cat mgmt
+[ ... ]
+# cat /sys/devices/disk01/threads_num
+6
+[key]
+# echo "in device/disk01 set_threads_num 1" >mgmt
+# cat /sys/devices/disk01/threads_num
+1
+[key]
+
+
+Target driver attributes
+------------------------
+
+Target drivers may support the following attributes:
+
+1. "enabled" - allows to enable and disable a target driver as a whole. If
+disabled, the target driver must not accept any new connection. Allows to
+configure a target driver before it becomes operational. Disabling a target
+driver may have the effect of closing all existing sessions for all
+targets. Defaults to 0 (disabled). Set this attribute to 1 to enable a target
+driver.
+
+2. "trace_level" - allows to manage the trace level of a target driver. An
+example:
+
+echo "add debug" >/sys/bus/scst_target/drivers/scst_local/trace_level
+
+3. "version" - Allows to query the target driver version and compilation
+options.
+
+An example:
+
+$ cat /sys/bus/scst_target/drivers/scst_local/version
+1.0.0/20100910
+EXTRACHECKS
+DEBUG
+
+4. "add_target" - If this attribute exists and equals 1 this means that the
+target driver supports the "add_target" command.
+
+5. "add_target_parameters" - Names of the parameters supported by the
+"add_target" command (one per line).
+
+6. "driver_attributes" - Names of the target driver attributes that can be
+created or removed dynamically by the add_attribute and del_attribute
+commands.
+
+7. "target_attributes" - Names of the target attributes that can be created or
+removed dynamically by the add_target_attribute and del_target_attribute
+commands.
+
+
+Target attributes
+-----------------
+
+Each SCSI target may support the following attributes:
+
+1. "enabled" - Allows to enable or disable a target by setting this attribute
+to 1 or 0 respectively. No new connections are accepted for a disabled
+target. This allows to configure a target before any connections are accepted.
+Must default to disabled.
+
+2. "rel_tgt_id" - SCSI Relative Target Port Identifier.
+
+3. "hw_target" (optional) - Allows to distinguish hardware and virtual
+targets, if the target driver supports both.
+
+4. "force_close" (optional) - Allows to forcibly close all sessions associated
+with a target.
+
+See also the SCST readme for further information.
+
+
+II. Rules for device handlers
+=============================
+
+There are two types of device handlers: parent device handlers and child
+device handlers. The child device handlers depend on their parent device
+handler.
+
+The SCST core creates a directory for each parent device handler (struct
+scst_dev_type where the parent member equals NULL) in
+/sys/bus/scst_tgt_dev/driver. Parent device handlers can have one or more
+subdirectories for child device handlers.
+
+Only one level is allowed in the parent/child hierarchy. Parent device
+handlers that support child device handlers must not handle devices themselves.
+
+In this document child device handlers and parent device handlers without
+child device handlers will be called "end level device handlers".
+
+For each device (struct scst_device) the SCST core creates a directory in
+/sys/bus/scst_tgt_dev.
+
+Device handler attributes
+-------------------------
+
+The following attributes may be supported for a device handler:
+
+1. "trace_level" - Allows to query and/or modify the log level for a device
+handler.
+
+2. "add_device_parameters" - Parameters supported by the add_device command.
+
+3. "driver_attributes" - Attributes supported by the add_attribute and
+del_attribute commands.
+
+4. "device_attributes" - Attributes supported by the add_device_attribute and
+del_device_attribute commands.
+
+5. "type" - SCSI device type. A number followed by a description, e.g.:
+
+# cat /sys/bus/scst_tgt_dev/drivers/vcdrom/type
+5 - CD-ROM device
+
+
+Device attributes
+-----------------
+
+The following attributes may be supported for a device:
+
+1. blocksize - Native SCSI block size of this device.
+
+2. filename - For virtual devices, the path of the associated file or device.
+An example:
+
+# cat /sys/devices/disk01/filename
+/dev/sdc
+[key]
+
+3. nv_cache - Whether or not the device has a non-volatile cache. SCST uses
+this information to decide whether or not it is safe to acknowledge writes
+early to the initiator. Setting this attribute to 1 for a device that neither
+has a non-volatile cache nor an UPS will decrease I/O latency but may result
+in data loss in case of a power failure.
+
+4. o_direct - For virtual devices that use file I/O, whether to use
+non-buffered (direct) I/O or buffered (asynchronous) I/O. In direct I/O mode
+both read and write caching is disabled.
+
+5. read_only - For virtual devices, whether or not to deny write commands.
+
+6. removable - For virtual devices, whether or not the underlying storage
+medium is removable.
+
+7. resync_size - For virtual devices, writing to this attribute will update
+the internally cached device size.
+
+8. size_mb - For virtual devices, the internally cached size in MB of the
+underlying storage device.
+
+9. t10_dev_id - SCSI device ID associated with the virtual device. This is the
+ID reported via the Device Identification page (0x83) of the INQUIRY command.
+
+10. thin_provisioned - Whether or not the virtual device supports thin
+provisioning.
+
+11. threads_num - Number of threads that exist in the thread pool that is
+used for processing SCSI commands for this device.
+
+12. threads_pool_type - Whether to use a distinct thread pool per initiator
+("per_initiator") or one thread pool for all initiators accessing this device
+("shared").
+
+13. type - SCSI type of this device.
+
+14. usn - Unique serial number as reported in the SCSI INQUIRY response.
+
+15. write_through - Allows to disable write-back caching for virtual devices.
+
+See also the SCST core README for more information about those attributes.