Skip to contentSkip to conversation

smartpqi man page updates

PATCH Superseded Don Brace 2 participants 10 messages Oct 3, 2023 – Oct 8, 2023 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v6 of 10 Superseded Latest is v10 →

lore
Share & tools
lore

Don Brace

author
#0 lore raw

v6 cover smartpqi man page updates

These patches are based the man page content found in
git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git

The Linux man page smartpqi.4 is out-of-date with the man page provided by our out-of-box driver. This patch series brings the Linux man page up to date.

The changes are:
smarpqi-update-copyright-and-email-addresses
The copyright, email, and URLs have changed to Microchip.
smartpqi-update-module-parameter-descriptions
We changed some descriptions of some of our module parameters. Clarifies what their default values are.
smartpqi-add-module-parameter_disable_managed_interrupts
We added a new module parameter to allow users to disable how interrupts are managed allowing them to change affinity.
smartpqi-add-module-parameter_ctrl_ready_timeout
We added a new module parameter to allow users to change how
long the driver waits for the controller becomes ready. The
default is 180 seconds and can be changed from 30-1800 seconds.
The longer wait times are useful for large configurations.
smartpqi-update_FILES_section
Minor change to the FILES section. The word "Logical" was changed to "Disk" since HBA disks are also supported.
smartpqi-update-host-attribute-descriptions
Updated the descriptions of existing host attributes accessed through sysfs.
smartpqi-update-device-attribute-descriptions
Updated the descriptions of existing device attributes accessed through sysfs.
smartpqi-add-host-attributes
We added some new host attributes:
enable_stream_detection: For RAID5/6 sequential write operations, this
can help increase IOPS. Reduces Read/Modify/Write operations. This is for AIO capable devices. (Volumes consisting of non-rotating media).
enable_r5_writes: Send down RAID 5 write operations down the AIO path.
enable_r6_writes: Send down RAID 6 write operations down the AIO path.
smartpqi-add-device-attributes
We added some new device attributes:
lunid - SCSI LUN ID
unique_id - 16-byte ID that uniquely identifies the device within the controller. path_info - Host:Bus:Target:Lun (h:b:t:l), device type, Active/Inactive raid_bypass_cnt - Count of the number of request sent down the AIO path. sas_ncq_prio_enable - Enables SATA NCQ priority support.
smartpqi-add-sg-entry-to-see_also
Simple addition of the sg(4) driver to the SEE ALSO section.

Changes since V5:
smartpqi: add module parameter ctrl_ready_timeout
Forgot to change the range of values for ctrl_ready_timeout. Changed 0 or 30,1800 to 0 or [30,1800]
Alejandro Colomar <[email protected]>

Sorry about that. Thanks for your review.

Changes since V4:
Added patch smartpqi-add-HISTORY-section
Added HISTORY section to explain that the sysfs entry for 'version' was replaced by two new sysfs entries: driver_version, and firmware_version.

smartpqi: add module parameter ctrl_ready_timeout
Minor update to parameter description due to suggestion by:
Alejandro Colomar <[email protected]>

Changes since V3:
Updated content for the following pages due to reviews by:
Alejandro Colomar <[email protected]>

smartpqi: add module parameter ctrl_ready_timeout

smartpqi: update FILES section

smartpqi: update host attribute descriptions

smartpqi: add host attributes

smartpqi: add device attributes

The other patches have already been applied and were removed from the remaining patch set after a rebase.

Thanks for your attention and reviews for these patches.

Changes since V2:
Resending due to bad e-mail address for maintainer.

Changes since V1:
Broke up the large patch into multiple smaller patches due to review by:
Alejandro Colomar <[email protected]>

---

Don Brace (6):
smartpqi: add module parameter ctrl_ready_timeout
smartpqi: update FILES section
smartpqi: update host attribute descriptions
smartpqi: add host attributes
smartpqi: add device attributes
smartpqi: add HISTORY section

 man4/smartpqi.4 | 194 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 174 insertions(+), 20 deletions(-)
Signature · 1 line
2.42.0.296.g493f462273
author
#1 lore raw

PATCH v6 1/6 smartpqi: add module parameter ctrl_ready_timeout

Allow user to change the length of time that the driver will wait for the controller to become ready.

---
 man4/smartpqi.4 | 7 +++++++
 1 file changed, 7 insertions(+)
man4/smartpqi.4 +7 -0
index 32f9240e37f2..e12d82296108 100644
@@ -17,6 +17,7 @@ smartpqi \- Microchip Smart Storage SCSI driver
 .RB [ expose_ld_first= { 0 | 1 }]
 .RB [ hide_vsep= { 0 | 1 }]
 .RB [ disable_managed_interrupts= { 0 | 1 }]
