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

[PATCH 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.

[PATCH 1/3] [SCSI] scst: Move target sysfs documentation 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 |  213 ++++++++++++++++++++
 .../stable/sysfs-devices-scst_target-scst_local    |   21 ++
 Documentation/ABI/stable/sysfs-driver-scst_target  |   65 ++++++
 .../ABI/stable/sysfs-driver-scst_target-scst_local |   12 +
 Documentation/scst/README.scst                     |   98 ---------
 Documentation/scst/SysfsRules                      |   63 ------
 6 files changed, 311 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..7e920f9
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_target
@@ -0,0 +1,213 @@
+What:           /sys/bus/scst_target/devices/*/addr_method
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Target-specific CPU mask. Read-only.
+
+What:           /sys/bus/scst_target/devices/*/force_close
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		CPU mask associated with this ACG. Read-only.
+
+What:           /sys/bus/scst_target/devices/*/ini_groups/<acg>/initiators/<ini>
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Soft link to the SCST device associated with this LUN.
+
+What:           /sys/bus/scst_target/devices/*/io_grouping_type
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Soft link to the exported SCST device. Read-only.
+
+What:           /sys/bus/scst_target/devices/*/luns/<number>/read_only
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Number of active commands. Read-only.
+
+What:           /sys/bus/scst_target/devices/*/sessions/<session>/lun<number>/latency
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Latency statistics. Read-only.
+
+What:           /sys/bus/scst_target/devices/*/sessions/<session>/luns/parameters
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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..c659c60
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_target-scst_local
@@ -0,0 +1,21 @@
+What:           /sys/bus/scst_target/devices/scst_local/phys_transport_version
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		SCSI physical transport version. Read-write.
+
+What:           /sys/bus/scst_target/devices/scst_local/scsi_transport_version
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		SCSI transport version. Read-write.
+
+What:           /sys/bus/scst_target/devices/scst_local/sessions/transport_id
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+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..0d682b0
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_target
@@ -0,0 +1,65 @@
+What:           /sys/bus/scst_target/drivers/*/add_target
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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..9c85701
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_target-scst_local
@@ -0,0 +1,12 @@
+What:           /sys/bus/scst_target/drivers/scst_local/stats
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+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

[PATCH 2/3] [SCSI] scst: Move SCST device documentation 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>
---
 Documentation/ABI/stable/sysfs-devices-scst |  150 +++++++++++++++++++++++++++
 Documentation/scst/README.scst              |   71 -------------
 2 files changed, 150 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..80bc258
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst
@@ -0,0 +1,150 @@
+What:           /sys/devices/scst/mgmt
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Statistics for the regular SGV cache. Read-only.
+
+What:           /sys/devices/scst/sgv/sgv-clust/stats
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Statistics for the clustering SGV cache. Read-only.
+
+What:           /sys/devices/scst/sgv/sgv-dma/stats
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		Statistics for the DMA SGV cache. Read-only.
+
+What:           /sys/devices/scst/threads
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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

[PATCH 3/3] [SCSI] scst: Move SCST devices documentation 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>
---
 .../ABI/stable/sysfs-devices-scst_tgt_dev          |  153 ++++++++++++++++++++
 Documentation/ABI/stable/sysfs-driver-scst_tgt_dev |   29 ++++
 2 files changed, 182 insertions(+), 0 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..ab09c21
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-scst_tgt_dev
@@ -0,0 +1,153 @@
+What:           /sys/bus/scst_tgt_dev/device/*/blocksize
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.org
+Description:
+		SCSI type of this device. Read-only.
+
+What:           /sys/bus/scst_tgt_dev/device/*/usn
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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..33a9221
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-driver-scst_tgt_dev
@@ -0,0 +1,29 @@
+What:           /sys/bus/scst_tgt_dev/drivers/*/add_device_parameters
+Date:           December 2010
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
+KernelVersion:  2.6.38
+Contact:        linux-scsi@vger.kernel.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
-- 
1.7.1

Re: [PATCH 2/3] [SCSI] scst: Move SCST device documentation to Documentation/ABI

[Greg KH]

On Wed, Dec 22, 2010 at 09:46:28PM +0100, Bart Van Assche wrote:
> 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>
> ---
>  Documentation/ABI/stable/sysfs-devices-scst |  150 +++++++++++++++++++++++++++
>  Documentation/scst/README.scst              |   71 -------------
>  2 files changed, 150 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..80bc258
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-devices-scst
> @@ -0,0 +1,150 @@
> +What:           /sys/devices/scst/mgmt

How did you get a file into this directory?  Are you sure that's
acceptable?  Same for the other files you added here.

> +Date:           December 2010
> +KernelVersion:  2.6.38

Really?  That's pretty presumptious, isn't it?

> +Contact:        linux-scsi@vger.kernel.org

Why not the "owner" of this code, not the scsi mailing list.

> +Description:
> +		Interface through which SCST management commands can be issued.

You mix tabs and spaces above and in all of your other files.  Please
make them only tabs.
> +		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>

What?  sysfs is one value per file, why would the mgmt file return more
than one line?  That's not acceptable, sorry.

> +
> +		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

That's quite complex, are you sure it's correct, and actually describes
it in a manner that anyone else can use?

Again, one value per file.

thanks,

greg k-h

Re: [PATCH 2/3] [SCSI] scst: Move SCST device documentation to Documentation/ABI

[Bart Van Assche]

(resending as plain text)

On Thu, Dec 23, 2010 at 1:20 AM, Greg KH <gregkh@suse.de> wrote:
>
> On Wed, Dec 22, 2010 at 09:46:28PM +0100, Bart Van Assche wrote:
> > 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>
> > ---
> >  Documentation/ABI/stable/sysfs-devices-scst |  150 +++++++++++++++++++++++++++
> >  Documentation/scst/README.scst              |   71 -------------
> >  2 files changed, 150 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..80bc258
> > --- /dev/null
> > +++ b/Documentation/ABI/stable/sysfs-devices-scst
> > @@ -0,0 +1,150 @@
> > +What:           /sys/devices/scst/mgmt
>
> How did you get a file into this directory?  Are you sure that's
> acceptable?  Same for the other files you added here.

Hello Greg,

All that was needed to create the entry /sys/devices/scst/mgmt was to
call device_register() for the device with the name "scst" and
device_create_file() for the attribute called "mgmt". We are not aware
of any documentation that disallows creating files there. So whether
or not creating a file there is acceptable is something we can't know
if the kernel maintainers do not speak up.

> > +Date:           December 2010
> > +KernelVersion:  2.6.38
>
> Really?  That's pretty presumptious, isn't it?
>
> > +Contact:        linux-scsi@vger.kernel.org
>
> Why not the "owner" of this code, not the scsi mailing list.
>
> > +Description:
> > +             Interface through which SCST management commands can be issued.
>
> You mix tabs and spaces above and in all of your other files.  Please
> make them only tabs.

Will address the above comments.

> > +             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>
>
> What?  sysfs is one value per file, why would the mgmt file return more
> than one line?  That's not acceptable, sorry.

As far as I understood the sysfs philosophy, the intention of the one
value per file rule is to avoid that software reading data from sysfs
files has to parse what it reads. The above data is documentation only
and is not intended to be parsed by software. So that file could be
left empty, but that would not be very helpful for users who configure
SCST by issuing shell commands instead of using the scstadmin tool.
I'm not sure though how to proceed here.

> > +
> > +             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
>
> That's quite complex, are you sure it's correct, and actually describes
> it in a manner that anyone else can use?

More detailed documentation of these commands is present in
Documentation/scst/README.scst. Should that documentation be moved to
Documentation/ABI/stable/sysfs-devices-scst too ?

Bart.
--
To unsubscribe from this list: send the line "unsubscribe linux-scsi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 3/3] [SCSI] scst: Move SCST devices documentation to Documentation/ABI

[Konrad Rzeszutek Wilk]

> +
> +What:           /sys/bus/scst_tgt_dev/device/*/exported/export<nr>
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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]

