[PATCH] smartpqi: initial submit of smartpqi man page

[PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

This patch contains the initial submission of the
smartpqi man page.

Signed-off-by: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
---
 man4/smartpqi.4 |  195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 195 insertions(+)
 create mode 100644 man4/smartpqi.4

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
new file mode 100644
index 0000000..dafdfe4
--- /dev/null
+++ b/man4/smartpqi.4
@@ -0,0 +1,195 @@
+.\" Copyright (C) 2016-2017, Microsemi Corporation
+.\" Copyright (C) 2016, PMC-Sierra, Inc.
+.\" Written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
+.\"
+.\" %%%LICENSE_START(GPLv2_ONELINE)
+.\" Licensed under GNU General Public License version 2 (GPLv2)
+.\" %%%LICENSE_END
+.\"
+.\" shorthand for double quote that works everywhere.
+.ds q \N'34'
+.TH SMARTPQI 4 "smartpqi"
+.SH NAME
+smartpqi \- Microsemi Smart Family SCSI driver
+.SH SYNOPSIS
+.nf
+modprobe smartpqi [ disable_device_id_wildcards=1 ] [ disable_heartbeat=1 ] [ disable_ctrl_shutdown=1 ] [ lockup_action=none | reboot | panic ]
+.fi
+.SH DESCRIPTION
+.B smartpqi
+is a SCSI driver for Microsemi Smart Family controllers.
+.SH OPTIONS
+.PP
+disable_device_id_wildcards=1
+.RS 4
+This option disables support for device ID wildcards.
+The default value is 0.
+.RE
+.PP
+disable_heartbeat=1
+.RS 4
+This option disables support for the controller's heartbeat check. This parameter is used for debug purposes.
+The default value is 0, do not disable the heartbeat check.
+.RE
+.PP
+disable_ctrl_shutdown=1
+.RS 4
+This option disables support for shutting down the controller in the event of a controller lockup.
+The default value is 0.
+.RE
+.PP
+lockup_action=none | reboot | panic
+.RS 4
+This option specifies the action the driver takes when a controller lockup is detected.
+The default action is none.
+.PP
+.RE
+.RS 4
+.nf
+parameter          action
+---------          ----------------------------
+.br
+none               take controller offline only
+.br
+reboot             reboot the system
+.br
+panic              panic the system
+.fi
+.RE
+.SH CONFIGURATION DETAILS
+To configure Microsemi Smart Family controllers, please refer to the controller's User Guide documentation.
+.RE
+.SH FILES
+.SS DEVICE NODES
+Logical drives are accessed via the SCSI disk driver (sd),
+tape drives via the SCSI tape driver (st), and
+the RAID controller via the SCSI generic driver (sg), with
+device nodes named /dev/sd*, /dev/st*, and /dev/sg*, respectively.
+.SS SMARTPQI SPECIFIC HOST ATTRIBUTE FILES IN /sys
+
+.PP
+.I /sys/class/scsi_host/host*/rescan
+.RS 4
+The host "rescan" attribute is a write-only attribute.  Writing to
+this attribute will cause the driver to scan for new, changed, or
+removed devices (e.g. hot-plugged tape drives, or newly configured
+or deleted logical drives, etc.) and notify the SCSI mid-layer of
+any changes detected.  Normally this is triggered automatically by
+configuration changes, so the user should not normally have to use
+this. It may be useful when hot plugging devices like tape drives,
+or entire storage boxes containing pre-configured logical drives.
+.RE
+.PP
+.I /sys/class/scsi_host/host*/version
+.RS 4
+The host "version" attribute is a read-only attribute. This attribute
+contains the driver version and the controller firmware version.
+.nf
+.PP
+For example:
+.RS 4
+
+cat /sys/class/scsi_host/host1/version
+driver: 1.1.2-126
+firmware: 1.29-112
+.RE
+.fi
+.RE
+.PP
+.I /sys/class/scsi_host/host*/lockup_action
+.RS 4
+The host "lockup_action" attribute is a read-write attribute. This attribute
+will cause the driver to perform a specific action in the unlikely event that
+a controller lockup has been detected. See
+.B OPTIONS
+section for an explanation
+of the lockup_action values.
+.RE
+
+.SS SMARTPQI SPECIFIC DISK ATTRIBUTE FILES IN /sys
+.PP
+.I /sys/class/scsi_disk/c:b:t:l/device/raid_level
+.RS 4
+The "raid_level" attribute is read-only.
+This attribute contains the RAID level of each logical drive.
+.P
+.nf
+For example:
+.RS 4
+cat /sys/class/scsi_disk/4:0:0:0/device/raid_level
+RAID 0
+.RE
+.fi
+.RE
+.PP
+.I /sys/class/scsi_disk/c:b:t:l/device/sas_address
+.RS 4
+The "sas_address" attribute is read-only.
+This attribute contains the unique identifier of the disk.
+.P
+.nf
+For example:
+.RS 4
+cat /sys/class/scsi_disk/1:0:3:0/device/sas_address
+0x5001173d028543a2
+.RE
+.fi
+.RE
+.PP
+.I /sys/class/scsi_disk/c:b:t:l/device/ssd_smart_path_enabled
+.RS 4
+The "ssd_smart_path_enabled" attribute is read-only.
+This attribute is for ioaccel enabled volumes.
+Contains 1 if ioaccel is enabled for the volume, 0 otherwise.
+.P
+.nf
+For example:
+.RS 4
+cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
+0
+.RE
+.fi
+.RE
+.SH SUPPORTED IOCTLS
+For compatibility with applications written for the hpsa driver, many, but
+not all of the ioctls supported by the hpsa driver are also supported by the
+smartpqi driver.  The data structures used by these are described in
+include/linux/cciss_ioctl.h
+.PP
+CCISS_DEREGDISK,
+CCISS_REGNEWDISK,
+and CCISS_REGNEWD
+.RS 4
+The above three ioctls all do exactly the same thing, which is to cause the driver
+to rescan for new devices.  This does exactly the same thing as writing to the
+smartpqi specific host "rescan" attribute.
+.RE
+.PP
+CCISS_GETPCIINFO
+.RS 4
+Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID).
+.RE
+.PP
+CCISS_GETDRIVVER
+.RS 4
+Returns driver version in four bytes encoded as:
+(major_version << 28) | (minor_version << 24) | (release << 16) | revision
+.RE
+.PP
+CCISS_PASSTHRU
+.RS 4
+Allows "BMIC" and "CISS" commands to be passed through to the controller.
+.RE
+.SH "SEE ALSO"
+hpsa(4), sd(4), st(4), and from the linux kernel source tree:
+.br
+Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
+
+.SH AUTHORS
+smartpqi was written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
+.br
+.nf
+This man page was written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org> and
+.br
+Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
+.fi

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

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 3246 bytes --]

At 2017-10-18T10:10:39-0500, Don Brace wrote:
> This patch contains the initial submission of the
> smartpqi man page.

Hi Don,

Please find attached my recommended changes.

I made many changes, most of them formatting-related.

