* Re: [PATCHv2 1/3] [SCSI] scst: Move target docs to Documentation/ABI
2010-12-23 18:56 [PATCHv2 0/3] Move SCST sysfs documentation to Documentation/ABI Bart Van Assche
@ 2010-12-23 18:57 ` Bart Van Assche
2010-12-23 18:58 ` [PATCHv2 2/3] [SCSI] scst: Move device " Bart Van Assche
2010-12-23 18:58 ` [PATCHv2 3/3] [SCSI] scst: Move devices doc " Bart Van Assche
2 siblings, 0 replies; 4+ messages in thread
From: Bart Van Assche @ 2010-12-23 18:57 UTC (permalink / raw)
To: linux-scsi; +Cc: Greg Kroah-Hartman, Vladislav Bolkhovitin, Richard Sharpe
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCHv2 2/3] [SCSI] scst: Move device docs to Documentation/ABI
2010-12-23 18:56 [PATCHv2 0/3] Move SCST sysfs documentation to Documentation/ABI Bart Van Assche
2010-12-23 18:57 ` [PATCHv2 1/3] [SCSI] scst: Move target docs " Bart Van Assche
@ 2010-12-23 18:58 ` Bart Van Assche
2010-12-23 18:58 ` [PATCHv2 3/3] [SCSI] scst: Move devices doc " Bart Van Assche
2 siblings, 0 replies; 4+ messages in thread
From: Bart Van Assche @ 2010-12-23 18:58 UTC (permalink / raw)
To: linux-scsi; +Cc: Greg Kroah-Hartman, Vladislav Bolkhovitin, Richard Sharpe
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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCHv2 3/3] [SCSI] scst: Move devices doc to Documentation/ABI
2010-12-23 18:56 [PATCHv2 0/3] Move SCST sysfs documentation to Documentation/ABI Bart Van Assche
2010-12-23 18:57 ` [PATCHv2 1/3] [SCSI] scst: Move target docs " Bart Van Assche
2010-12-23 18:58 ` [PATCHv2 2/3] [SCSI] scst: Move device " Bart Van Assche
@ 2010-12-23 18:58 ` Bart Van Assche
2 siblings, 0 replies; 4+ messages in thread
From: Bart Van Assche @ 2010-12-23 18:58 UTC (permalink / raw)
To: linux-scsi; +Cc: Greg Kroah-Hartman, Vladislav Bolkhovitin, Richard Sharpe
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
^ permalink raw reply related [flat|nested] 4+ messages in thread