[PATCHv2 0/3] Move SCST sysfs documentation to Documentation/ABI

[PATCHv2 0/3] Move SCST sysfs documentation to Documentation/ABI

[Bart Van Assche]

Since documentation of sysfs attributes must reside in Documentation/ABI, this
series of three patches moves the documentation of the SCST sysfs attributes
to that location. Please review.

Changes since the patch set posted yesterday:
- Removed kernel version.
- All indentation is now done via tabs.
- Changed the contents of the contact field from a mailing list into the name of a person.
- Removed more redundant documentation.

Re: [PATCHv2 1/3] [SCSI] scst: Move target docs to Documentation/ABI

[Bart Van Assche]

Move the documentation about SCSI target drivers and devices from
Documentation/scst/SysfsRules and Documentation/scst/README.scst to
Documentation/ABI/stable.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Greg Kroah-Hartman <gregkh@suse.de>
Cc: Vladislav Bolkhovitin <vst@vlnb.net>
Cc: Richard Sharpe <realrichardsharpe@gmail.com>
---
 Documentation/ABI/stable/sysfs-devices-scst_target |  188 ++++++++++++++++++++
 .../stable/sysfs-devices-scst_target-scst_local    |   18 ++
 Documentation/ABI/stable/sysfs-driver-scst_target  |   59 ++++++
 .../ABI/stable/sysfs-driver-scst_target-scst_local |   11 ++
 Documentation/scst/README.scst                     |   98 ----------
 Documentation/scst/SysfsRules                      |   63 -------
 6 files changed, 276 insertions(+), 161 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-devices-scst_target
 create mode 100644 Documentation/ABI/stable/sysfs-devices-scst_target-scst_local
 create mode 100644 Documentation/ABI/stable/sysfs-driver-scst_target
 create mode 100644 Documentation/ABI/stable/sysfs-driver-scst_target-scst_local