+.RB [ ctrl_ready_timeout= { 0 | [30, 1800] }]
 .YS
 .SH DESCRIPTION
 .B smartpqi
@@ -107,6 +108,12 @@ Disables driver utilization of Linux kernel managed interrupts for controllers.
 The managed interrupts feature automatically distributes interrupts
 to all available CPUs and assigns SMP affinity.
 The default value is 0 (managed interrupts enabled).
+.TP
+.BR ctrl_ready_timeout= { 0 | [30, 1800] }
+This option specifies the timeout in seconds for the driver to wait
+for the controller to be ready.
+The valid range is 0 or [30, 1800]. The default value is 0,
+which causes the driver to use a timeout of 180 seconds.
 .SH FILES
 .SS Device nodes
 Logical drives are accessed via the SCSI disk driver
Signature · 1 line
2.42.0.296.g493f462273
#2 lore raw

Re: [PATCH v6 1/6] smartpqi: add module parameter ctrl_ready_timeout

Quoted 8 lines · Don Brace

Allow user to change the length of time that the driver will wait for the controller to become ready.

Thanks. Patch applied. I applied the following minor formatting fix to your patch.

Cheers,
Alex

man4/smartpqi.4 +4 -2
index e12d82296..a213b3b70 100644
@@ -17,7 +17,7 @@ .SH SYNOPSIS
 .RB [ expose_ld_first= { 0 | 1 }]
 .RB [ hide_vsep= { 0 | 1 }]
 .RB [ disable_managed_interrupts= { 0 | 1 }]
-.RB [ ctrl_ready_timeout= { 0 | [30, 1800] }]
+.RB [ ctrl_ready_timeout= { 0 |[ 30 , 1800 ]}]
 .YS
 .SH DESCRIPTION
 .B smartpqi
@@ -112,7 +112,9 @@ .SS Boot options
 .BR ctrl_ready_timeout= { 0 | [30, 1800] }
 This option specifies the timeout in seconds for the driver to wait
 for the controller to be ready.
-The valid range is 0 or [30, 1800]. The default value is 0,
+The valid range is 0 or
+.RB [ 30 ", " 1800 ].
+The default value is 0,
 which causes the driver to use a timeout of 180 seconds.
 .SH FILES
 .SS Device nodes
Quoted 32 lines
---
 man4/smartpqi.4 | 7 +++++++
 1 file changed, 7 insertions(+)
man4/smartpqi.4 +7 -0
index 32f9240e37f2..e12d82296108 100644
@@ -17,6 +17,7 @@ smartpqi \- Microchip Smart Storage SCSI driver
 .RB [ expose_ld_first= { 0 | 1 }]
 .RB [ hide_vsep= { 0 | 1 }]
 .RB [ disable_managed_interrupts= { 0 | 1 }]
+.RB [ ctrl_ready_timeout= { 0 | [30, 1800] }]
 .YS
 .SH DESCRIPTION
 .B smartpqi
@@ -107,6 +108,12 @@ Disables driver utilization of Linux kernel managed interrupts for controllers.
 The managed interrupts feature automatically distributes interrupts
 to all available CPUs and assigns SMP affinity.
 The default value is 0 (managed interrupts enabled).
+.TP
+.BR ctrl_ready_timeout= { 0 | [30, 1800] }
+This option specifies the timeout in seconds for the driver to wait
+for the controller to be ready.
+The valid range is 0 or [30, 1800]. The default value is 0,
+which causes the driver to use a timeout of 180 seconds.
 .SH FILES
 .SS Device nodes
 Logical drives are accessed via the SCSI disk driver
Signature · 1 line
2.42.0.296.g493f462273
Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#3 lore raw

PATCH v6 2/6 smartpqi: update FILES section

In reply to Don Brace

Minor description changes for Device nodes.

Change "Logical drives" to "Disk drives".

---
 man4/smartpqi.4 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man4/smartpqi.4 +1 -1
index e12d82296108..92bc5402b866 100644
@@ -116,7 +116,7 @@ The valid range is 0 or [30, 1800]. The default value is 0,
 which causes the driver to use a timeout of 180 seconds.
 .SH FILES
 .SS Device nodes
-Logical drives are accessed via the SCSI disk driver
+Disk drives are accessed via the SCSI disk driver
 .RI ( sd ),
 tape drives via the SCSI tape driver
 .RI ( st ),
Signature · 1 line
2.42.0.296.g493f462273
#4 lore raw

Re: [PATCH v6 2/6] smartpqi: update FILES section

Hi Don,

Quoted 9 lines · Don Brace

Minor description changes for Device nodes.

Change "Logical drives" to "Disk drives".

Patch applied. Thanks. I've reworded the commit message to:

smartpqi.4: FILES: Change "Logical drives" to "Disk drives" for /dev/sd*.

Cheers,
Alex

