[PATCH] scsi: Document generic scsi device attributes

[PATCH] scsi: Document generic scsi device attributes

[Stephen M. Cameron]

From: Stephen M. Cameron <scameron@beardog.cce.hp.com>

Signed-off-by: Stephen M. Cameron <scameron@beardog.cce.hp.com>
---
 Documentation/ABI/testing/sysfs-class-scsi_devices |  123 ++++++++++++++++++++
 1 files changed, 123 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-class-scsi_devices

diff --git a/Documentation/ABI/testing/sysfs-class-scsi_devices b/Documentation/ABI/testing/sysfs-class-scsi_devices
new file mode 100644
index 0000000..ad2d36b
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
@@ -0,0 +1,123 @@
+What:           /sys/class/scsi_device/..../device/device_blocked
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer attribute indicates whether the
+		device is blocked.  A non-zero value indicates the device
+		is blocked, zero indicates the device is not blocked.
+
+What:           /sys/class/scsi_device/..../device/type
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only decimal integer value indicates the
+		SCSI device type.
+
+What:           /sys/class/scsi_device/..../device/scsi_level
+Date:           January, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only decimal integer value indicates the
+		SCSI revision level the device claims to support.
+
+What:           /sys/class/scsi_device/..../device/vendor
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the vendor of the SCSI
+		device.
+
+What:           /sys/class/scsi_device/..../device/model
+Date:           December 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the model of the SCSI
+		device.
+
+What:           /sys/class/scsi_device/..../device/rev
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the product revision
+		of the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/rescan
+Date:           March, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+
+What:           /sys/class/scsi_device/..../device/delete
+Date:           August, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		Writing to this write only attribute causes the SCSI device to
+		be removed from the SCSI midlayer.
+
+What:           /sys/class/scsi_device/..../device/state
+Date:           April, 2004
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read/write string attribute allows setting or retrieving
+		the current state of the SCSI device.  Possible values are
+		"created", "running", "cancel", "deleted", "quiesce", "offline",
+		"blocked" and "created-blocked"
+
+What:           /sys/class/scsi_device/..../device/timeout
+Date:           May, 2004
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read/write decimal integer attribute contains the number
+		of seconds which may elapse after sending a command to the
+		device before that command is considered to have timed out.
+
+What:           /sys/class/scsi_device/..../device/iocounterbits
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value shows the number of bits
+		used to represent the various I/O counters.
+
+What:           /sys/class/scsi_device/..../device/iorequest_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been submitted to the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/iodone_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been completed by the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/ioerr_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been completed with errors by the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/modalias
+Date:           April, 2007
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string value contains a string of the form
+		"scsi:t-0xXX" where "XX" are two hex digits representing the
+		SCSI device type.  See also the "type" attribute.
+

Re: [PATCH] scsi: Document generic scsi device attributes

[James Bottomley]

On Wed, 2011-08-17 at 13:20 -0500, Stephen M. Cameron wrote:
> From: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> 
> Signed-off-by: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> ---
>  Documentation/ABI/testing/sysfs-class-scsi_devices |  123 ++++++++++++++++++++
>  1 files changed, 123 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/ABI/testing/sysfs-class-scsi_devices
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-scsi_devices b/Documentation/ABI/testing/sysfs-class-scsi_devices
> new file mode 100644
> index 0000000..ad2d36b
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
> @@ -0,0 +1,123 @@
> +What:           /sys/class/scsi_device/..../device/device_blocked
> +Date:           December, 2002
> +KernelVersion:  Unknown
> +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>

Hmm, so I get fingered for every screw up in our sysfs ABI? nice wide
receiver buck pass move.

James

Re: [PATCH] scsi: Document generic scsi device attributes

[scameron]

On Wed, Aug 17, 2011 at 12:45:06PM -0700, James Bottomley wrote:
> On Wed, 2011-08-17 at 13:20 -0500, Stephen M. Cameron wrote:
> > From: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> > 
> > Signed-off-by: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> > ---
> >  Documentation/ABI/testing/sysfs-class-scsi_devices |  123 ++++++++++++++++++++
> >  1 files changed, 123 insertions(+), 0 deletions(-)
> >  create mode 100644 Documentation/ABI/testing/sysfs-class-scsi_devices
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-class-scsi_devices b/Documentation/ABI/testing/sysfs-class-scsi_devices
> > new file mode 100644
> > index 0000000..ad2d36b
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
> > @@ -0,0 +1,123 @@
> > +What:           /sys/class/scsi_device/..../device/device_blocked
> > +Date:           December, 2002
> > +KernelVersion:  Unknown
> > +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
> 
> Hmm, so I get fingered for every screw up in our sysfs ABI? nice wide
> receiver buck pass move.

