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:
smartpqi_branden.man
Description: Unix manual page
--- 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@xxxxxxxxxxxxx>
-.br
-.nf
-This man page was written by Kevin Barnett <kevin.barnett@xxxxxxxxxxxxx> and
-.br
-Don Brace <don.brace@xxxxxxxxxxxxx>
-.fi
+.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss
+in the Linux kernel source tree.
Attachment:
signature.asc
Description: PGP signature