01. Removed string definition that was never used[1].
02. Set up the title heading per man-pages(7).
03. Used SY/OP/YS macros to lay out the synopsis.  This solves alignment
    issues more pleasantly than nf/fi requests, and puts literal syntax
    elements in bold.
04. Used tagged paragraphs instead of un-tagged paragraphs combined with
    relative-indent macros.
05. Documented boolean values more explicitly (in synopsis as well).
06. Tightened language; "This option" is implied by context.
07. Wordsmithed an imperative-sounding phrase to a descriptive one
    regarding the heartbeat.
08. Put the lockup_action action table into a real table.
09. Retitled section "CONFIGURATION DETAILS" to just "CONFIGURATION" per
    man-pages(7).
10. Marked up driver names, file names[2], and controller attribute
    references in italics.
11. Added line breaks to ends of sentences so troff will apply
    inter-sentence spacing appropriately.
12. Put subsection titles into sentence-case[2] per man-pages(7).
13. hot plugging -> hot-plugging[3]
14. "e.g." implies "etc.", so both are not necessary.
15. Convert examples to use indentation and EX/EE macros per
    man-pages(7).
16. In examples, put user input in bold per man-pages(7).
17. Explain b:c:t:l notation, since it is not used literally in
    filespecs.
18. "read-write" -> "read/write"[3]
19. Added cross-reference to cciss(4) man page.
20. Reformatted SEE ALSO section.
21. Deleted AUTHORS section as it is "strongly deprecated" per
    man-pages(7).

There are some issues I was unsure about; I left them in comments:

To configure Microsemi Smart Family controllers, please refer to the
controller's User Guide documentation.
.\" Does this manual have a title?  Is it freely available online?
.\" Does it have a stable URL?  Can this information be moved to the SEE
.\" ALSO section?

.\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.

.\" This example line is too wide for an 80-column TTY.
.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled

.SS Supported \f[BI]ioctl\fP\/() operations
.\" Does this subsection belong here, under .SH FILES ?

And here's one more I just thought of (forest, trees...).

Is "SmartPQI" the correct casing when referring to the product rather
than the kernel module?

I checked the output on 80- and 191-column terminals and with a
PostScript viewer.

[1] And which doesn't "work everywhere", anyway, for instance on EBCDIC
systems.  IIRC, the groff guys discourage defining a string escape this
way.
[2] I don't know of another term for this.  "In subsection ("SS")
    headings, capitalize the first word in the heading, but otherwise
    use lowercase, except where English usage (e.g., proper nouns) or
    programming language requirements (e.g., identifier names) dictate
    otherwise."
[3] MTK: Is this a candidate for the "Preferred terms" subsection of
    man-pages(7)?

-- 
Regards,
Branden