Uh, sorry if that wasn't the right thing to do, which it sounds
like it wasn't.  I just put your name there because you're the SCSI
maintainer.  I can dig through all the commits and see who added what
if that's preferable.  Or leave the names out?  or something else?

-- steve

Re: [PATCH] scsi: Document generic scsi device attributes

[James Bottomley]

On Wed, 2011-08-17 at 15:00 -0500, scameron@beardog.cce.hp.com wrote:
> On Wed, Aug 17, 2011 at 12:45:06PM -0700, James Bottomley wrote:
> > On Wed, 2011-08-17 at 13:20 -0500, Stephen M. Cameron wrote:
> > > From: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> > > 
> > > Signed-off-by: Stephen M. Cameron <scameron@beardog.cce.hp.com>
> > > ---
> > >  Documentation/ABI/testing/sysfs-class-scsi_devices |  123 ++++++++++++++++++++
> > >  1 files changed, 123 insertions(+), 0 deletions(-)
> > >  create mode 100644 Documentation/ABI/testing/sysfs-class-scsi_devices
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-class-scsi_devices b/Documentation/ABI/testing/sysfs-class-scsi_devices
> > > new file mode 100644
> > > index 0000000..ad2d36b
> > > --- /dev/null
> > > +++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
> > > @@ -0,0 +1,123 @@
> > > +What:           /sys/class/scsi_device/..../device/device_blocked
> > > +Date:           December, 2002
> > > +KernelVersion:  Unknown
> > > +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
> > 
> > Hmm, so I get fingered for every screw up in our sysfs ABI? nice wide
> > receiver buck pass move.
> 
> Uh, sorry if that wasn't the right thing to do, which it sounds
> like it wasn't.  I just put your name there because you're the SCSI
> maintainer.  I can dig through all the commits and see who added what
> if that's preferable.  Or leave the names out?  or something else?

No, don't worry, the patch is the right thing to do ... I was just
slightly amused to see my name down for all of it.

James

Re: [PATCH] scsi: Document generic scsi device attributes

[Stefan Richter]

On Aug 17 James Bottomley wrote:
> On Wed, 2011-08-17 at 15:00 -0500, scameron@beardog.cce.hp.com wrote:
> > On Wed, Aug 17, 2011 at 12:45:06PM -0700, James Bottomley wrote:
> > > On Wed, 2011-08-17 at 13:20 -0500, Stephen M. Cameron wrote:
> > > > +++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
> > > > @@ -0,0 +1,123 @@
> > > > +What:           /sys/class/scsi_device/..../device/device_blocked
> > > > +Date:           December, 2002
> > > > +KernelVersion:  Unknown
> > > > +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
> > > 
> > > Hmm, so I get fingered for every screw up in our sysfs ABI? nice wide
> > > receiver buck pass move.
> > 
> > Uh, sorry if that wasn't the right thing to do, which it sounds
> > like it wasn't.  I just put your name there because you're the SCSI
> > maintainer.  I can dig through all the commits and see who added what
> > if that's preferable.  Or leave the names out?  or something else?
> 
> No, don't worry, the patch is the right thing to do ... I was just
> slightly amused to see my name down for all of it.

Isn't linux-scsi@vger.kernel.org acceptable if not even preferable
as contact?
-- 
Stefan Richter
-=====-==-== =--- =--=-
http://arcgraph.de/sr/

Re: [PATCH] scsi: Document generic scsi device attributes

[Stefan Richter]

On Aug 17 Stephen M. Cameron wrote:
> +What:           /sys/class/scsi_device/..../device/type
> +Date:           December, 2002
> +KernelVersion:  Unknown
> +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
> +Description:
> +		This read only decimal integer value indicates the
> +		SCSI device type.
> +
> +What:           /sys/class/scsi_device/..../device/scsi_level
> +Date:           January, 2003
> +KernelVersion:  Unknown
> +Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
> +Description:
> +		This read only decimal integer value indicates the
> +		SCSI revision level the device claims to support.

Perhaps a reference to the pertaining SCSI specifications would be good
to have at these two attribute descriptions.  (I am too lazy to look those
up right now though.)
-- 
Stefan Richter
-=====-==-== =--- =--=-
http://arcgraph.de/sr/

[PATCH] scsi: Document generic scsi device attributes

[Stephen M. Cameron]

From: Stephen M. Cameron <scameron@beardog.cce.hp.com>