diff --git a/Documentation/ABI/stable/sysfs-devices-scst_target b/Documentation/ABI/stable/sysfs-devices-scst_target
new file mode 100644
index 0000000..0835ab5
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_target
@@ -0,0 +1,188 @@
+What:		/sys/bus/scst_target/devices/*/addr_method
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		LUN addressing method used by this target when e.g. responding
+		to a REPORT_LUNS command. One of the values FLAT, PERIPHERAL
+		or LUN. See also SAM-3, section 4.9, Logical Unit Numbers.
+		Read-write.
+
+What:		/sys/bus/scst_target/devices/*/cpu_mask
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Target-specific CPU mask. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/force_close
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		If this file exists, allows to forcibly close all sessions
+		associated with a target. Optional / write-only.
+
+What:		/sys/bus/scst_target/devices/*/enabled
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Allows to enable or disable a target by setting this attribute
+		to 1 or 0 respectively. No new connections are accepted for a
+		target that is in the disabled state. Defaults to disabled
+		(0). This allows to configure a target before any connections
+		are accepted. Enabling a target is only allowed if its relative
+		target port identifier is unique. Read-write.
+
+What:		/sys/bus/scst_target/devices/*/hw_target
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Allows to distinguish hardware and virtual targets. The value
+		1 means that there is a one-to-one correspondence between this
+		target and a hardware entity, and the value 0 means that there
+		is no such one-to-one correspondence. Only exists when the
+		target driver supports both hardware and virtual targets.
+		Read-only.
+
+What:		/sys/bus/scst_target/devices/*/ini_groups/<acg>/addr_method
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		LUN addressing method for this ACG (access control group).
+		Read-write.
+
+What:		/sys/bus/scst_target/devices/*/ini_groups/<acg>/cpu_mask
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		CPU mask associated with this ACG. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/ini_groups/<acg>/initiators/<ini>
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Name of an initiator associated with this ACG. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/ini_groups/<acg>/initiators/luns/parameters
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the parameters supported when adding a LUN to an ACG,
+		one per line. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/ini_groups/<acg>/initiators/luns/<number>
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Soft link to the SCST device associated with this LUN.
+
+What:		/sys/bus/scst_target/devices/*/io_grouping_type
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Defines whether and how to share I/O contexts. I/O context
+		sharing may improve I/O performance significantly when using
+		the CFQ I/O scheduler and multithreaded I/O processing.
+		The allowed values for this parameter are:
+		* "auto"		Use one I/O context per initiator.
+		* "this_group_only"		Use the same I/O context for all sessions
+								associated with this target.
+		* "never"		Never share I/O contexts.
+		* <I/O context number> Share an I/O context over all targets
+				that have this I/O context number. Must
+						be a number above zero.
+		Read-write.
+
+What:		/sys/bus/scst_target/devices/*/luns/parameters
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the parameters supported when adding a LUN to a target,
+		one per line. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/luns/<number>/device
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Soft link to the exported SCST device. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/luns/<number>/read_only
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether this LUN is read-only (1) or read-write (0). Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/active_commands
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Number of SCSI commands being executed for the device
+		associated with this session. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/commands
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Number of SCSI commands being executed for this session.
+		Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/force_close
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Attribute that allows to forcibly close a session. Optional,
+		write-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/initiator_name
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Session name. For most target drivers this is a name that
+		identifies the initiator. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/latency
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		If CONFIG_SCST_MEASURE_LATENCY has been enabled, latency
+		statistics for this session. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/lun<number>/active_commands
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Number of active commands. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/lun<number>/latency
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Latency statistics. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/luns/parameters
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the parameters that may be specified when adding a
+		LUN, one per line. Read-only.
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/luns/<number>/device
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Soft link to the SCST device that is exported via this LUN. An
+		example:
+		$ readlink /sys/bus/scst_target/devices/scst_local_tgt/sessions/scst_local_host/luns/0/device
+		../../../disk01
+
+What:		/sys/bus/scst_target/devices/*/sessions/<session>/luns/<number>/read_only
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether a LUN has been exported read-only (1) or read-write (0).
+		Read-only.
+
+What:		/sys/bus/scst_target/devices/*/rel_tgt_id
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCSI Relative Target Port Identifier, which is used by e.g.
+		persistent reservation commands. Read-write.
diff --git a/Documentation/ABI/stable/sysfs-devices-scst_target-scst_local b/Documentation/ABI/stable/sysfs-devices-scst_target-scst_local
new file mode 100644
index 0000000..c67c950
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_target-scst_local
@@ -0,0 +1,18 @@
+What:		/sys/bus/scst_target/devices/scst_local/phys_transport_version
+Date:		December 2010
+Contact:	Richard Sharpe <realrichardsharpe@gmail.com>
+Description:
+		SCSI physical transport version. Read-write.
+
+What:		/sys/bus/scst_target/devices/scst_local/scsi_transport_version
+Date:		December 2010
+Contact:	Richard Sharpe <realrichardsharpe@gmail.com>
+Description:
+		SCSI transport version. Read-write.
+
+What:		/sys/bus/scst_target/devices/scst_local/sessions/*/transport_id
+Date:		December 2010
+Contact:	Richard Sharpe <realrichardsharpe@gmail.com>
+Description:
+		SCSI transport ID in binary format. Necessary e.g. for
+		implementing persistent reservation support. Read-write.
diff --git a/Documentation/ABI/stable/sysfs-driver-scst_target b/Documentation/ABI/stable/sysfs-driver-scst_target
new file mode 100644
index 0000000..0c2b6a1
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_target
@@ -0,0 +1,59 @@
+What:		/sys/bus/scst_target/drivers/*/add_target
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether or not dynamic creation and removal of SCSI targets is
+		supported by a particular SCSI target driver. The value 1
+		means that dynamic target creation/removal is supported
+		and the value 0 means that dynamic target creation/removal is
+		not supported. Read-only.
+
+What:		/sys/bus/scst_target/drivers/*/add_target_parameters
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the parameters that may be specified at target
+		creation time. Each parameter name appears on a separate
+		line. This file only exists if dynamic target creation and
+		removal is supported. Read-only.
+
+What:		/sys/bus/scst_target/drivers/*/driver_attributes
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the SCSI target driver attributes that may be created
+		or removed dynamically. Each attribute name appears on a
+		separate line. This file only exists if dynamic target driver
+		attribute creation and removal is supported. Read-only.
+
+What:		/sys/bus/scst_target/drivers/*/enabled
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Allows to enable or disable the operation of a SCSI target
+		driver. The value 1 means enabled and 0 means disabled.
+		Defaults to 0 (disabled). This allows to configure a target
+		driver before it becomes operational. Optional / read-write.
+
+What:		/sys/bus/scst_target/drivers/*/target_attributes
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the SCSI target attributes that may be created and/or
+		removed dynamically. Each attribute name appears on a separate
+		line. This file only exists if dynamic target attribute
+		creation and removal is supported. Read-only.
+
+What:		/sys/bus/scst_target/drivers/*/version
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Target driver version and build options. The driver version
+		and build date appear on the first line separated by a
+		slash and the build options appear on subsequent
+		lines. Read-only. An example:
+
+		$ cat /sys/bus/scst_target/drivers/scst_local/version
+		1.0.0/20100910
+		TRACING
+		DEBUG
diff --git a/Documentation/ABI/stable/sysfs-driver-scst_target-scst_local b/Documentation/ABI/stable/sysfs-driver-scst_target-scst_local
new file mode 100644
index 0000000..56e50f7
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_target-scst_local
@@ -0,0 +1,11 @@
+What:		/sys/bus/scst_target/drivers/scst_local/stats
+Date:		December 2010
+Contact:	Richard Sharpe <realrichardsharpe@gmail.com>
+Description:
+		Statistics about processing of SCSI commands received via the
+		Linux SCSI initiator: the number of SCSI commands that have
+		been aborted, the number of SCSI device resets and the number
+		of SCSI target resets. Read-only. An example:
+
+		# cat /sys/bus/scst_target/drivers/scst_local/stats
+		Aborts: 0, Device Resets: 0, Target Resets: 0
diff --git a/Documentation/scst/README.scst b/Documentation/scst/README.scst
index 333daa5..7c16d5c 100644
--- a/Documentation/scst/README.scst
+++ b/Documentation/scst/README.scst
@@ -357,104 +357,6 @@ Each SGV cache's subdirectory has the following item:
 
  - stats - file containing statistics for this SGV caches.
 
-"Targets" subdirectory contains subdirectories for each SCST target.
-
-Content of each target's subdirectory is target specific. See
-documentation for your target for more info about it as well as
-SysfsRules file for more info about common to all targets rules.
-Every target should have at least the following entries:
-
- - ini_groups - subdirectory, which contains and allows to define
-   initiator-oriented access control information, see below.
-
- - luns - subdirectory, which contains list of available LUNs in the
-   target-oriented access control and allows to define it, see below.
-
- - sessions - subdirectory containing connected to this target sessions.
-
- - enabled - using this attribute you can enable or disable this target/
-   It allows to finish configuring it before it starts accepting new
-   connections. 0 by default.
-
- - addr_method - used LUNs addressing method. Possible values:
-   "Peripheral" and "Flat". Most initiators work well with Peripheral
-   addressing method (default), but some (HP-UX, for instance) may
-   require Flat method. This attribute is also available in the
-   initiators security groups, so you can assign the addressing method
-   on per-initiator basis.
-
- - cpu_mask - defines CPU affinity mask for threads serving this target.
-   For threads serving LUNs it is used only for devices with
-   threads_pool_type "per_initiator".
-
- - io_grouping_type - defines how I/O from sessions to this target are
-   grouped together. This I/O grouping is very important for
-   performance. By setting this attribute in a right value, you can
-   considerably increase performance of your setup. This grouping is
-   performed only if you use CFQ I/O scheduler on the target and for
-   devices with threads_num >= 0 and, if threads_num > 0, with
-   threads_pool_type "per_initiator". Possible values:
-   "this_group_only", "never", "auto", or I/O group number >0. When the
-   value is "this_group_only" all I/O from all sessions in this target
-   will be grouped together. When the value is "never", I/O from
-   different sessions will not be grouped together, i.e. all sessions in
-   this target will have separate dedicated I/O groups. When the value
-   is "auto" (default), all I/O from initiators with the same name
-   (iSCSI initiator name, for instance) in all targets will be grouped
-   together with a separate dedicated I/O group for each initiator name.
-   For iSCSI this mode works well, but other transports usually use
-   different initiator names for different sessions, so using such
-   transports in MPIO configurations you should either use value
-   "this_group_only", or an explicit I/O group number. This attribute is
-   also available in the initiators security groups, so you can assign
-   the I/O grouping on per-initiator basis. See below for more info how
-   to use this attribute.
-
- - rel_tgt_id - allows to read or write SCSI Relative Target Port
-   Identifier attribute. This identifier is used to identify SCSI Target
-   Ports by some SCSI commands, mainly by Persistent Reservations
-   commands. This identifier must be unique among all SCST targets, but
-   for convenience SCST allows disabled targets to have not unique
-   rel_tgt_id. In this case SCST will not allow to enable this target
-   until rel_tgt_id becomes unique. This attribute initialized unique by
-   SCST by default.
-
-A target driver may have also the following entries:
-
- - "hw_target" - if the 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), this read only attribute for all hardware targets will
-    exist and contain value 1.
-
-Subdirectory "sessions" contains one subdirectory for each connected
-session with name equal to name of the connected initiator.
-
-Each session subdirectory contains the following entries:
-
- - initiator_name - contains initiator name
-
- - force_close - optional write-only attribute, which allows to force
-   close this session.
-
- - active_commands - contains number of active, i.e. not yet or being
-   executed, SCSI commands in this session.
-
- - commands - contains overall number of SCSI commands in this session.
-
- - latency - if CONFIG_SCST_MEASURE_LATENCY enabled, contains latency
-   statistics for this session.
-
- - luns - a link pointing out to the corresponding LUNs set (security
-   group) where this session was attached to.
-
- - One or more "lunX" subdirectories, where 'X' is a number, for each LUN
-   this session has (see below).
-
- - other target driver specific attributes and subdirectories.
-
-See below description of the VDISK's sysfs interface for samples.
-
 
 Access and devices visibility management (LUN masking)
 ------------------------------------------------------
diff --git a/Documentation/scst/SysfsRules b/Documentation/scst/SysfsRules
index 2e594bd..5790511 100644
--- a/Documentation/scst/SysfsRules
+++ b/Documentation/scst/SysfsRules
@@ -60,69 +60,6 @@ the management commands can be revealed by reading that attribute. An example:
 [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
 =============================
 
-- 
1.7.1

Re: [PATCHv2 2/3] [SCSI] scst: Move device docs to Documentation/ABI

[Bart Van Assche]

Move the documentation about the sysfs attributes of the SCST
virtual device to Documentation/ABI/stable.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Greg Kroah-Hartman <gregkh@suse.de>
Cc: Vladislav Bolkhovitin <vst@vlnb.net>
Cc: Richard Sharpe <realrichardsharpe@gmail.com>
---
 Documentation/ABI/stable/sysfs-devices-scst |  142 +++++++++++++++++++++++++++
 Documentation/scst/README.scst              |   71 -------------
 2 files changed, 142 insertions(+), 71 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-devices-scst

diff --git a/Documentation/ABI/stable/sysfs-devices-scst b/Documentation/ABI/stable/sysfs-devices-scst
new file mode 100644
index 0000000..03972c4
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst
@@ -0,0 +1,142 @@
+What:		/sys/devices/scst/mgmt
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Interface through which SCST management commands can be issued.
+		The documentation of the syntax of these commands can be
+		obtained by reading this file:
+
+		# cat mgmt
+		in device/<dev> <dev_cmd>
+		in device_driver/<devt> <devt_cmd>
+		in target_driver/<tgtt> <tgtt_cmd>
+		in target_driver/<tgtt>/<target>/luns <tgt_cmd>
+		in target_driver/<tgtt>/<target>/luns <luns_cmd>
+		in target_driver/<tgtt>/<target>/ini_groups <acg_mgmt_cmd>
+		in target_driver/<tgtt>/<target>/ini_groups/<acg> <acg_cmd>
+		in target_driver/<tgtt>/<target>/ini_groups/<acg>/luns <luns_cmd>
+		in target_driver/<tgtt>/<target>/ini_groups/<acg>/initiators <acg_ini_cmd>
+
+		dev_cmd syntax:
+
+		set_filename <filename>
+		set_threads_num <n>
+		set_thread_pool_type <thread_pool_type>
+
+		devt_cmd syntax:
+
+		add_device device_name [parameters]
+		del_device device_name
+		add_attribute <attribute> <value>
+		del_attribute <attribute> <value>
+		add_device_attribute device_name <attribute> <value>
+		del_device_attribute device_name <attribute> <value>
+
+		devt_cmd syntax for pass-through device types:
+
+		add_device H:C:I:L
+		del_device H:C:I:L
+
+		tgtt_cmd syntax:
+
+		add_target target_name [parameters]
+		del_target target_name
+		add_attribute <attribute> <value>
+		del_attribute <attribute> <value>
+		add_target_attribute target_name <attribute> <value>"
+		del_target_attribute target_name <attribute> <value>"
+
+		where parameters is one or more <name>=<value> pairs separated by ';'
+
+		tgt_cmd syntax:
+
+		enable
+		disable
+		set_cpu_mask <mask>
+
+		luns_cmd syntax:
+
+		add|del H:C:I:L lun [parameters]
+		add VNAME lun [parameters]
+		del lun
+		replace H:C:I:L lun [parameters]
+		replace VNAME lun [parameters]
+		clear
+
+		where parameters is either 'read_only' or empty.
+
+		acg_mgmt_cmd syntax:
+
+		create <group_name>
+		del <group_name>
+
+		acg_cmd syntax:
+		set_cpu_mask <mask>
+
+		acg_ini_cmd syntax:
+
+		add <initiator_name>
+		del <initiator_name>
+		move <initiator_name> <dest_group_name>
+		clear
+
+What:		/sys/devices/scst/setup_id
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCST setup ID. Allows to identify otherwise identical SCST
+		setups on different systems. Makes the IDs and SNs of
+		otherwise identical SCST devices unique. As an example,	the
+		vdisk device handler uses this to generate the T10 vendor
+		specific identifier and SN of vdisk devices. Read-write.
+
+What:		/sys/devices/scst/sgv/global_stats
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Global SGV (scatter/gather vector) cache statistics. Read-only.
+		An example:
+
+		$ cat sgv/global_stats
+		Inactive/active pages		0/0
+		Hi/lo watermarks [pages]		62208/0
+		Hi watermark releases/failures		0/0
+		Other allocs		0
+
+What:		/sys/devices/scst/sgv/sgv/stats
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Statistics for the regular SGV cache. Read-only.
+
+What:		/sys/devices/scst/sgv/sgv-clust/stats
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Statistics for the clustering SGV cache. Read-only.
+
+What:		/sys/devices/scst/sgv/sgv-dma/stats
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Statistics for the DMA SGV cache. Read-only.
+
+What:		/sys/devices/scst/threads
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Number of global I/O threads. Global I/O threads are used by
+		asynchronous device handlers, e.g. the vdisk blockio handler.
+		Read-write.
+
+What:		/sys/devices/scst/version
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCST version (first line) and compile-time configuration
+		(subsequent lines). Read-only. An example:
+
+		$ cat /sys/devices/scst/version
+		2.0.0
+		TRACING
+		DEBUG
diff --git a/Documentation/scst/README.scst b/Documentation/scst/README.scst
index 7c16d5c..d098c3b 100644
--- a/Documentation/scst/README.scst
+++ b/Documentation/scst/README.scst
@@ -253,45 +253,6 @@ SCST sysfs interface
 Root of SCST sysfs interface is /sys/kernel/scst_tgt. It has the
 following entries:
 
- - devices - this is a root subdirectory for all SCST devices
-
- - handlers - this is a root subdirectory for all SCST dev handlers
-
- - sgv - this is a root subdirectory for all SCST SGV caches
-
- - targets - this is a root subdirectory for all SCST targets
-
- - setup_id - allows to read and write SCST setup ID. This ID can be
-   used in cases, when the same SCST configuration should be installed
-   on several targets, but exported from those targets devices should
-   have different IDs and SNs. For instance, VDISK dev handler uses this
-   ID to generate T10 vendor specific identifier and SN of the devices.
-
- - threads - allows to read and set number of global SCST I/O threads.
-   Those threads used with async. dev handlers, for instance, vdisk
-   BLOCKIO or NULLIO.
-
- - trace_level - allows to enable and disable various tracing
-   facilities. See content of this file for help how to use it.
-
- - version - read-only attribute, which allows to see version of
-   SCST and enabled optional features.
-
- - last_sysfs_mgmt_res - read-only attribute returning completion status
-   of the last management command. In the sysfs implementation there are
-   some problems between internal sysfs and internal SCST locking. To
-   avoid them in some cases sysfs calls can return error with errno
-   EAGAIN. This doesn't mean the operation failed. It only means that
-   the operation queued and not yet completed. To wait for it to
-   complete, an management tool should poll this file. If the operation
-   hasn't yet completed, it will also return EAGAIN. But after it's
-   completed, it will return the result of this operation (0 for success
-   or -errno for error).
-
-Each SCST sysfs file (attribute) can contain in the last line mark
-"[key]". It is automatically added mark used to allow scstadmin to see
-which attributes it should save in the config file. You can ignore it.
-
 "Devices" subdirectory contains subdirectories for each SCST devices.
 
 Content of each device's subdirectory is dev handler specific. See
@@ -325,38 +286,6 @@ SCST dev handlers can have the following common entries:
 See below for more information about other entries of this subdirectory
 of the standard SCST dev handlers.
 
-"Handlers" subdirectory contains subdirectories for each SCST dev
-handler.
-
-Content of each handler's subdirectory is dev handler specific. See
-documentation for your dev handlers for more info about it as well as
-SysfsRules file for more info about common to all dev handlers rules.
-SCST dev handlers can have the following common entries:
-
- - mgmt - this entry allows to create virtual devices and their
-   attributes (for virtual devices dev handlers) or assign/unassign real
-   SCSI devices to/from this dev handler (for pass-through dev
-   handlers).
-
- - trace_level - allows to enable and disable various tracing
-   facilities. See content of this file for help how to use it.
-
- - type - SCSI type of devices served by this dev handler.
-
-See below for more information about other entries of this subdirectory
-of the standard SCST dev handlers.
-
-"Sgv" subdirectory contains statistic information of SCST SGV caches. It
-has the following entries:
-
- - None, one or more subdirectories for each existing SGV cache.
-
- - global_stats - file containing global SGV caches statistics.
-
-Each SGV cache's subdirectory has the following item:
-
- - stats - file containing statistics for this SGV caches.
-
 
 Access and devices visibility management (LUN masking)
 ------------------------------------------------------
-- 
1.7.1

Re: [PATCHv2 3/3] [SCSI] scst: Move devices doc to Documentation/ABI

[Bart Van Assche]

Move the documentation about the sysfs attributes of the SCST
pass-through and virtual devices to Documentation/ABI/stable.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Greg Kroah-Hartman <gregkh@suse.de>
Cc: Vladislav Bolkhovitin <vst@vlnb.net>
Cc: Richard Sharpe <realrichardsharpe@gmail.com>
---
 .../ABI/stable/sysfs-devices-scst_tgt_dev          |  136 ++++++++++++++++++++
 Documentation/ABI/stable/sysfs-driver-scst_tgt_dev |   27 ++++
 Documentation/scst/README.scst                     |  106 ---------------
 3 files changed, 163 insertions(+), 106 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-devices-scst_tgt_dev
 create mode 100644 Documentation/ABI/stable/sysfs-driver-scst_tgt_dev

diff --git a/Documentation/ABI/stable/sysfs-devices-scst_tgt_dev b/Documentation/ABI/stable/sysfs-devices-scst_tgt_dev
new file mode 100644
index 0000000..cfa791e
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_tgt_dev
@@ -0,0 +1,136 @@
+What:		/sys/bus/scst_tgt_dev/device/*/blocksize
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Block size used by the virtual device. Must be a power of two
+		and equal to or above 512. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/exported/export<nr>
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Zero or more soft links to the LUNs through which this device
+		has been exported. An example:
+
+		$ readlink /sys/bus/scst_tgt_dev/devices/disk01/exported/export0
+		../../scst_local_tgt/luns/0
+
+What:		/sys/bus/scst_tgt_dev/device/*/filename
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For virtual devices, the absolute path of the associated file
+		or device. Read-only. An example:
+
+		# cat /sys/devices/disk01/filename
+		/dev/sdc
+		[key]
+
+What:		/sys/bus/scst_tgt_dev/device/*/nv_cache
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		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. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/o_direct
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		The value 1 means that all caching has been disabled for
+		a virtual device (direct I/O) and the value 0 means that caching
+		is enabled. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/read_only
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For virtual devices, whether or not to deny write commands.
+		Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/removable
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For virtual devices, whether or not the underlying storage
+		medium is removable. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/resync_size
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For virtual devices, writing to this attribute will update the
+		internally cached device size. Write-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/scsi_device
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For SCSI devices, the device identification. Read-only. An
+		example:
+
+		$ cat /sys/bus/scst_tgt_dev/devices/1:0:0:0/scsi_device
+		1:0:0:0
+
+What:		/sys/bus/scst_tgt_dev/device/*/size_mb
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		For virtual devices, the internally cached size in MB of the
+		underlying storage device. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/t10_dev_id
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCSI device ID associated with the virtual device. This is the
+		ID reported e.g. via the Device Identification page (0x83) of
+		the INQUIRY command. Read-write.
+
+What:		/sys/bus/scst_tgt_dev/device/*/thin_provisioned
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether or not the virtual device supports thin provisioning,
+		or in other words, that remote initiators can mark storage as
+		unallocated. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/threads_num
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Number of threads in the thread pool that is used for
+		processing SCSI commands for this device. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/threads_pool_type
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether to use a distinct thread pool per initiator
+		("per_initiator") or one thread pool for all initiators
+		accessing this device ("shared"). Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/type
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCSI type of this device. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/usn
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Unique serial number as reported e.g. by the SCSI INQUIRY
+		response. Read-only.
+
+What:		/sys/bus/scst_tgt_dev/device/*/write_through
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Whether or not write-back caching has been disabled for a
+		virtual device. The value 0 stands for write-back mode and the
+		value 1 stands for write-through mode. Read-only.
diff --git a/Documentation/ABI/stable/sysfs-driver-scst_tgt_dev b/Documentation/ABI/stable/sysfs-driver-scst_tgt_dev
new file mode 100644
index 0000000..c79aee0
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_tgt_dev
@@ -0,0 +1,27 @@
+What:		/sys/bus/scst_tgt_dev/drivers/*/add_device_parameters
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		Names of the parameters supported when adding a device. Each
+		parameter name appears on a separate line. Read-only.
+		An example:
+
+		$ cat /sys/bus/scst_tgt_dev/drivers/vdisk_fileio/add_device_parameters
+		filename
+		blocksize
+		write_through
+		nv_cache
+		o_direct
+		read_only
+		removable
+		thin_provisioned
+
+What:		/sys/bus/scst_tgt_dev/drivers/*/type
+Date:		December 2010
+Contact:	Bart Van Assche <bvanassche@acm.org>
+Description:
+		SCSI type of the devices managed by this driver. Read-only.
+		An example:
+
+		$ cat /sys/bus/scst_tgt_dev/drivers/vcdrom/type
+		5 - CD-ROM device
diff --git a/Documentation/scst/README.scst b/Documentation/scst/README.scst
index d098c3b..27e2a0c 100644
--- a/Documentation/scst/README.scst
+++ b/Documentation/scst/README.scst
@@ -571,112 +571,6 @@ echo "add_device disk1 filename=/disk1; blocksize=4096; nv_cache=1" >/sys/kernel
 will create a FILEIO virtual device disk1 with backend file /disk1
 with block size 4K and NV_CACHE enabled.
 
-Each vdisk_fileio's device has the following attributes in
-/sys/kernel/scst_tgt/devices/device_name:
-
- - filename - contains path and file name of the backend file.
-
- - blocksize - contains block size used by this virtual device.
-
- - write_through - contains status of write back caching of this virtual
-   device.
-
- - read_only - contains read only status of this virtual device.
-
- - o_direct - contains O_DIRECT status of this virtual device.
-
- - nv_cache - contains NV_CACHE status of this virtual device.
-
- - thin_provisioned - contains thin provisioning status of this virtual
-   device
-
- - removable - contains removable status of this virtual device.
-
- - size_mb - contains size of this virtual device in MB.
-
- - t10_dev_id - contains and allows to set T10 vendor specific
-   identifier for Device Identification VPD page (0x83) of INQUIRY data.
-   By default VDISK handler always generates t10_dev_id for every new
-   created device at creation time based on the device name and
-   scst_vdisk_ID scst_vdisk.ko module parameter (see below).
-
- - usn - contains the virtual device's serial number of INQUIRY data. It
-   is created at the device creation time based on the device name and
-   scst_vdisk_ID scst_vdisk.ko module parameter (see below).
-
- - type - contains SCSI type of this virtual device.
-
- - resync_size - write only attribute, which makes vdisk_fileio to
-   rescan size of the backend file. It is useful if you changed it, for
-   instance, if you resized it.
-
-For example:
-
-/sys/kernel/scst_tgt/devices/disk1
-|-- blocksize
-|-- exported
-|   |-- export0 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/luns/0
-|   |-- export1 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt/ini_groups/INI/luns/0
-|   |-- export2 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/luns/0
-|   |-- export3 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI1/luns/0
-|   |-- export4 -> ../../../targets/iscsi/iqn.2006-10.net.vlnb:tgt1/ini_groups/INI2/luns/0
-|-- filename
-|-- handler -> ../../handlers/vdisk_fileio
-|-- nv_cache
-|-- o_direct
-|-- read_only
-|-- removable
-|-- resync_size
-|-- size_mb
-|-- t10_dev_id
-|-- thin_provisioned
-|-- threads_num
-|-- threads_pool_type
-|-- type
-|-- usn
-`-- write_through
-
-Each vdisk_blockio's device has the following attributes in
-/sys/kernel/scst_tgt/devices/device_name: blocksize, filename, nv_cache,
-read_only, removable, resync_size, size_mb, t10_dev_id,
-thin_provisioned, threads_num, threads_pool_type, type, usn. See above
-description of those parameters.
-
-Each vdisk_nullio's device has the following attributes in
-/sys/kernel/scst_tgt/devices/device_name: blocksize, read_only,
-removable, size_mb, t10_dev_id, threads_num, threads_pool_type, type,
-usn. See above description of those parameters.
-
-Each vcdrom's device has the following attributes in
-/sys/kernel/scst_tgt/devices/device_name: filename, size_mb,
-t10_dev_id, threads_num, threads_pool_type, type, usn. See above
-description of those parameters. Exception is filename attribute. For
-vcdrom it is writable. Writing to it allows to virtually insert or
-change virtual CD media in the virtual CDROM device. For example:
-
- - echo "/image.iso" >/sys/kernel/scst_tgt/devices/cdrom/filename - will
-   insert file /image.iso as virtual media to the virtual CDROM cdrom.
-
- - echo "" >/sys/kernel/scst_tgt/devices/cdrom/filename - will remove
-   "media" from the virtual CDROM cdrom.
-
-Additionally VDISK handler has module parameter "num_threads", which
-specifies count of I/O threads for each FILEIO VDISK's or VCDROM device.
-If you have a workload, which tends to produce rather random accesses
-(e.g. DB-like), you should increase this count to a bigger value, like
-32. If you have a rather sequential workload, you should decrease it to
-a lower value, like number of CPUs on the target or even 1. Due to some
-limitations of Linux I/O subsystem, increasing number of I/O threads too
-much leads to sequential performance drop, especially with deadline
-scheduler, so decreasing it can improve sequential performance. The
-default provides a good compromise between random and sequential
-accesses.
-
-You shouldn't be afraid to have too many VDISK I/O threads if you have
-many VDISK devices. Kernel threads consume very little amount of
-resources (several KBs) and only necessary threads will be used by SCST,
-so the threads will not trash your system.
-
 CAUTION: If you partitioned/formatted your device with block size X, *NEVER*
 ======== ever try to export and then mount it (even accidentally) with another
          block size. Otherwise you can *instantly* damage it pretty
-- 
1.7.1