[-- Attachment #1.2: smartpqi_branden.man --]
[-- Type: application/x-troff-man, Size: 6065 bytes --]

[-- Attachment #1.3: smartpqi.diff --]
[-- Type: text/x-diff, Size: 10901 bytes --]

--- smartpqi.4	2017-10-19 15:40:10.044996618 -0400
+++ smartpqi_branden.man	2017-10-19 17:20:45.658894362 -0400
@@ -5,191 +5,220 @@
 .\" %%%LICENSE_START(GPLv2_ONELINE)
 .\" Licensed under GNU General Public License version 2 (GPLv2)
 .\" %%%LICENSE_END
-.\"
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH SMARTPQI 4 "smartpqi"
+.TH SMARTPQI 4 2017-10-19 "Linux" "Linux Programmer's Manual"
 .SH NAME
 smartpqi \- Microsemi Smart Family SCSI driver
 .SH SYNOPSIS
-.nf
-modprobe smartpqi [ disable_device_id_wildcards=1 ] [ disable_heartbeat=1 ] [ disable_ctrl_shutdown=1 ] [ lockup_action=none | reboot | panic ]
-.fi
+.SY "modprobe smartpqi"
+.RB [ disable_device_id_wildcards= { 0 | 1 }]
+.RB [ disable_heartbeat= { 0 | 1 }]
+.RB [ disable_ctrl_shutdown= { 0 | 1 }]
+.RB [ lockup_action= { none | reboot | panic }]
+.YS
 .SH DESCRIPTION
 .B smartpqi
 is a SCSI driver for Microsemi Smart Family controllers.
 .SH OPTIONS
-.PP
-disable_device_id_wildcards=1
-.RS 4
-This option disables support for device ID wildcards.
+.TP
+.BR disable_device_id_wildcards= { 0 | 1 }
+Disables support for device ID wildcards.
 The default value is 0.
-.RE
-.PP
-disable_heartbeat=1
-.RS 4
-This option disables support for the controller's heartbeat check. This parameter is used for debug purposes.
-The default value is 0, do not disable the heartbeat check.
-.RE
-.PP
-disable_ctrl_shutdown=1
-.RS 4
-This option disables support for shutting down the controller in the event of a controller lockup.
+.TP
+.BR disable_heartbeat= { 0 | 1 }
+Disables support for the controller's heartbeat check.
+This parameter is used for debugging purposes.
+The default value is 0, leaving the controller's heartbeat check active.
+.TP
+.BR disable_ctrl_shutdown= { 0 | 1 }
+Disables support for shutting down the controller in the
+event of a controller lockup.
 The default value is 0.
-.RE
-.PP
-lockup_action=none | reboot | panic
-.RS 4
-This option specifies the action the driver takes when a controller lockup is detected.
-The default action is none.
-.PP
-.RE
-.RS 4
-.nf
-parameter          action
----------          ----------------------------
-.br
-none               take controller offline only
-.br
-reboot             reboot the system
-.br
-panic              panic the system
-.fi
-.RE
-.SH CONFIGURATION DETAILS
-To configure Microsemi Smart Family controllers, please refer to the controller's User Guide documentation.
+.TP
+.BR lockup_action= { none | reboot | panic }
+Specifies the action the driver takes when a controller
+lockup is detected.
+The default action is
+.BR none .
+.TS
+l l
+---
+l l.
+parameter	action
+\fBnone\fP	take controller offline only
+\fBreboot\fP	reboot the system
+\fBpanic\fP	panic the system
+.TE
+.SH CONFIGURATION
+To configure Microsemi Smart Family controllers, please refer to the
+controller's User Guide documentation.
+.\" Does this manual have a title?  Is it freely available online?
+.\" Does it have a stable URL?  Can this information be moved to the SEE
+.\" ALSO section?
 .RE
 .SH FILES
-.SS DEVICE NODES
-Logical drives are accessed via the SCSI disk driver (sd),
-tape drives via the SCSI tape driver (st), and
-the RAID controller via the SCSI generic driver (sg), with
-device nodes named /dev/sd*, /dev/st*, and /dev/sg*, respectively.
-.SS SMARTPQI SPECIFIC HOST ATTRIBUTE FILES IN /sys
-
-.PP
-.I /sys/class/scsi_host/host*/rescan
-.RS 4
-The host "rescan" attribute is a write-only attribute.  Writing to
-this attribute will cause the driver to scan for new, changed, or
-removed devices (e.g. hot-plugged tape drives, or newly configured
-or deleted logical drives, etc.) and notify the SCSI mid-layer of
-any changes detected.  Normally this is triggered automatically by
-configuration changes, so the user should not normally have to use
-this. It may be useful when hot plugging devices like tape drives,
-or entire storage boxes containing pre-configured logical drives.
-.RE
-.PP
-.I /sys/class/scsi_host/host*/version
-.RS 4
-The host "version" attribute is a read-only attribute. This attribute
-contains the driver version and the controller firmware version.
-.nf
-.PP
+.SS Device nodes
+Logical drives are accessed via the SCSI disk driver
+.RI ( sd ),
+tape drives via the SCSI tape driver
+.RI ( st ),
+and the RAID controller via the SCSI generic driver
+.RI ( sg ),
+with device nodes named
+.IR /dev/sd *,
+.IR /dev/st *,
+and
+.IR /dev/sg *,
+respectively.
+.SS SmartPQI-specific host attribute files in \f[BI]/sys\fP
+.TP
+.IR /sys/class/scsi_host/host * /rescan
+The host
+.I rescan
+attribute is a write-only attribute.
+Writing to this attribute will cause the driver to scan for new,
+changed, or removed devices (e.g., hot-plugged tape drives, or newly
+configured or deleted logical drives) and notify the SCSI mid-layer of
+any changes detected.
+Normally this action is triggered automatically by configuration
+changes, so the user should not normally have to write to this file.
+Doing so may be useful when hot-plugging devices like tape drives, or
+entire storage boxes containing pre-configured logical drives.
+.TP
+.IR /sys/class/scsi_host/host * /version
+The host
+.I version
+attribute is a read-only attribute.
+This attribute contains the driver version and the controller firmware
+version.
+.IP
 For example:
-.RS 4
-
-cat /sys/class/scsi_host/host1/version
-driver: 1.1.2-126
-firmware: 1.29-112
-.RE
-.fi
-.RE
-.PP
-.I /sys/class/scsi_host/host*/lockup_action
-.RS 4
-The host "lockup_action" attribute is a read-write attribute. This attribute
-will cause the driver to perform a specific action in the unlikely event that
-a controller lockup has been detected. See
-.B OPTIONS
-section for an explanation
-of the lockup_action values.
-.RE
-
-.SS SMARTPQI SPECIFIC DISK ATTRIBUTE FILES IN /sys
-.PP
-.I /sys/class/scsi_disk/c:b:t:l/device/raid_level
-.RS 4
-The "raid_level" attribute is read-only.
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_host/host1/version
+driver: 1.1.2\-126
+firmware: 1.29\-112
+.EE
+.in
+.TP
+.IR /sys/class/scsi_host/host * /lockup_action
+The host
+.I lockup_action
+attribute is a read/write attribute.
+This attribute will cause the driver to perform a specific action in the
+unlikely event that a controller lockup has been detected.
+See
+.BR OPTIONS
+above
+for an explanation of the
+.I lockup_action
+values.
+.SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
+In the file specifications below,
+.I c
+stands for the number of the appropriate SCSI controller,
+.I b
+the bus number,
+.I t
+the target number, and
+.I l
+the logical unit number (LUN).
+.TP
+.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level
+The
+.I raid_level
+attribute is read-only.
 This attribute contains the RAID level of each logical drive.
-.P
-.nf
+.IP
 For example:
-.RS 4
-cat /sys/class/scsi_disk/4:0:0:0/device/raid_level
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level
 RAID 0
-.RE
-.fi
-.RE
-.PP
-.I /sys/class/scsi_disk/c:b:t:l/device/sas_address
-.RS 4
-The "sas_address" attribute is read-only.
+.EE
+.in
+.TP
+.IR /sys/class/scsi_disk/c : b : t : l/device/sas_address
+The
+.I sas_address
+attribute is read-only.
 This attribute contains the unique identifier of the disk.
-.P
-.nf
+.IP
 For example:
-.RS 4
-cat /sys/class/scsi_disk/1:0:3:0/device/sas_address
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address
 0x5001173d028543a2
-.RE
-.fi
-.RE
-.PP
-.I /sys/class/scsi_disk/c:b:t:l/device/ssd_smart_path_enabled
-.RS 4
-The "ssd_smart_path_enabled" attribute is read-only.
-This attribute is for ioaccel enabled volumes.
-Contains 1 if ioaccel is enabled for the volume, 0 otherwise.
-.P
-.nf
+.EE
+.in
+.TP
+.IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled
+The
+.I ssd_smart_path_enabled
+attribute is read-only.
+.\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
+This attribute is for ioaccel-enabled volumes.
+Contains 1 if ioaccel is enabled for the volume and 0 otherwise.
+.IP
 For example:
-.RS 4
-cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
+.in +4n
+.EX
+$ \c
+.\" This example line is too wide for an 80-column TTY.
+.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
 0
-.RE
-.fi
-.RE
-.SH SUPPORTED IOCTLS
-For compatibility with applications written for the hpsa driver, many, but
-not all of the ioctls supported by the hpsa driver are also supported by the
-smartpqi driver.  The data structures used by these are described in
-include/linux/cciss_ioctl.h
-.PP
-CCISS_DEREGDISK,
-CCISS_REGNEWDISK,
-and CCISS_REGNEWD
-.RS 4
-The above three ioctls all do exactly the same thing, which is to cause the driver
-to rescan for new devices.  This does exactly the same thing as writing to the
-smartpqi specific host "rescan" attribute.
-.RE
-.PP
-CCISS_GETPCIINFO
-.RS 4
-Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID).
-.RE
-.PP
-CCISS_GETDRIVVER
-.RS 4
-Returns driver version in four bytes encoded as:
+.EE
+.in
+.SS Supported \f[BI]ioctl\fP\/() operations
+.\" Does this subsection belong here, under .SH FILES ?
+For compatibility with applications written for the
+.BR cciss (4)
+and
+.BR hpsa (4)
+drivers, many, but not all of the
+.IR ioctl s
+supported by the
+.B hpsa
+driver are also supported by the
+.B smartpqi
+driver.
+The data structures used by these
+.IR ioctl s
+are described in the Linux kernel source file
+.IR include/linux/cciss_ioctl.h .
+.TP
+.BR CCISS_DEREGDISK ,\c
+.BR CCISS_REGNEWDISK ,\c
+.B CCISS_REGNEWD
+The above three
+.IR ioctl s
+all do exactly the same thing, which is to cause the driver to re-scan
+for new devices.
+This does exactly the same thing as writing to the
+.BR smartpqi -specific
+host
+.I rescan
+attribute.
+.TP
+.B CCISS_GETPCIINFO
+Returns the PCI domain, bus, device and function and "board ID" (PCI
+subsystem ID).
+.TP
+.B CCISS_GETDRIVVER
+Returns the driver version in four bytes, encoded as:
+.EX
 (major_version << 28) | (minor_version << 24) | (release << 16) | revision
-.RE
+.EE
+.TP
+.B CCISS_PASSTHRU
+Allows BMIC and CISS commands to be passed through to the controller.
+.SH SEE ALSO
+.BR cciss (4),
+.BR hpsa (4),
+.BR sd (4),
+.BR st (4)
 .PP
-CCISS_PASSTHRU
-.RS 4
-Allows "BMIC" and "CISS" commands to be passed through to the controller.
-.RE
-.SH "SEE ALSO"
-hpsa(4), sd(4), st(4), and from the linux kernel source tree:
-.br
-Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
-
-.SH AUTHORS
-smartpqi was written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
-.br
-.nf
-This man page was written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org> and
-.br
-Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
-.fi
+.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss
+in the Linux kernel source tree.

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

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

> -----Original Message-----
> From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
> Sent: Thursday, October 19, 2017 4:36 PM
> To: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org; Gerry Morong
> <gerry.morong-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; John Hall <John.Hall-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
> Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Bader Ali - Saleh
> <bader.alisaleh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Teel <scott.teel-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
> Justin Lindley <justin.lindley-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Benesh
> <scott.benesh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> 
> At 2017-10-18T10:10:39-0500, Don Brace wrote:
> > This patch contains the initial submission of the
> > smartpqi man page.
> 
> Hi Don,
> 
> Please find attached my recommended changes.
> 
> I made many changes, most of them formatting-related.

Really appreciate your effort!

> 
> There are some issues I was unsure about; I left them in comments:
> 
> To configure Microsemi Smart Family controllers, please refer to the
> controller's User Guide documentation.
> .\" Does this manual have a title?  Is it freely available online?
> .\" Does it have a stable URL?  Can this information be moved to the SEE
> .\" ALSO section?

There is currently no User Guide available on-line. The guide should be packaged with
the controller. There is a Documentation/scsi/smartpqi.txt  entry.

> 
> .\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
This is a term for RAID volumes. When an I/O request can go directly to a physical disk
bypassing the RAID engine in the controller. This results in a performance gain.

> 
> .\" This example line is too wide for an 80-column TTY.
> .B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
How about:
cd /sys/class/scsi_disk/1:0:3:0/device/
cat ssd_smart_path_enabled
> 
> .SS Supported \f[BI]ioctl\fP\/() operations
> .\" Does this subsection belong here, under .SH FILES ?
I see your point. This should be in a different section. We saw that hpsa.4 had
done the same thing.

Should this be under NOTES?

> 
> And here's one more I just thought of (forest, trees...).
> 
> Is "SmartPQI" the correct casing when referring to the product rather
> than the kernel module?

The driver name is smartpqi, perhaps omitting the SmartPQI or SMARTPQI would be best
for these sections.
> 
> I checked the output on 80- and 191-column terminals and with a
> PostScript viewer.
> 
> [1] And which doesn't "work everywhere", anyway, for instance on EBCDIC
> systems.  IIRC, the groff guys discourage defining a string escape this
> way.
> [2] I don't know of another term for this.  "In subsection ("SS")
>     headings, capitalize the first word in the heading, but otherwise
>     use lowercase, except where English usage (e.g., proper nouns) or
>     programming language requirements (e.g., identifier names) dictate
>     otherwise."
> [3] MTK: Is this a candidate for the "Preferred terms" subsection of
>     man-pages(7)?
> 
> --
> Regards,
> Branden
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[G. Branden Robinson]

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

At 2017-10-20T22:10:55+0000, Don Brace wrote:
> > -----Original Message-----
> > From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
> > I made many changes, most of them formatting-related.
> 
> Really appreciate your effort!

Thanks!

> > There are some issues I was unsure about; I left them in comments:

Just FYI, these were as much for Michael Kerrisk's feedback as yours.
I'm just a volunteer like most people on the linux-man list, so please
don't feel that all of these issues have to be resolved before the page
can make it in; Mr. Kerrisk is the gatekeeper.

> > To configure Microsemi Smart Family controllers, please refer to the
> > controller's User Guide documentation.
> > .\" Does this manual have a title?  Is it freely available online?
> > .\" Does it have a stable URL?  Can this information be moved to the SEE
> > .\" ALSO section?
> 
> There is currently no User Guide available on-line. The guide should be packaged with
> the controller. There is a Documentation/scsi/smartpqi.txt  entry.

My preference as a committed non-professional sysadmin is to never have
to dig up a piece of paper to find out how to configure my hardware.  :)