Quoted 20 lines
---
 man4/smartpqi.4 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
man4/smartpqi.4 +1 -1
index e12d82296108..92bc5402b866 100644
@@ -116,7 +116,7 @@ The valid range is 0 or [30, 1800]. The default value is 0,
 which causes the driver to use a timeout of 180 seconds.
 .SH FILES
 .SS Device nodes
-Logical drives are accessed via the SCSI disk driver
+Disk drives are accessed via the SCSI disk driver
 .RI ( sd ),
 tape drives via the SCSI tape driver
 .RI ( st ),
Signature · 1 line
2.42.0.296.g493f462273
Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#5 lore raw

PATCH v6 3/6 smartpqi: update host attribute descriptions

In reply to Don Brace

Minor description changes for host attributes.

Just some small changes to the host attribute descriptions. Remove the "version" sysfs entry. This entry was changed to two sysfs entries: driver_version and firmware_version.

---
 man4/smartpqi.4 | 21 ++-------------------
 1 file changed, 2 insertions(+), 19 deletions(-)
man4/smartpqi.4 +2 -19
index 92bc5402b866..5ff134a4821a 100644
@@ -136,29 +136,12 @@ The host
 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
+configured or deleted logical volumes) 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
+entire storage boxes containing pre-configured logical volumes.
 .in
 .TP
 .IR /sys/class/scsi_host/host * /lockup_action
Signature · 1 line
2.42.0.296.g493f462273
#6 lore raw

Re: [PATCH v6 3/6] smartpqi: update host attribute descriptions

Hi Don,

Quoted 5 lines · Don Brace

Minor description changes for host attributes.

Just some small changes to the host attribute descriptions. Remove the "version" sysfs entry. This entry was changed to two sysfs entries: driver_version and firmware_version.

Please do the removal in a patch of its own, separate from the small wording fixes.

Also, it would be good to merge that one with the one that adds HISTORY.

Thanks,
Alex

Quoted 49 lines
---
 man4/smartpqi.4 | 21 ++-------------------
 1 file changed, 2 insertions(+), 19 deletions(-)
man4/smartpqi.4 +2 -19
index 92bc5402b866..5ff134a4821a 100644
@@ -136,29 +136,12 @@ The host
 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
+configured or deleted logical volumes) 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
+entire storage boxes containing pre-configured logical volumes.
 .in
 .TP
 .IR /sys/class/scsi_host/host * /lockup_action
Signature · 1 line
2.42.0.296.g493f462273
Signature · 1 line
<https://www.alejandro-colomar.es/>
author
#7 lore raw

PATCH v6 4/6 smartpqi: add host attributes

In reply to Don Brace

Add in some host level sysfs entries:
enable_stream_detection - Send RAID 5/6 writes down the normal I/O path.
Allow for full-stripe write requests.
ssd_smart_path_enabled - Indicates that our Accelerated I/O path is

                          enabled. (AIO).

enable_r5_writes - Allow RAID 5 write operations down the AIO path.
enable_r6_writes - Allow RAID 6 write operations down the AIO path.

---
 man4/smartpqi.4 | 62 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
man4/smartpqi.4 +62 -0
index 5ff134a4821a..6305e15a912b 100644
@@ -236,6 +236,68 @@ $ \c
 Adaptec
 .EE
 .in
+.TP
+.I /sys/class/scsi_host/host*/enable_stream_detection
+The
+.I enable_stream_detection
+attribute is read-write.
+This attribute enables/disables stream detection in the driver.
+Enabling stream detection can improve sequential write performance for
+ioaccel-enabled volumes. See the
+.BI ssd_smart_path_enabled
+disk attribute section for details on ioaccel-enabled volumes.
+The default value is 1 (stream detection enabled).
+.IP
+Enable example:
+.IP
+.in +4n
+.EX
+$ \c
+.B echo 1 > /sys/class/scsi_host/host1/enable_stream_detection
+.EE
+.in
+.TP
+.I /sys/class/scsi_host/host*/enable_r5_writes
+The
+.I enable_r5_writes
+attribute is read-write.
+This attribute enables/disables RAID 5 write operations for ioaccel-enabled
+volumes.
+Enabling can improve sequential write performance.
+See the
+.BI ssd_smart_path_enabled
+disk attribute section for details on ioaccel-enabled volumes.
+The default value is 1 (RAID 5 writes enabled).
+.IP
+Enable example:
+.IP
+.in +4n
+.EX
+$ \c
+.B echo 1 > /sys/class/scsi_host/host1/enable_r5_writes
+.EE
+.in
+.TP
+.I /sys/class/scsi_host/host*/enable_r6_writes
+The
+.I enable_r6_writes
+attribute is read-write.
+This attribute enables/disables RAID 6 write operations for
+ioaccel-enabled volumes.
+Enabling can improve sequential write performance.
+See the
+.BI ssd_smart_path_enabled
+disk attribute section for details on ioaccel-enabled volumes.
+The default value is 1 (RAID 6 writes enabled).
+.IP
+Enable example:
+.IP
+.in +4n
+.EX
+$ \c
+.B echo 1 > /sys/class/scsi_host/host1/enable_r6_writes
+.EE
+.in
 .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 In the file specifications below,
 .I c
