[PATCH V2 0/6] smartpqi man page update

[PATCH V2 0/6] smartpqi man page update

[Don Brace]

These changes are based on Linux man pages

Changes since V1:
 - corrected copyright patch

---

Dave Carroll (1):
      smartpqi: add module param to hide vsep

Don Brace (3):
      smartpqi: fix spelling error
      smartpqi: update copyright
      smartpqi: correct lockup action table

Gilbert Wu (1):
      smartpqi: add module param expose ld first

Murthy Bhat (1):
      smartpqi: add sysfs entries


 man4/smartpqi.4 |  104 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 98 insertions(+), 6 deletions(-)

--
Signature

[PATCH V2 1/6] smartpqi: fix spelling error

[Don Brace]

- correct smarpqi to smartpqi

Reviewed-by: Scott Teel <scott.teel@microsemi.com>
Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index cf7c43034..704efb735 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -215,7 +215,7 @@ $ \c
 .in
 .SH VERSIONS
 The
-.B smarpqi
+.B smartpqi
 driver was added in Linux 4.9.
 .SH NOTES
 .SS Configuration

[PATCH V2 2/6] smartpqi: update copyright

[Don Brace]

Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 704efb735..dc9ef1020 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -1,4 +1,5 @@
-.\" Copyright (C) 2016-2017, Microsemi Corporation
+.\" Copyright (C) 2019, Microchip Technology Inc. and its subsidiaries
+.\" Copyright (C) 2016-2018, Microsemi Corporation
 .\" Copyright (C) 2016, PMC-Sierra, Inc.
 .\" Written by Kevin Barnett <kevin.barnett@microsemi.com>
 .\"

[PATCH V2 3/6] smartpqi: add module param expose ld first

[Don Brace]

From: Gilbert Wu <gilbert.wu@microsemi.com>

Reviewed-by: Matt Perricone <matt.perricone@microsemi.com>
Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microsemi.com>
Signed-off-by: Gilbert Wu <gilbert.wu@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |    6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index dc9ef1020..7004f468a 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -15,6 +15,7 @@ smartpqi \- Microsemi Smart Family SCSI driver
 .RB [ disable_heartbeat= { 0 | 1 }]
 .RB [ disable_ctrl_shutdown= { 0 | 1 }]
 .RB [ lockup_action= { none | reboot | panic }]
+.RB [ expose_ld_first= { 0 | 1 }]
 .YS
 .SH DESCRIPTION
 .B smartpqi
@@ -82,6 +83,7 @@ Specifies the action the driver takes when a controller
 lockup is detected.
 The default action is
 .BR none .
+.TP
 .TS
 l l
 ---
@@ -90,6 +92,10 @@ parameter	action
 \fBnone\fP	take controller offline only
 \fBreboot\fP	reboot the system
 \fBpanic\fP	panic the system
+.TP
+.BR expose_ld_first= { 0 | 1 }
+This option enables support for exposing logical devices to OS before physical devices.
+The default value is 0.
 .TE
 .SH FILES
 .SS Device nodes

Re: [PATCH V2 3/6] smartpqi: add module param expose ld first

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 847 bytes --]

At 2019-08-23T12:09:32-0500, Don Brace wrote:
> @@ -82,6 +83,7 @@ Specifies the action the driver takes when a controller
>  lockup is detected.
>  The default action is
>  .BR none .
> +.TP
>  .TS
>  l l
>  ---

Can you explain the purpose of the above change?

Your subsequent patch to correct the table, by reformatting it using
tabs instead of tbl(1) macros, might have been provoked by the above.

The .TP macro is for tagged paragraphs.  .TP consumes the next input
line as a tag for a tagged paragraph.  In man pages, .TP is often used
for definition lists.

However, because the page was being preprocessed by tbl, the .TS macro
was getting substituted with something else, and that something was
getting "eaten" by the .TP macro.

Try removing the above hunk of the patch and see if the table comes back
to life, fixed.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH V2 4/6] smartpqi: add module param to hide vsep

[Don Brace]

From: Dave Carroll <david.carroll@microsemi.com>

Reviewed-by: Matt Perricone <matt.perricone@microsemi.com>
Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microsemi.com>
Signed-off-by: Dave Carroll <david.carroll@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |    5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 7004f468a..45a2017bd 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -16,6 +16,7 @@ smartpqi \- Microsemi Smart Family SCSI driver
 .RB [ disable_ctrl_shutdown= { 0 | 1 }]
 .RB [ lockup_action= { none | reboot | panic }]
 .RB [ expose_ld_first= { 0 | 1 }]
+.RB [ hide_vsep= { 0 | 1 }]
 .YS
 .SH DESCRIPTION
 .B smartpqi
@@ -96,6 +97,10 @@ parameter	action
 .BR expose_ld_first= { 0 | 1 }
 This option enables support for exposing logical devices to OS before physical devices.
 The default value is 0.
+.TP
+.BR hide_vsep= { 0 | 1 }
+This option enables disabling exposure of the virtual SEP to the host. This is usually associated with direct attached drives.
+The default value is 0.
 .TE
 .SH FILES
 .SS Device nodes

[PATCH V2 5/6] smartpqi: add sysfs entries

[Don Brace]

From: Murthy Bhat <Murthy.Bhat@microsemi.com>