> > .\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
> This is a term for RAID volumes. When an I/O request can go directly
> to a physical disk bypassing the RAID engine in the controller. This
> results in a performance gain.

I hope that's restricted to read operations.  ;-)

> > .\" This example line is too wide for an 80-column TTY.
> > .B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
> How about:
> cd /sys/class/scsi_disk/1:0:3:0/device/
> cat ssd_smart_path_enabled

I checked and the original too-wide line is also too wide on troff's
PostScript output device, and runs into the page margin.

Your solution is one obvious one; another would be to put a shell
line-continuation into the example.

.IP
For example:
.in +4n
.EX
.RB "$ " cat /sys/class/scsi_disk/1:0:3:0/device/\\e
.RB "> " ssd_smart_path_enabled
0
.EE
.in

Which renders as:

              For example:
                  $ cat /sys/class/scsi_disk/1:0:3:0/device/\
                  > ssd_smart_path_enabled
                  0

But with the user input in boldface.

> > .SS Supported \f[BI]ioctl\fP\/() operations
> > .\" Does this subsection belong here, under .SH FILES ?
> I see your point. This should be in a different section. We saw that hpsa.4 had
> done the same thing.
> 
> Should this be under NOTES?

Yup, I noticed that, too.  When Michael K. has a chance to review my
suggestions, I'm happy to supply patches to cciss(4) and hpsa(4) to
"parallelize" the three.

> > And here's one more I just thought of (forest, trees...).
> > 
> > Is "SmartPQI" the correct casing when referring to the product rather
> > than the kernel module?
> 
> The driver name is smartpqi, perhaps omitting the SmartPQI or SMARTPQI
> would be best for these sections.

I have no preference here; I just wanted to make sure the orthography
was right.  I don't want anyone getting flamed by their trademark
lawyer.  :D

-- 
Regards,
Branden

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

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[Michael Kerrisk (man-opages)]

Hello Don,

On 10/21/2017 12:10 AM, Don Brace wrote:
>> -----Original Message-----
>> From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
>> Sent: Thursday, October 19, 2017 4:36 PM
>> To: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
>> Cc: mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org; linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org; Gerry Morong
>> <gerry.morong-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; John Hall <John.Hall-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
>> Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Bader Ali - Saleh
>> <bader.alisaleh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Teel <scott.teel-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
>> Justin Lindley <justin.lindley-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Benesh
>> <scott.benesh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
>> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
>>
>> At 2017-10-18T10:10:39-0500, Don Brace wrote:
>>> This patch contains the initial submission of the
>>> smartpqi man page.
>>
>> Hi Don,
>>
>> Please find attached my recommended changes.
>>
>> I made many changes, most of them formatting-related.
> 
> Really appreciate your effort!