Signed-off-by: Stephen M. Cameron <scameron@beardog.cce.hp.com>
---
 Documentation/ABI/testing/sysfs-class-scsi_devices |  130 ++++++++++++++++++++
 1 files changed, 130 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-class-scsi_devices

diff --git a/Documentation/ABI/testing/sysfs-class-scsi_devices b/Documentation/ABI/testing/sysfs-class-scsi_devices
new file mode 100644
index 0000000..cee5619
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-scsi_devices
@@ -0,0 +1,130 @@
+What:           /sys/class/scsi_device/..../device/device_blocked
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer attribute indicates whether the
+		device is blocked.  A non-zero value indicates the device
+		is blocked, zero indicates the device is not blocked.
+
+What:           /sys/class/scsi_device/..../device/type
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only decimal integer value indicates the
+		SCSI device type.  See also table 47 in section 8.2.5.1
+		"Standard INQUIRY data" of the SCSI-2 specification.
+
+What:           /sys/class/scsi_device/..../device/scsi_level
+Date:           January, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only decimal integer value indicates the
+		SCSI revision level the device claims to support.
+
+What:           /sys/class/scsi_device/..../device/vendor
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the vendor of the SCSI
+		device.
+
+What:           /sys/class/scsi_device/..../device/model
+Date:           December 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the model of the SCSI
+		device.
+
+What:           /sys/class/scsi_device/..../device/rev
+Date:           December, 2002
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string attribute contains the product revision
+		of the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/rescan
+Date:           March, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		When written to, this write-only attribute causes the 
+		target device driver to rescan the device if the target
+		driver implements any sort of rescan -- currently only the
+		sd driver does.
+
+What:           /sys/class/scsi_device/..../device/delete
+Date:           August, 2003
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		Writing to this write only attribute causes the SCSI device to
+		be removed from the SCSI midlayer.
+
+What:           /sys/class/scsi_device/..../device/state
+Date:           April, 2004
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read/write string attribute allows setting or retrieving
+		the current state of the SCSI device.  Possible values are
+		"created", "running", "cancel", "deleted", "quiesce", "offline",
+		"blocked" and "created-blocked"
+
+What:           /sys/class/scsi_device/..../device/timeout
+Date:           May, 2004
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read/write decimal integer attribute contains the number
+		of seconds which may elapse after sending a command to the
+		device before that command is considered to have timed out.
+
+What:           /sys/class/scsi_device/..../device/iocounterbits
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value shows the number of bits
+		used to represent the various I/O counters.
+
+What:           /sys/class/scsi_device/..../device/iorequest_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been submitted to the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/iodone_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been completed by the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/ioerr_cnt
+Date:           March, 2005
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only integer value indicates how many I/O requests
+		have been completed with errors by the SCSI device.
+
+What:           /sys/class/scsi_device/..../device/modalias
+Date:           April, 2007
+KernelVersion:  Unknown
+Contact:        James Bottomley <James.Bottomley@HansenPartnership.com>
+Description:
+		This read only string value contains a string of the form
+		"scsi:t-0xXX" where "XX" are two hex digits representing the
+		SCSI device type.  See also the "type" attribute and table 47
+		in section 8.2.5.1 "Standard INQUIRY data" of the SCSI-2
+		specification.
+

Re: [PATCH] scsi: Document generic scsi device attributes

[Douglas Gilbert]

On 11-08-19 10:44 AM, Stephen M. Cameron wrote:
> From: Stephen M. Cameron<scameron@beardog.cce.hp.com>
>

<snip>

> +What:           /sys/class/scsi_device/..../device/modalias
> +Date:           April, 2007
> +KernelVersion:  Unknown
> +Contact:        James Bottomley<James.Bottomley@HansenPartnership.com>
> +Description:
> +		This read only string value contains a string of the form
> +		"scsi:t-0xXX" where "XX" are two hex digits representing the
> +		SCSI device type.  See also the "type" attribute and table 47
> +		in section 8.2.5.1 "Standard INQUIRY data" of the SCSI-2
> +		specification.

My copy of SCSI-2 is draft 10b from 1989 and it doesn't have a
section 8.2.5.1 . Since SCSI-2 was withdrawn over 10 years
ago perhaps you could use a more recent reference. [I see
webstore.ansi.org still sells the SCSI-2 standard for $30 .]

SPC-3 is a standard [ANSI INCITS 408-2005; ISO/IEC 14776-453]
and the relevant section, judging from its last draft, would
be table 83 in section 6.4.2 . And it is now called the
"peripheral device type".

Doug Gilbert

Re: [PATCH] scsi: Document generic scsi device attributes

[scameron]