Key?
> +
> +What:           /sys/bus/scst_tgt_dev/device/*/nv_cache
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.org
> +Description:
> +		For virtual devices, whether or not to deny write commands.
> +		Read-only.

So earlier on (in o_direct) you mentioned the proper values (0 or 1). Would it 
make sense to have that here too?

> +
> +What:           /sys/bus/scst_tgt_dev/device/*/removable
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.org
> +Description:
> +		For virtual devices, whether or not the underlying storage
> +		medium is removable. Read-only.

Ditto.
> +
> +What:           /sys/bus/scst_tgt_dev/device/*/resync_size
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.org
> +Description:
> +		For virtual devices, writing to this attribute will update the
> +		internally cached device size. Write-only.

Is this in kB or bytes or pages?
> +
> +What:           /sys/bus/scst_tgt_dev/device/*/scsi_device
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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.

Wouldn't you want to be able to toggle that? Say if the device does support 
thin provisioning but you want to disable it?
> +
> +What:           /sys/bus/scst_tgt_dev/device/*/threads_num
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.org
> +Description:
> +		Whether to use a distinct thread pool per initiator

Whether would imply you can change the allocation. It sounds however you are 
just told what it is. Perhaps "What type of thread pool pool is used 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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.org
> +Description:
> +		SCSI type of this device. Read-only.
> +
> +What:           /sys/bus/scst_tgt_dev/device/*/usn
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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..33a9221
> --- /dev/null
> +++ b/Documentation/ABI/stable/sysfs-driver-scst_tgt_dev
> @@ -0,0 +1,29 @@
> +What:           /sys/bus/scst_tgt_dev/drivers/*/add_device_parameters
> +Date:           December 2010
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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
> +KernelVersion:  2.6.38
> +Contact:        linux-scsi@vger.kernel.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

Re: [PATCH 3/3] [SCSI] scst: Move SCST devices documentation to Documentation/ABI

[Bart Van Assche]

On Thu, Dec 23, 2010 at 4:11 PM, Konrad Rzeszutek Wilk
<konrad@darnok.org> wrote:
>
> > +
> > +What:           /sys/bus/scst_tgt_dev/device/*/exported/export<nr>
> > +Date:           December 2010
> > +KernelVersion:  2.6.38
> > +Contact:        linux-scsi@vger.kernel.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
> > +KernelVersion:  2.6.38
> > +Contact:        linux-scsi@vger.kernel.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]
>
> Key?
>
> [ ... ]

Hello Konrad,

Thanks for the feedback. I'll do by best to clarify the documentation
according to your remarks.

Regarding the "[key]" indicator on the second line: that is an
indicator that is either present or absent. That indicator is only
used by a user-space tool (scstadmin) to find out which sysfs
attributes differ from their default value. That indicator makes it
possible to minimize the amount of information to be saved when making
the SCST state persistent.

Bart.
--
To unsubscribe from this list: send the line "unsubscribe linux-scsi" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html