Reviewed-by: Matt Perricone <matt.perricone@microsemi.com>
Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Signed-off-by: Murthy Bhat <Murthy.Bhat@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |   80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 45a2017bd..6e2cd1328 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -161,6 +161,86 @@ above
 for an explanation of the
 .I lockup_action
 values.
+.TP
+.IR /sys/class/scsi_host/host*/driver_version
+The
+.I driver_version
+attribute is read-only.
+This attribute contains the smartpqi driver version.
+.IP
+For example:
+.IP
+.in +2n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/driver_version
+1.1.2-126
+.EE
+.in
+.TP
+.IR /sys/class/scsi_host/host*/firmware_version
+The
+.I firmware_version
+attribute is read-only.
+This attribute contains the controller firmware version.
+.IP
+For example:
+.IP
+.in +2n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/firmware_version
+1.29-112
+.EE
+.in
+.TP
+.IR /sys/class/scsi_host/host*/model
+The
+.I model
+attribute is read-only.
+This attribute contains the product identification string of the controller.
+.IP
+For example:
+.IP
+.in +2n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/model
+1100-16i
+.EE
+.in
+.TP
+.IR /sys/class/scsi_host/host*/serial_number
+The
+.I serial_number
+attribute is read-only.
+This attribute contains the unique identification number of the controller.
+.IP
+For example:
+.IP
+.in +2n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/serial_number
+6A316373777
+.EE
+.in
+.TP
+.IR /sys/class/scsi_host/host*/vendor
+The
+.I vendor
+attribute is read-only.
+This attribute contains the vendor identification string of the controller.
+.IP
+For example:
+.IP
+.in +2n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/vendor
+Adaptec
+.EE
+.in
 .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 In the file specifications below,
 .I c

[PATCH V2 6/6] smartpqi: correct lockup action table

[Don Brace]

Reviewed-by: Matt Perricone <matt.perricone@microsemi.com>
Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
Signed-off-by: Don Brace <don.brace@microsemi.com>
---
 man4/smartpqi.4 |   10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 6e2cd1328..43e1d1cb2 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -84,15 +84,15 @@ Specifies the action the driver takes when a controller
 lockup is detected.
 The default action is
 .BR none .
-.TP
-.TS
-l l
----
-l l.
+.nf
+.ta 10n +10n
+
 parameter	action
+---------	----------------------------
 \fBnone\fP	take controller offline only
 \fBreboot\fP	reboot the system
 \fBpanic\fP	panic the system
+.fi
 .TP
 .BR expose_ld_first= { 0 | 1 }
 This option enables support for exposing logical devices to OS before physical devices.

Re: [PATCH V2 6/6] smartpqi: correct lockup action table

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2530 bytes --]

Hi Don,

As noted in my previous message, I suspect this entire segment (6/6) of
the patch is rendered unnecessary if you revert the introduction of the
.TP tagged paragraph macro immediately prior to the .TS table start
macro in segement 3/6.

Also, it's generally better style-wise (in my opinion!) to use tbl(1) to
achieve columnated output in man pages, rather than trying to use tab
stops for this purpose.  I suspect Mr. Kerrisk agrees; while there's no
formal guidance regarding this in man-pages(7), I find 722 lines
matching '^\.TS' in man-pages git HEAD, and only 10 matching
'^\.ta'--and all of those are in timezone-related pages[1], so they
perhaps came in together as part of some sort of import.

This is true even if all tbl(1) ends up doing is setting up tab stops
for you!  It is valuable to preserve the semantic content that tbl
macros give us.  Recognition of the distinction between semantic
markup and presentational markup has been hard-won in the decades since
the classic Unix toolkit was designed.

Finally, in man-pages project parlance, the change below, to convert
from a tbl-preprocessed table to a hand-crafted one using low-level roff
tab requests and literal tab characters, would probably be characterized
as a "srcfix" if there is no visible change to the page as rendered, and
"ffix" if there is[2].

Regards,
Branden

[1] for the curious: tzfile(5), zdump(8), and zic(8)
[2] https://www.kernel.org/doc/man-pages/patches.html ; see "For trivial
    patches..."

At 2019-08-23T12:09:51-0500, Don Brace wrote:
> Reviewed-by: Matt Perricone <matt.perricone@microsemi.com>
> Reviewed-by: Scott Benesh <scott.benesh@microsemi.com>
> Signed-off-by: Don Brace <don.brace@microsemi.com>
> ---
>  man4/smartpqi.4 |   10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
> index 6e2cd1328..43e1d1cb2 100644
> --- a/man4/smartpqi.4
> +++ b/man4/smartpqi.4
> @@ -84,15 +84,15 @@ Specifies the action the driver takes when a controller
>  lockup is detected.
>  The default action is
>  .BR none .
> -.TP
> -.TS
> -l l
> ----
> -l l.
> +.nf
> +.ta 10n +10n
> +
>  parameter	action
> +---------	----------------------------
>  \fBnone\fP	take controller offline only
>  \fBreboot\fP	reboot the system
>  \fBpanic\fP	panic the system
> +.fi
>  .TP
>  .BR expose_ld_first= { 0 | 1 }
>  This option enables support for exposing logical devices to OS before physical devices.
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]