On Fri, Aug 19, 2011 at 11:21:47AM -0400, Douglas Gilbert wrote:
> On 11-08-19 10:44 AM, Stephen M. Cameron wrote:
> >From: Stephen M. Cameron<scameron@beardog.cce.hp.com>
> >
> 
> <snip>
> 
> >+What:           /sys/class/scsi_device/..../device/modalias
> >+Date:           April, 2007
> >+KernelVersion:  Unknown
> >+Contact:        James Bottomley<James.Bottomley@HansenPartnership.com>
> >+Description:
> >+		This read only string value contains a string of the form
> >+		"scsi:t-0xXX" where "XX" are two hex digits representing the
> >+		SCSI device type.  See also the "type" attribute and table 47
> >+		in section 8.2.5.1 "Standard INQUIRY data" of the SCSI-2
> >+		specification.
> 
> My copy of SCSI-2 is draft 10b from 1989 and it doesn't have a
> section 8.2.5.1 . Since SCSI-2 was withdrawn over 10 years
> ago perhaps you could use a more recent reference. [I see
> webstore.ansi.org still sells the SCSI-2 standard for $30 .]
> 
> SPC-3 is a standard [ANSI INCITS 408-2005; ISO/IEC 14776-453]
> and the relevant section, judging from its last draft, would
> be table 83 in section 6.4.2 . And it is now called the
> "peripheral device type".

I knew it was a mistake for me to try to figure out what the
proper reference should be.  If such things change, maybe 
having a reference in there at all is a mistake.  Maybe it should just
say something like, "the numbers correspond to the entries in
the scsi_device_types[] array in drivers/scsi/scsi.c" since 
that file is more likely to be close at hand than whichever
spec we might refer to.

-- steve

Re: [PATCH] scsi: Document generic scsi device attributes

[Stefan Richter]

On Aug 19 scameron@beardog.cce.hp.com wrote:
> On Fri, Aug 19, 2011 at 11:21:47AM -0400, Douglas Gilbert wrote:
> > On 11-08-19 10:44 AM, Stephen M. Cameron wrote:
> > >From: Stephen M. Cameron<scameron@beardog.cce.hp.com>
> > >
> > 
> > <snip>
> > 
> > >+What:           /sys/class/scsi_device/..../device/modalias
> > >+Date:           April, 2007
> > >+KernelVersion:  Unknown
> > >+Contact:        James Bottomley<James.Bottomley@HansenPartnership.com>
> > >+Description:
> > >+		This read only string value contains a string of the form
> > >+		"scsi:t-0xXX" where "XX" are two hex digits representing the
> > >+		SCSI device type.  See also the "type" attribute and table 47
> > >+		in section 8.2.5.1 "Standard INQUIRY data" of the SCSI-2
> > >+		specification.
> > 
> > My copy of SCSI-2 is draft 10b from 1989 and it doesn't have a
> > section 8.2.5.1 . Since SCSI-2 was withdrawn over 10 years
> > ago perhaps you could use a more recent reference. [I see
> > webstore.ansi.org still sells the SCSI-2 standard for $30 .]
> > 
> > SPC-3 is a standard [ANSI INCITS 408-2005; ISO/IEC 14776-453]
> > and the relevant section, judging from its last draft, would
> > be table 83 in section 6.4.2 . And it is now called the
> > "peripheral device type".
> 
> I knew it was a mistake for me to try to figure out what the
> proper reference should be.  If such things change, maybe 
> having a reference in there at all is a mistake.

The versions of the spec change, as do the chapter numbers and table
numbers.  But it is always "SCSI Primary Commands" ( <- the command
set specification), "INQUIRY data" ( <- the SCSI command response which
contains the data that we are talking about here), "Peripheral Device
Type" ( <- the number which is written into the modalias).

In the last draft revisions of SPC-3 and SPC-4 which were openly published
at ftp.t10.org, it is table 83 in section 6.4.2.  (Visit archive.org to
retrieve those drafts.)  But in the words of the same table:  "All
standards are subject to revision, and parties to agreements based on this
standard are encouraged to investigate the possibility of applying the
most recent editions of the listed standards." :-)

> Maybe it should just
> say something like, "the numbers correspond to the entries in
> the scsi_device_types[] array in drivers/scsi/scsi.c"

But
  - the values come from the target, not from the kernel,
  - their meaning is defined by ANSI/INCITS T10, not by the authors of
    linux/drivers/scsi/scsi.c.

> since that file is more likely to be close at hand than whichever
> spec we might refer to.

Maybe call it Peripheral Device Type (PDT, defined by SCSI Primary
Commands).
-- 
Stefan Richter
-=====-==-== =--- =-=-=
http://arcgraph.de/sr/