My apologies for not weighing in sooner. I see you got a lot of input 
from Branden! (Thanks, Branden!) How shall we move forward? Possibilities:

1. I apply your original patch as is.
2. You rework your patch incorporating those changes from Branden
    that seem uncontroversial to you, and I apply, and then we
    discuss any further changes that may be needed.
3. If all changes from Branden seem uncontroversial, I apply\
    your patch, his patch, and then we  discuss any further changes
    that may be needed.

I suspect 2 or 3 is the way to go, but I await your input.

Thanks,

Michael

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

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[G. Branden Robinson]

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

At 2017-10-31T08:10:47+0100, Michael Kerrisk (man-opages) wrote:
> My apologies for not weighing in sooner. I see you got a lot of input from
> Branden! (Thanks, Branden!) How shall we move forward? Possibilities:
> 
> 1. I apply your original patch as is.
> 2. You rework your patch incorporating those changes from Branden
>    that seem uncontroversial to you, and I apply, and then we
>    discuss any further changes that may be needed.
> 3. If all changes from Branden seem uncontroversial, I apply\
>    your patch, his patch, and then we  discuss any further changes
>    that may be needed.
> 
> I suspect 2 or 3 is the way to go, but I await your input.

If the set of my changes accepted is not null, I'm happy to prepare
diffs for any parallel changes that are necessary to cciss(4) and
hpsa(4), which share some material with the proposed smartpqi(4).

-- 
Regards,
Branden

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

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

