[PATCH v10 0/1] smartpqi man page updates

[PATCH v10 0/1] 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 V9:

    Only 1 patch remaining.

    smartpqi-remove-sysfs-entry-for-version
      Added the kernel patch that changed the sysfs entry for "version"
      into two entries "driver_version" and "firmware_version" and the
      date this patch went into Linus's tree.

      Alejandro Colomar <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZThOy783p2lCDQcF@debian/

      Thanks Alejandro for your work in getting these patches applied.

Changes since V8:
    smartpqi-update-host-attribute-descriptions
      I added an explanation for changing "logical drives" to "logical volumes".
      Alejandro Colomar <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZS3IKF9XHOuQaMMt@debian/

    smartpqi-add-device-attributes
      Changed the sysfs entry from a specific Host:Bus:Target:Lun to generic
      c : b : t : l
      Shortened some lines.
      Alejandro Colomar <alx@kernel.org>
      Link: https://lore.kernel.org/linux-man/ZS3MwU7MNF3p7yes@debian/

Changes since V7:

    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 (1):
  smartpqi: remove sysfs entry for version

 man4/smartpqi.4 | 25 +++++++------------------
 1 file changed, 7 insertions(+), 18 deletions(-)

-- 
2.42.0.482.g2e8e77cbac

[PATCH v10 1/1] 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 by
patch "(6d90615f1346 scsi: smartpqi: add sysfs entries)" in Linus's
tree Aug 22 2019.

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 5f333356aae3..9718cb4b22e8 100644
--- a/man4/smartpqi.4
+++ b/man4/smartpqi.4
@@ -149,24 +149,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
@@ -397,6 +379,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.482.g2e8e77cbac

Re: [PATCH v10 0/1] smartpqi man page updates

[Alejandro Colomar]

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

Hi Don,

On Wed, Oct 25, 2023 at 09:22:34AM -0500, Don Brace wrote:
> 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 V9:
> 
>     Only 1 patch remaining.
> 
>     smartpqi-remove-sysfs-entry-for-version
>       Added the kernel patch that changed the sysfs entry for "version"
>       into two entries "driver_version" and "firmware_version" and the
>       date this patch went into Linus's tree.
> 
>       Alejandro Colomar <alx@kernel.org>
>       Link: https://lore.kernel.org/linux-man/ZThOy783p2lCDQcF@debian/
> 
>       Thanks Alejandro for your work in getting these patches applied.

Thank you for your patience!  :)

Patch set fully applied.  You can find it here:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=cae9da3fbbac173fb094acf4cfc027739d1caf9a>

Cheers,
Alex

> 
> Changes since V8:
>     smartpqi-update-host-attribute-descriptions
>       I added an explanation for changing "logical drives" to "logical volumes".
>       Alejandro Colomar <alx@kernel.org>
>       Link: https://lore.kernel.org/linux-man/ZS3IKF9XHOuQaMMt@debian/
> 
>     smartpqi-add-device-attributes
>       Changed the sysfs entry from a specific Host:Bus:Target:Lun to generic
>       c : b : t : l
>       Shortened some lines.
>       Alejandro Colomar <alx@kernel.org>
>       Link: https://lore.kernel.org/linux-man/ZS3MwU7MNF3p7yes@debian/
> 
> Changes since V7:
> 
>     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 (1):
>   smartpqi: remove sysfs entry for version
> 
>  man4/smartpqi.4 | 25 +++++++------------------
>  1 file changed, 7 insertions(+), 18 deletions(-)
> 
> -- 
> 2.42.0.482.g2e8e77cbac
> 

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

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