[PATCH v8 0/3] smartpqi man page updates

[PATCH v8 0/3] smartpqi man page updates

[Don Brace]

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 V7:

    Three patches left from the original series.
          smartpqi-update-host-attribute-descriptions
          smartpqi-remove-sysfs-entry-for-version
          smartpqi-add-device-attributes

    The changes since V6 are:
    smartpqi-update-host-attribute-descriptions
      I had removed some patch context, but did not update the patch
      description to reflect the updated patch.
      Alejandro Colomar <alx@kernel.org>
      Link: https://marc.info/?l=linux-man&m=169732291731554&w=2
    smartpqi: add device attributes
      Changed the sysfs path entry for each device attribute from ".I" to ".IR".
      Alejandro Colomar <alx@kernel.org>
      Link: https://marc.info/?l=linux-man&m=169732400031940&w=2

    Thanks Alejandro for your review and suggestions.

Changes since V6:
    patch "(smartpqi-add-module-parameter_ctrl_ready_timeout)" was
    applied.
    patch "(smartpqi-update_FILES_section)" was applied.
    Some minor updates requested by Alejandro Colomar <alx@kernel.org>
    Thanks Alejandro for your review and suggestions.

    The V7 updates include the following patches:

    smartpqi-update-host-attribute-descriptions
      Moved the sysfs entry removal description for "version"
    smartpqi-remove-sysfs-entry-for-version
      New patch for removal of sysfs entry for "version".
      Added HISTORY section.
      Alejandro Colomar <alx@kernel.org>
      Link: https://marc.info/?l=linux-man&m=169680471921234&w=2

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 <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZRtfS8DIxlqNN-XH@debian/
      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.
      Suggested-by: Alejandro Colomar <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZRtgG396-1Cj4gn2@debian/

    smartpqi: add module parameter ctrl_ready_timeout
      Minor update to parameter description due to suggestion by:
      Alejandro Colomar <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZRtfS8DIxlqNN-XH@debian/

Changes since V3:
    Updated content for the following pages due to reviews by:
    Alejandro Colomar <alx@kernel.org>

      smartpqi: add module parameter ctrl_ready_timeout
      Link: https://lore.kernel.org/linux-man/axwssorupkp6fv3b7zqgjyd243exvhlw7rle2ftyy43jxhm4yf@woxzbz4hm766/

      smartpqi: update FILES section
      Link: https://lore.kernel.org/linux-man/fwpvmbussvf2zzug5bsqhrd7mvwcvdllvna6a4ngke3hw6w5am@b4icgpgirck4/

      smartpqi: update host attribute descriptions
      Link: https://lore.kernel.org/linux-man/ss7k5ooeoi7y56j6otvdpwhgd5yltzk6nt5l6ujiiupxzpmrdx@zrcvhw364ejx/

      smartpqi: add host attributes
      Link: https://lore.kernel.org/linux-man/nbt3jt7busx6akj7ykaxs7df6vlbbxtvcdy4ckvlp7saol3djl@rb6ckz3lzzot/

      smartpqi: add device attributes
      Link: https://lore.kernel.org/linux-man/ytcsqleu53iwpn5gsjmmuoqz2cy5oegvvafwlwxn422bcn3a5e@ne3khvixxzuq/

    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 <alx@kernel.org>
    Link: https://lore.kernel.org/all/096ed4d5-945f-5ac9-eba3-c9be5d32cfe8@kernel.org/

---

Don Brace (3):
  smartpqi: update host attribute descriptions
  smartpqi: remove sysfs entry for version
  smartpqi: add device attributes

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

-- 
2.42.0.357.g59167d7d09

[PATCH v8 1/3] smartpqi: update host attribute descriptions

[Don Brace]

Minor description changes for host attributes.

Change the word "drives" to "volumes".

Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
Reviewed-by: Scott Teel <scott.teel@microchip.com>
Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
Signed-off-by: Don Brace <don.brace@microchip.com>
---
 man4/smartpqi.4 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 393545d3728d..1e5b6d76f548 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -138,12 +138,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.
+entire storage boxes containing pre-configured logical volumes.
 .TP
 .IR /sys/class/scsi_host/host * /version
 The host
-- 
2.42.0.357.g59167d7d09

Re: [PATCH v8 1/3] smartpqi: update host attribute descriptions

[Alejandro Colomar]

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

Hi Don,

On Mon, Oct 16, 2023 at 11:04:01AM -0500, Don Brace wrote:
> Minor description changes for host attributes.
> 
> Change the word "drives" to "volumes".

But why is volumes more appropriate?  Please justify.

Thanks,
Alex