> -----Original Message-----
> From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
> Sent: Tuesday, October 31, 2017 8:37 PM
> To: Michael Kerrisk (man-opages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> Cc: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org; Gerry
> Morong <gerry.morong-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; John Hall
> <John.Hall-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
> Bader Ali - Saleh <bader.alisaleh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Teel
> <scott.teel-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Justin Lindley <justin.lindley-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
> Scott Benesh <scott.benesh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> 
> EXTERNAL EMAIL

I Ack your proposed changes.

Acked-by: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>

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

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[Michael Kerrisk (man-pages)]

On 11/06/2017 04:26 PM, Don Brace wrote:>
>> -----Original Message-----
>> From: G. Branden Robinson [mailto:g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org]
>> Sent: Tuesday, October 31, 2017 8:37 PM
>> To: Michael Kerrisk (man-opages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
>> Cc: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org; Gerry
>> Morong <gerry.morong-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; John Hall
>> <John.Hall-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
>> Bader Ali - Saleh <bader.alisaleh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Scott Teel
>> <scott.teel-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>; Justin Lindley <justin.lindley-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>;
>> Scott Benesh <scott.benesh-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
>> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
>>
>> EXTERNAL EMAIL
>
> I Ack your proposed changes.
>
> Acked-by: Don Brace <don.brace-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>

Hello Don,

Thanks. I've taken your patch into a local branch, and applied
Branden's patch on top, and done a few edits.

However, Branden raised a couple of relevant questions that I'd
like to get resolved.

Could you take a look at the FIXMEs in the draft below, please.

Cheers,

Michael

.\" Copyright (C) 2016-2017, Microsemi Corporation
.\" Copyright (C) 2016, PMC-Sierra, Inc.
.\" Written by Kevin Barnett <kevin.barnett-dzo6w/eZyo2tG0bUXCXiUA@public.gmane.org>
.\"
.\" %%%LICENSE_START(GPLv2_ONELINE)
.\" Licensed under GNU General Public License version 2 (GPLv2)
.\" %%%LICENSE_END
.TH SMARTPQI 4 2017-10-19 "Linux" "Linux Programmer's Manual"
.SH NAME
smartpqi \- Microsemi Smart Family SCSI driver
.SH SYNOPSIS
.SY "modprobe smartpqi"
.RB [ disable_device_id_wildcards= { 0 | 1 }]
.RB [ disable_heartbeat= { 0 | 1 }]
.RB [ disable_ctrl_shutdown= { 0 | 1 }]
.RB [ lockup_action= { none | reboot | panic }]
.YS
.SH DESCRIPTION
.B smartpqi
is a SCSI driver for Microsemi Smart Family controllers.
.SS Supported \f[BI]ioctl\fP\/() operations
For compatibility with applications written for the
.BR cciss (4)
and
.BR hpsa (4)
drivers, many, but not all of the
.BR ioctl (2)
operations supported by the
.B hpsa
driver are also supported by the
.B smartpqi
driver.
The data structures used by these operations
are described in the Linux kernel source file
.IR include/linux/cciss_ioctl.h .
.TP
.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD
These operations
all do exactly the same thing, which is to cause the driver to re-scan
for new devices.
This does exactly the same thing as writing to the
.BR smartpqi -specific
host
.I rescan
attribute.
.TP
.B CCISS_GETPCIINFO
This operation Returns the PCI domain, bus,
device and function and "board ID" (PCI subsystem ID).
.TP
.B CCISS_GETDRIVVER
This operation returns the driver version in four bytes, encoded as:
.IP
.in +4n
.EX
(major_version << 28) | (minor_version << 24) |
        (release << 16) | revision
.EE
.in
.TP
.B CCISS_PASSTHRU
Allows BMIC and CISS commands to be passed through to the controller.
.SS Boot options
.TP
.BR disable_device_id_wildcards= { 0 | 1 }
Disables support for device ID wildcards.
The default value is 0.
.TP
.BR disable_heartbeat= { 0 | 1 }
Disables support for the controller's heartbeat check.
This parameter is used for debugging purposes.
The default value is 0, leaving the controller's heartbeat check active.
.TP
.BR disable_ctrl_shutdown= { 0 | 1 }
Disables support for shutting down the controller in the
event of a controller lockup.
The default value is 0.
.TP
.BR lockup_action= { none | reboot | panic }
Specifies the action the driver takes when a controller
lockup is detected.
The default action is
.BR none .
.TS
l l
---
l l.
parameter    action
\fBnone\fP    take controller offline only
\fBreboot\fP    reboot the system
\fBpanic\fP    panic the system
.TE
.RE
.SH FILES
.SS Device nodes
Logical drives are accessed via the SCSI disk driver
.RI ( sd ),
tape drives via the SCSI tape driver
.RI ( st ),
and the RAID controller via the SCSI generic driver
.RI ( sg ),
with device nodes named
.IR /dev/sd *,
.IR /dev/st *,
and
.IR /dev/sg *,
respectively.
.SS SmartPQI-specific host attribute files in \f[BI]/sys\fP
.TP
.IR /sys/class/scsi_host/host * /rescan
The host
.I rescan
attribute is a write-only attribute.
Writing to this attribute will cause the driver to scan for new,
changed, or removed devices (e.g., hot-plugged tape drives, or newly
configured or deleted logical drives) and notify the SCSI mid-layer of
any changes detected.
Usually this action is triggered automatically by configuration
changes, so the user should not normally have to write to this file.
Doing so may be useful when hot-plugging devices such as tape drives or
entire storage boxes containing pre-configured logical drives.
.TP
.IR /sys/class/scsi_host/host * /version
The host
.I version
attribute is a read-only attribute.
This attribute contains the driver version and the controller firmware
version.
.IP
For example:
.IP
.in +4n
.EX
$ \c
.B cat /sys/class/scsi_host/host1/version
driver: 1.1.2\-126
firmware: 1.29\-112
.EE
.in
.TP
.IR /sys/class/scsi_host/host * /lockup_action
The host
.I lockup_action
attribute is a read/write attribute.
This attribute will cause the driver to perform a specific action in the
unlikely event that a controller lockup has been detected.
See
.BR OPTIONS
above
for an explanation of the
.I lockup_action
values.
.SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
In the file specifications below,
.I c
stands for the number of the appropriate SCSI controller,
.I b
is the bus number,
.I t
the target number, and
.I l
is the logical unit number (LUN).
.TP
.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level
The
.I raid_level
attribute is read-only.
This attribute contains the RAID level of each logical drive.
.IP
For example:
.IP
.in +4n
.EX
$ \c
.B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level
RAID 0
.EE
.in
.TP
.IR /sys/class/scsi_disk/c : b : t : l/device/sas_address
The
.I sas_address
attribute is read-only.
This attribute contains the unique identifier of the disk.
.IP
For example:
.IP
.in +4n
.EX
$ \c
.B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address
0x5001173d028543a2
.EE
.in
.TP
.IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled
The
.I ssd_smart_path_enabled
attribute is read-only.
.\" FIXME
.\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
This attribute is for ioaccel-enabled volumes.
Contains 1 if ioaccel is enabled for the volume and 0 otherwise.
.IP
For example:
.IP
.in +2n
.EX
$ \c
.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
0
.EE
.in
.SH VERSIONS
The
.B smarpqi
driver was added in Linux 4.9.
.SH NOTES
.SS Configuration
To configure Microsemi Smart Family controllers, please refer to the
controller's User Guide documentation.
.\" FIXME
.\" Does this manual have a title?  Is it freely available online?
.\" Does it have a stable URL?  Can this information be moved to the SEE
.\" ALSO section?
.SH SEE ALSO
.BR cciss (4),
.BR hpsa (4),
.BR sd (4),
.BR st (4)
.PP
.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss
in the Linux kernel source tree.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

> -----Original Message-----
> From: Michael Kerrisk (man-pages) [mailto:mtk.manpages@gmail.com]
> Sent: Tuesday, November 14, 2017 1:12 AM
> To: Don Brace <don.brace@microsemi.com>
> Cc: G. Branden Robinson <g.branden.robinson@gmail.com>; linux-
> man@vger.kernel.org; Gerry Morong <gerry.morong@microsemi.com>; John
> Hall <John.Hall@microsemi.com>; Kevin Barnett
> <kevin.barnett@microsemi.com>; Bader Ali - Saleh
> <bader.alisaleh@microsemi.com>; Scott Teel <scott.teel@microsemi.com>;
> Justin Lindley <justin.lindley@microsemi.com>; Scott Benesh
> <scott.benesh@microsemi.com>
> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> 
> EXTERNAL EMAIL
> 
> 
> On 11/06/2017 04:26 PM, Don Brace wrote:>
> >> -----Original Message-----
> >> From: G. Branden Robinson [mailto:g.branden.robinson@gmail.com]
> >> Sent: Tuesday, October 31, 2017 8:37 PM
> >> To: Michael Kerrisk (man-opages) <mtk.manpages@gmail.com>
> >> Cc: Don Brace <don.brace@microsemi.com>; linux-man@vger.kernel.org;
> Gerry
> >> Morong <gerry.morong@microsemi.com>; John Hall
> >> <John.Hall@microsemi.com>; Kevin Barnett
> <kevin.barnett@microsemi.com>;
> >> Bader Ali - Saleh <bader.alisaleh@microsemi.com>; Scott Teel
> >> <scott.teel@microsemi.com>; Justin Lindley
> <justin.lindley@microsemi.com>;
> >> Scott Benesh <scott.benesh@microsemi.com>
> >> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> >>
> >> EXTERNAL EMAIL
> >
> > I Ack your proposed changes.
> >
> > Acked-by: Don Brace <don.brace@microsemi.com>
> 
> Hello Don,
> 
> Thanks. I've taken your patch into a local branch, and applied
> Branden's patch on top, and done a few edits.
> 
> However, Branden raised a couple of relevant questions that I'd
> like to get resolved.
> 
> Could you take a look at the FIXMEs in the draft below, please.
I answered them in-line. Thanks for your effort.

> 
> Cheers,
> 
> Michael
> 
> .\" Copyright (C) 2016-2017, Microsemi Corporation
> .\" Copyright (C) 2016, PMC-Sierra, Inc.
> .\" Written by Kevin Barnett <kevin.barnett@microsemi.com>
> .\"
> .\" %%%LICENSE_START(GPLv2_ONELINE)
> .\" Licensed under GNU General Public License version 2 (GPLv2)
> .\" %%%LICENSE_END
> .TH SMARTPQI 4 2017-10-19 "Linux" "Linux Programmer's Manual"
> .SH NAME
> smartpqi \- Microsemi Smart Family SCSI driver
> .SH SYNOPSIS
> .SY "modprobe smartpqi"
> .RB [ disable_device_id_wildcards= { 0 | 1 }]
> .RB [ disable_heartbeat= { 0 | 1 }]
> .RB [ disable_ctrl_shutdown= { 0 | 1 }]
> .RB [ lockup_action= { none | reboot | panic }]
> .YS
> .SH DESCRIPTION
> .B smartpqi
> is a SCSI driver for Microsemi Smart Family controllers.
> .SS Supported \f[BI]ioctl\fP\/() operations
> For compatibility with applications written for the
> .BR cciss (4)
> and
> .BR hpsa (4)
> drivers, many, but not all of the
> .BR ioctl (2)
> operations supported by the
> .B hpsa
> driver are also supported by the
> .B smartpqi
> driver.
> The data structures used by these operations
> are described in the Linux kernel source file
> .IR include/linux/cciss_ioctl.h .
> .TP
> .BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD
> These operations
> all do exactly the same thing, which is to cause the driver to re-scan
> for new devices.
> This does exactly the same thing as writing to the
> .BR smartpqi -specific
> host
> .I rescan
> attribute.
> .TP
> .B CCISS_GETPCIINFO
> This operation Returns the PCI domain, bus,
> device and function and "board ID" (PCI subsystem ID).
> .TP
> .B CCISS_GETDRIVVER
> This operation returns the driver version in four bytes, encoded as:
> .IP
> .in +4n
> .EX
> (major_version << 28) | (minor_version << 24) |
>         (release << 16) | revision
> .EE
> .in
> .TP
> .B CCISS_PASSTHRU
> Allows BMIC and CISS commands to be passed through to the controller.
> .SS Boot options
> .TP
> .BR disable_device_id_wildcards= { 0 | 1 }
> Disables support for device ID wildcards.
> The default value is 0.
> .TP
> .BR disable_heartbeat= { 0 | 1 }
> Disables support for the controller's heartbeat check.
> This parameter is used for debugging purposes.
> The default value is 0, leaving the controller's heartbeat check active.
> .TP
> .BR disable_ctrl_shutdown= { 0 | 1 }
> Disables support for shutting down the controller in the
> event of a controller lockup.
> The default value is 0.
> .TP
> .BR lockup_action= { none | reboot | panic }
> Specifies the action the driver takes when a controller
> lockup is detected.
> The default action is
> .BR none .
> .TS
> l l
> ---
> l l.
> parameter    action
> \fBnone\fP    take controller offline only
> \fBreboot\fP    reboot the system
> \fBpanic\fP    panic the system
> .TE
> .RE
> .SH FILES
> .SS Device nodes
> Logical drives are accessed via the SCSI disk driver
> .RI ( sd ),
> tape drives via the SCSI tape driver
> .RI ( st ),
> and the RAID controller via the SCSI generic driver
> .RI ( sg ),
> with device nodes named
> .IR /dev/sd *,
> .IR /dev/st *,
> and
> .IR /dev/sg *,
> respectively.
> .SS SmartPQI-specific host attribute files in \f[BI]/sys\fP
> .TP
> .IR /sys/class/scsi_host/host * /rescan
> The host
> .I rescan
> attribute is a write-only attribute.
> Writing to this attribute will cause the driver to scan for new,
> changed, or removed devices (e.g., hot-plugged tape drives, or newly
> configured or deleted logical drives) and notify the SCSI mid-layer of
> any changes detected.
> Usually this action is triggered automatically by configuration
> changes, so the user should not normally have to write to this file.
> Doing so may be useful when hot-plugging devices such as tape drives or
> entire storage boxes containing pre-configured logical drives.
> .TP
> .IR /sys/class/scsi_host/host * /version
> The host
> .I version
> attribute is a read-only attribute.
> This attribute contains the driver version and the controller firmware
> version.
> .IP
> For example:
> .IP
> .in +4n
> .EX
> $ \c
> .B cat /sys/class/scsi_host/host1/version
> driver: 1.1.2\-126
> firmware: 1.29\-112
> .EE
> .in
> .TP
> .IR /sys/class/scsi_host/host * /lockup_action
> The host
> .I lockup_action
> attribute is a read/write attribute.
> This attribute will cause the driver to perform a specific action in the
> unlikely event that a controller lockup has been detected.
> See
> .BR OPTIONS
> above
> for an explanation of the
> .I lockup_action
> values.
> .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
> In the file specifications below,
> .I c
> stands for the number of the appropriate SCSI controller,
> .I b
> is the bus number,
> .I t
> the target number, and
> .I l
> is the logical unit number (LUN).
> .TP
> .IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level
> The
> .I raid_level
> attribute is read-only.
> This attribute contains the RAID level of each logical drive.
> .IP
> For example:
> .IP
> .in +4n
> .EX
> $ \c
> .B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level
> RAID 0
> .EE
> .in
> .TP
> .IR /sys/class/scsi_disk/c : b : t : l/device/sas_address
> The
> .I sas_address
> attribute is read-only.
> This attribute contains the unique identifier of the disk.
> .IP
> For example:
> .IP
> .in +4n
> .EX
> $ \c
> .B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address
> 0x5001173d028543a2
> .EE
> .in
> .TP
> .IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled
> The
> .I ssd_smart_path_enabled
> attribute is read-only.
> .\" FIXME
> .\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
> This attribute is for ioaccel-enabled volumes.
> Contains 1 if ioaccel is enabled for the volume and 0 otherwise.

ioaccel  is  an  alternative driver submission path that allows the
driver to send  I/O  requests  directly  to  backend  SCSI  devices
bypassing   the  controller  firmware.  This  results  in  an
increase in performance. This method is used  for  HBA  disks
and for LOGICAL VOLUMES comprised of SSDs.

> .IP
> For example:
> .IP
> .in +2n
> .EX
> $ \c
> .B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
> 0
> .EE
> .in
> .SH VERSIONS
> The
> .B smarpqi
> driver was added in Linux 4.9.
> .SH NOTES
> .SS Configuration
> To configure Microsemi Smart Family controllers, please refer to the
> controller's User Guide documentation.
> .\" FIXME
> .\" Does this manual have a title?  Is it freely available online?
> .\" Does it have a stable URL?  Can this information be moved to the SEE
> .\" ALSO section?

To configure Microsemi Smart Family controllers, please refer to the 
controller’s Installation and User’s Guide documentation which can be found by
searching for the controller at https://storage.microsemi.com/

> .SH SEE ALSO
> .BR cciss (4),
> .BR hpsa (4),
> .BR sd (4),
> .BR st (4)
> .PP
> .I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss
> in the Linux kernel source tree.
> 
> 
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[Michael Kerrisk (man-pages)]

Hello Don,

>> .\" FIXME
>> .\" What is "ioaccel"?  This string appears nowhere in man-pages HEAD.
>> This attribute is for ioaccel-enabled volumes.
>> Contains 1 if ioaccel is enabled for the volume and 0 otherwise.
>
> ioaccel  is  an  alternative driver submission path that allows the
> driver to send  I/O  requests  directly  to  backend  SCSI  devices
> bypassing   the  controller  firmware.  This  results  in  an
> increase in performance. This method is used  for  HBA  disks
> and for LOGICAL VOLUMES comprised of SSDs.

Thanks. I added that text to the page.

>> .IP
>> For example:
>> .IP
>> .in +2n
>> .EX
>> $ \c
>> .B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled
>> 0
>> .EE
>> .in
>> .SH VERSIONS
>> The
>> .B smarpqi
>> driver was added in Linux 4.9.
>> .SH NOTES
>> .SS Configuration
>> To configure Microsemi Smart Family controllers, please refer to the
>> controller's User Guide documentation.
>> .\" FIXME
>> .\" Does this manual have a title?  Is it freely available online?
>> .\" Does it have a stable URL?  Can this information be moved to the SEE
>> .\" ALSO section?
>
> To configure Microsemi Smart Family controllers, please refer to the
> controller’s Installation and User’s Guide documentation which can be found by
> searching for the controller at https://storage.microsemi.com/

What exactly does one search for? I could not easily find the User's Guide.

Cheers,

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

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="utf-8", Size: 969 bytes --]


> > To configure Microsemi Smart Family controllers, please refer to the
> > controller’s Installation and User’s Guide documentation which can be found
> by
> > searching for the controller at https://storage.microsemi.com/
> 
> What exactly does one search for? I could not easily find the User's Guide.
> 
> Cheers,
> 
> Michael
> --

I searched the Microsemi site for the controller (example 2100-8i)

And came to this page:
https://storage.microsemi.com/en-us/support/sas/sas/aha-2100-8i/

Yields this document:
http://download.adaptec.com/pdfs/user_guides/microsemi_smarthba_smartraid_iug_10_2017.pdf



> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
N‹§²æìr¸›yúèšØb²X¬¶Ç§vØ^–)Þº{.nÇ+‰·¥Š{±™©âžØ^n‡r¡ö¦zË\x1aëh™¨è­Ú&¢îý»\x05ËÛÔØï¦v¬Îf\x1dp)¹¹br	šê+€Ê+zf£¢·hšˆ§~†­†Ûiÿûàz¹\x1e®w¥¢¸?™¨è­Ú&¢)ߢ^[f

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[Michael Kerrisk (man-pages)]

Hi Don

On 11/17/2017 05:56 PM, Don Brace wrote:
> 
>>> To configure Microsemi Smart Family controllers, please refer to the
>>> controller’s Installation and User’s Guide documentation which can be found
>> by
>>> searching for the controller at https://storage.microsemi.com/
>>
>> What exactly does one search for? I could not easily find the User's Guide.
>>
>> Cheers,
>>
>> Michael
>> --
> 
> I searched the Microsemi site for the controller (example 2100-8i)
> 
> And came to this page:
> https://storage.microsemi.com/en-us/support/sas/sas/aha-2100-8i/
> 
> Yields this document:
> http://download.adaptec.com/pdfs/user_guides/microsemi_smarthba_smartraid_iug_10_2017.pdf
Okay, I get it now. The thing was that the wording made it sound
like there was a single User Guide, which was confusing me (and, 
I suspect, Branden). I've reworded your proposed  text to:

       To configure a Microsemi Smart Family  controller,  refer  to  the
       User Guide for the controller, which can be found by searching for
       the specific controller at ⟨https://storage.microsemi.com/⟩.

I've merged the page into master, and pushed to Git. Thanks for
contributing the page!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

> -----Original Message-----
> From: Michael Kerrisk (man-opages) [mailto:mtk.manpages@gmail.com]
> Sent: Tuesday, October 31, 2017 2:11 AM
> To: Don Brace <don.brace@microsemi.com>; G. Branden Robinson
> <g.branden.robinson@gmail.com>
> Cc: mtk.manpages@gmail.com; linux-man@vger.kernel.org; Gerry Morong
> <gerry.morong@microsemi.com>; John Hall <John.Hall@microsemi.com>;
> Kevin Barnett <kevin.barnett@microsemi.com>; Bader Ali - Saleh
> <bader.alisaleh@microsemi.com>; Scott Teel <scott.teel@microsemi.com>;
> Justin Lindley <justin.lindley@microsemi.com>; Scott Benesh
> <scott.benesh@microsemi.com>
> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> 
> EXTERNAL EMAIL
> 
> 
> Hello Don,
> 
> On 10/21/2017 12:10 AM, Don Brace wrote:
> >> -----Original Message-----
> >> From: G. Branden Robinson [mailto:g.branden.robinson@gmail.com]
> >> Sent: Thursday, October 19, 2017 4:36 PM
> >> To: Don Brace <don.brace@microsemi.com>
> >> Cc: mtk.manpages@gmail.com; linux-man@vger.kernel.org; Gerry Morong
> >> <gerry.morong@microsemi.com>; John Hall <John.Hall@microsemi.com>;
> >> Kevin Barnett <kevin.barnett@microsemi.com>; Bader Ali - Saleh
> >> <bader.alisaleh@microsemi.com>; Scott Teel <scott.teel@microsemi.com>;
> >> Justin Lindley <justin.lindley@microsemi.com>; Scott Benesh
> >> <scott.benesh@microsemi.com>
> >> Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page
> >>
> >> At 2017-10-18T10:10:39-0500, Don Brace wrote:
> >>> This patch contains the initial submission of the
> >>> smartpqi man page.
> >>
> >> Hi Don,
> >>
> >> Please find attached my recommended changes.
> >>
> >> I made many changes, most of them formatting-related.
> >
> > Really appreciate your effort!
> 
> My apologies for not weighing in sooner. I see you got a lot of input
> from Branden! (Thanks, Branden!) How shall we move forward? Possibilities:
> 
> 1. I apply your original patch as is.
> 2. You rework your patch incorporating those changes from Branden
>     that seem uncontroversial to you, and I apply, and then we
>     discuss any further changes that may be needed.
> 3. If all changes from Branden seem uncontroversial, I apply\
>     your patch, his patch, and then we  discuss any further changes
>     that may be needed.
> 
> I suspect 2 or 3 is the way to go, but I await your input.
> 
> Thanks,
> 
> Michael

I like option #3.

Re: [PATCH] smartpqi: initial submit of smartpqi man page

[Theodore Dubois]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=utf-8, Size: 357 bytes --]