Signature · 1 line
2.42.0.296.g493f462273
author
#8 lore raw

PATCH v6 5/6 smartpqi: add device attributes

In reply to Don Brace

Add in some device level sysfs entry descriptions:
lunid
unique_id
path_info
raid_bypass_cnt
sas_ncq_prio_enable

These have already been provided by the driver.

---
 man4/smartpqi.4 | 95 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
man4/smartpqi.4 +95 -0
index 6305e15a912b..7477ee714e5b 100644
@@ -362,6 +362,101 @@ $ \c
 0
 .EE
 .in
+.TP
+.I /sys/class/scsi_disk/c : b : t : l/device/lunid
+The
+.I lunid
+attribute is read-only.
+This attribute contains the SCSI LUN ID for the device.
+.IP
+For example:
+.IP
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/13:1:0:3/device/lunid
+0x0300004000000000
+.EE
+.in
+.TP
+.I /sys/class/scsi_disk/c : b : t : l/device/unique_id
+The
+.I unique_id
+attribute is read-only.
+This attribute contains a 16-byte ID that uniquely identifies the device
+within the controller.
+.IP
+For example:
+.IP
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/13:1:0:3/device/unique_id
+600508B1001C6D4723A8E98D704FDB94
+.EE
+.in
+.TP
+.I /sys/class/scsi_disk/c : b : t : l/device/path_info
+The
+.I path_info
+attribute is read-only.
+This attribute contains the c:b:t:l of the device along with the device
+type and whether the device is Active or Inactive.
+If the device is an HBA device,
+.I path_info
+will also display the PORT, BOX, and BAY the device is plugged into.
+.IP
+For example:
+.IP
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/13:1:0:3/device/path_info
+[13:1:0:3]    Direct-Access     Active
+
+$ \c
+.B cat /sys/class/scsi_disk/12:0:9:0/device/path_info
+[12:0:9:0]  Direct-Access   PORT: C1 BOX: 1 BAY: 14 Inactive
+[12:0:9:0]  Direct-Access   PORT: C0 BOX: 1 BAY: 14 Active
+.EE
+.in
+.TP
+.I /sys/class/scsi_disk/13:1:0:3/device/raid_bypass_cnt
+The
+.I raid_bypass_cnt
+attribute is read-only.
+This attribute contains the number of I/O requests that have gone
+through the ioaccel path for ioaccel-enabled volumes.
+See the
+.BI ssd_smart_path_enabled
+disk attribute section for details on ioaccel-enabled volumes.
+.IP
+For example:
+.IP
+.in +4n
+.EX
+$ \c
+.B cat /sys/class/scsi_disk/13:1:0:3/device/raid_bypass_cnt
+0x300
+.EE
+.in
+.TP
+.I /sys/class/scsi_disk/13:1:0:3/device/sas_ncq_prio_enable
+The
+.I sas_ncq_prio_enable
+attribute is read/write.
+This attribute enables SATA NCQ priority support.
+This attribute works only when device has NCQ support and
+controller firmware can handle IO with NCQ priority attribute.
+.IP
+For example:
+.IP
+.in +4n
+.EX
+$ \c
+.B echo 1 > /sys/class/scsi_disk/13:1:0:3/device/sas_ncq_prio_enable
+.EE
+.in
 .SH VERSIONS
 The
 .B smartpqi
Signature · 1 line
2.42.0.296.g493f462273
author
#9 lore raw

PATCH v6 6/6 smartpqi: add HISTORY section

In reply to Don Brace

Enumerate old sysfs entries replaced by newer entries.

---
 man4/smartpqi.4 | 7 +++++++
 1 file changed, 7 insertions(+)
man4/smartpqi.4 +7 -0
index 7477ee714e5b..4a2d44d6101b 100644
@@ -468,6 +468,13 @@ refer to the User Guide for the controller,
 which can be found by searching for the specific controller at
 .UR https://www.microchip.com/design-centers/storage
 .UE .
+.SH HISTORY
+.I /sys/class/scsi_host/host*/version
+was replaced by two sysfs entries:
+.IP
+.I /sys/class/scsi_host/host*/driver_version
+.IP
+.I /sys/class/scsi_host/host*/firmware_version
 .SH SEE ALSO
 .BR cciss (4),
 .BR hpsa (4),
Signature · 1 line
2.42.0.296.g493f462273