> 
> Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
> Reviewed-by: Scott Teel <scott.teel@microchip.com>
> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
> Signed-off-by: Don Brace <don.brace@microchip.com>
> ---
>  man4/smartpqi.4 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
> index 393545d3728d..1e5b6d76f548 100644
> --- a/man4/smartpqi.4
> +++ b/man4/smartpqi.4
> @@ -138,12 +138,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.
> +entire storage boxes containing pre-configured logical volumes.
>  .TP
>  .IR /sys/class/scsi_host/host * /version
>  The host
> -- 
> 2.42.0.357.g59167d7d09
> 

-- 
<https://www.alejandro-colomar.es/>

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

[PATCH v8 2/3] smartpqi: remove sysfs entry for version

[Don Brace]

Remove the "version" sysfs entry. This entry was changed into
two sysfs entries: driver_version and firmware_version.

Add HISTORY section.
Enumerate old sysfs entries replaced by newer entries.

Signed-off-by: Don Brace <don.brace@microchip.com>
Suggested-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Don Brace <don.brace@microchip.com>
---
 man4/smartpqi.4 | 25 +++++++------------------
 1 file changed, 7 insertions(+), 18 deletions(-)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 1e5b6d76f548..89387c0498fd 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -145,24 +145,6 @@ 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 volumes.
 .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
@@ -330,6 +312,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),
-- 
2.42.0.357.g59167d7d09

[PATCH v8 3/3] smartpqi: add device attributes

[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.

Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
Reviewed-by: Scott Teel <scott.teel@microchip.com>
Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
Signed-off-by: Don Brace <don.brace@microchip.com>
---
 man4/smartpqi.4 | 95 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index 89387c0498fd..00a8146eba6b 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -301,6 +301,101 @@ $ \c
 0
 .EE
 .in
+.TP
+.IR /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
+.IR /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
+.IR /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
+.IR /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
+.IR /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
-- 
2.42.0.357.g59167d7d09

Re: [PATCH v8 3/3] smartpqi: add device attributes

[Alejandro Colomar]

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

Hi Don,

On Mon, Oct 16, 2023 at 11:04:03AM -0500, Don Brace wrote:
> 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.
> 
> Reviewed-by: Scott Benesh <scott.benesh@microchip.com>
> Reviewed-by: Scott Teel <scott.teel@microchip.com>
> Reviewed-by: Mike McGowen <mike.mcgowen@microchip.com>
> Reviewed-by: Kevin Barnett <kevin.barnett@microchip.com>
> Signed-off-by: Don Brace <don.brace@microchip.com>
> ---
>  man4/smartpqi.4 | 95 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 95 insertions(+)
> 
> diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
> index 89387c0498fd..00a8146eba6b 100644
> --- a/man4/smartpqi.4
> +++ b/man4/smartpqi.4
> @@ -301,6 +301,101 @@ $ \c
>  0
>  .EE
>  .in
> +.TP
> +.IR /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
> +.IR /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
> +.IR /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
> +.IR /sys/class/scsi_disk/13:1:0:3/device/raid_bypass_cnt

This is probably a typo.  I guess you wanted to use c:b:t:l too.

> +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
> +.IR /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
> -- 
> 2.42.0.357.g59167d7d09
> 

I've applied a few formatting fixes to the patch.  Please apply the
below diff to your patch before fixing the typo.

Thanks,
Alex


diff --git a/man4/smartpqi.4 b/man4/smartpqi.4
index c0b305935..4aefbfde0 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -383,7 +383,7 @@ .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 .EE
 .in
 .TP
-.IR /sys/class/scsi_disk/c : b : t : l/device/lunid
+.IR /sys/class/scsi_disk/ c : b : t : l /device/lunid
 The
 .I lunid
 attribute is read-only.
@@ -399,12 +399,12 @@ .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 .EE
 .in
 .TP
-.IR /sys/class/scsi_disk/c : b : t : l/device/unique_id
+.IR /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.
+This attribute contains a 16-byte ID
+that uniquely identifies the device within the controller.
 .IP
 For example:
 .IP
@@ -416,12 +416,15 @@ .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 .EE
 .in
 .TP
-.IR /sys/class/scsi_disk/c : b : t : l/device/path_info
+.IR /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.
+This attribute contains the
+.IR 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.
@@ -445,8 +448,9 @@ .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 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.
+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.
@@ -466,8 +470,8 @@ .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP
 .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.
+This attribute works only when device has NCQ support
+and controller firmware can handle IO with NCQ priority attribute.
 .IP
 For example:
 .IP


-- 
<https://www.alejandro-colomar.es/>

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