> N‹§ēæėrļ›yúčšØbēXŽķĮ§vØ^–)Þš{.nĮ+‰·ĨŠ{ą™ĐâžØ^n‡rĄöĶzË\x1aëh™Ļč­Ú&Ēø\x1eŪGŦéhŪ\x03(­éšŽŠÝĒj"ú\x1aķ^[m§ĸïęäzđޖŠāþfĢĒ·hšˆ§~ˆm

what is this?

~TheodoreN‹§²æìr¸›yúèšØb²X¬¶Ç§vØ^–)Þº{.nÇ+‰·¥Š{±™©âžØ^n‡r¡ö¦zË\x1aëh™¨è­Ú&¢îý»\x05ËÛÔØï¦v¬Îf\x1dp)¹¹br	šê+€Ê+zf£¢·hšˆ§~†­†Ûiÿûàz¹\x1e®w¥¢¸?™¨è­Ú&¢)ߢ^[f

RE: [PATCH] smartpqi: initial submit of smartpqi man page

[Don Brace]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="utf-8", Size: 795 bytes --]

________________________________________
From: Theodore Dubois [tblodt@icloud.com]
Sent: Tuesday, November 07, 2017 11:06 AM
To: Don Brace
Cc: Michael Kerrisk (man-opages); G. Branden Robinson; linux-man@vger.kernel.org; Gerry Morong; John Hall; Kevin Barnett; Bader Ali - Saleh; Scott Teel; Justin Lindley; Scott Benesh
Subject: Re: [PATCH] smartpqi: initial submit of smartpqi man page

EXTERNAL EMAIL


> N‹§ēæėrļ›yúčšØbēXŽķĮ§vØ^–)Þš{.nĮ+‰·ĨŠ{ą™ĐâžØ^n‡rĄöĶzË?ëh™Ļč­Ú&Ēø?ŪGŦéhŪ?(­éšŽŠÝĒj"ú?ķ?m§ĸïęäzđޖŠāþfĢĒ·hšˆ§~ˆm

what is this?

~Theodore

Bad signature.
Sorry about that.

N‹§²æìr¸›yúèšØb²X¬¶Ç§vØ^–)Þº{.nÇ+‰·¥Š{±™©âžØ^n‡r¡ö¦zË\x1aëh™¨è­Ú&¢îý»\x05ËÛÔØï¦v¬Îf\x1dp)¹¹br	šê+€Ê+zf£¢·hšˆ§~†­†Ûiÿûàz¹\x1e®w¥¢¸?™¨è­Ú&¢)ߢ^[f