[PATCH net v2 0/4] Documentation fixes for Mellanox mlx5 devlink info

[PATCH net v2 0/4] Documentation fixes for Mellanox mlx5 devlink info

[Bagas Sanjaya]

Here are fixes for mlx5 devlink info documentation. The first fixes
htmldocs warnings on the mainline, while the rest is formatting fixes.

Changes since v1 [1]:

  * Pick up Reviewed-by tags from Leon Romanovsky
  * Rebase on current net tree

[1]: https://lore.kernel.org/linux-doc/20230503094248.28931-1-bagasdotme@gmail.com/

Bagas Sanjaya (4):
  Documentation: net/mlx5: Wrap vnic reporter devlink commands in code
    blocks
  Documentation: net/mlx5: Use bullet and definition lists for vnic
    counters description
  Documentation: net/mlx5: Add blank line separator before numbered
    lists
  Documentation: net/mlx5: Wrap notes in admonition blocks

 .../ethernet/mellanox/mlx5/devlink.rst        | 60 ++++++++++++-------
 1 file changed, 37 insertions(+), 23 deletions(-)


base-commit: 582dbb2cc1a0a7427840f5b1e3c65608e511b061
-- 
An old man doll... just what I always wanted! - Clara

[PATCH net v2 1/4] Documentation: net/mlx5: Wrap vnic reporter devlink commands in code blocks

[Bagas Sanjaya]

Sphinx reports htmldocs warnings:

Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:287: WARNING: Unexpected indentation.
Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:288: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:290: WARNING: Unexpected indentation.

Fix above warnings by wrapping diagnostic devlink commands in "vnic
reporter" section in code blocks to be consistent with other devlink
command snippets.

Fixes: b0bc615df488ab ("net/mlx5: Add vnic devlink health reporter to PFs/VFs")
Fixes: cf14af140a5ad0 ("net/mlx5e: Add vnic devlink health reporter to representors")
Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../device_drivers/ethernet/mellanox/mlx5/devlink.rst     | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
index 3a7a714cc08f0a..0f0598caea145f 100644
--- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
+++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
@@ -283,10 +283,14 @@ nic_receive_steering_discard: number of packets that completed RX flow
 steering but were discarded due to a mismatch in flow table.
 
 User commands examples:
-- Diagnose PF/VF vnic counters
+
+- Diagnose PF/VF vnic counters::
+
         $ devlink health diagnose pci/0000:82:00.1 reporter vnic
+
 - Diagnose representor vnic counters (performed by supplying devlink port of the
-  representor, which can be obtained via devlink port command)
+  representor, which can be obtained via devlink port command)::
+
         $ devlink health diagnose pci/0000:82:00.1/65537 reporter vnic
 
 NOTE: This command can run over all interfaces such as PF/VF and representor ports.
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net v2 1/4] Documentation: net/mlx5: Wrap vnic reporter devlink commands in code blocks

[Simon Horman]

On Wed, May 10, 2023 at 10:54:12AM +0700, Bagas Sanjaya wrote:
> Sphinx reports htmldocs warnings:
> 
> Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:287: WARNING: Unexpected indentation.
> Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:288: WARNING: Block quote ends without a blank line; unexpected unindent.
> Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst:290: WARNING: Unexpected indentation.
> 
> Fix above warnings by wrapping diagnostic devlink commands in "vnic
> reporter" section in code blocks to be consistent with other devlink
> command snippets.
> 
> Fixes: b0bc615df488ab ("net/mlx5: Add vnic devlink health reporter to PFs/VFs")
> Fixes: cf14af140a5ad0 ("net/mlx5e: Add vnic devlink health reporter to representors")
> Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

[PATCH net v2 2/4] Documentation: net/mlx5: Use bullet and definition lists for vnic counters description

[Bagas Sanjaya]

"vnic reporter" section contains unformatted description for vnic
counters, which is rendered as one long paragraph instead of list.

Use bullet and definition lists to match other lists.

Fixes: b0bc615df488ab ("net/mlx5: Add vnic devlink health reporter to PFs/VFs")
Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../ethernet/mellanox/mlx5/devlink.rst        | 36 ++++++++++---------
 1 file changed, 20 insertions(+), 16 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
index 0f0598caea145f..00687425d8b72d 100644
--- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
+++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
@@ -265,22 +265,26 @@ It is responsible for querying the vnic diagnostic counters from fw and displayi
 them in realtime.
 
 Description of the vnic counters:
-total_q_under_processor_handle: number of queues in an error state due to
-an async error or errored command.
-send_queue_priority_update_flow: number of QP/SQ priority/SL update
-events.
-cq_overrun: number of times CQ entered an error state due to an
-overflow.
-async_eq_overrun: number of times an EQ mapped to async events was
-overrun.
-comp_eq_overrun: number of times an EQ mapped to completion events was
-overrun.
-quota_exceeded_command: number of commands issued and failed due to quota
-exceeded.
-invalid_command: number of commands issued and failed dues to any reason
-other than quota exceeded.
-nic_receive_steering_discard: number of packets that completed RX flow
-steering but were discarded due to a mismatch in flow table.
+
+- total_q_under_processor_handle
+        number of queues in an error state due to
+        an async error or errored command.
+- send_queue_priority_update_flow
+        number of QP/SQ priority/SL update events.
+- cq_overrun
+        number of times CQ entered an error state due to an overflow.
+- async_eq_overrun
+        number of times an EQ mapped to async events was overrun.
+        comp_eq_overrun number of times an EQ mapped to completion events was
+        overrun.
+- quota_exceeded_command
+        number of commands issued and failed due to quota exceeded.
+- invalid_command
+        number of commands issued and failed dues to any reason other than quota
+        exceeded.
+- nic_receive_steering_discard
+        number of packets that completed RX flow
+        steering but were discarded due to a mismatch in flow table.
 
 User commands examples:
 
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net v2 2/4] Documentation: net/mlx5: Use bullet and definition lists for vnic counters description

[Simon Horman]

On Wed, May 10, 2023 at 10:54:13AM +0700, Bagas Sanjaya wrote:
> "vnic reporter" section contains unformatted description for vnic
> counters, which is rendered as one long paragraph instead of list.
> 
> Use bullet and definition lists to match other lists.
> 
> Fixes: b0bc615df488ab ("net/mlx5: Add vnic devlink health reporter to PFs/VFs")
> Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

Re: [PATCH net v2 2/4] Documentation: net/mlx5: Use bullet and definition lists for vnic counters description

[Daniel.Machon]

>  Description of the vnic counters:
> -total_q_under_processor_handle: number of queues in an error state due to
> -an async error or errored command.
> -send_queue_priority_update_flow: number of QP/SQ priority/SL update
> -events.
> -cq_overrun: number of times CQ entered an error state due to an
> -overflow.
> -async_eq_overrun: number of times an EQ mapped to async events was
> -overrun.
> -comp_eq_overrun: number of times an EQ mapped to completion events was
> -overrun.
> -quota_exceeded_command: number of commands issued and failed due to quota
> -exceeded.
> -invalid_command: number of commands issued and failed dues to any reason
> -other than quota exceeded.
> -nic_receive_steering_discard: number of packets that completed RX flow
> -steering but were discarded due to a mismatch in flow table.
> +
> +- total_q_under_processor_handle
> +        number of queues in an error state due to
> +        an async error or errored command.
> +- send_queue_priority_update_flow
> +        number of QP/SQ priority/SL update events.
> +- cq_overrun
> +        number of times CQ entered an error state due to an overflow.
> +- async_eq_overrun
> +        number of times an EQ mapped to async events was overrun.
> +        comp_eq_overrun number of times an EQ mapped to completion events was
> +        overrun.
> +- quota_exceeded_command
> +        number of commands issued and failed due to quota exceeded.
> +- invalid_command
> +        number of commands issued and failed dues to any reason other than quota
> +        exceeded.

Hi Bagas,

nit: I think 'dues' should be 'due' here. Might as well get that in
when touching the code anyway.

Other than that:

Reviewed-by: Daniel Machon <daniel.machon@microchip.com>

> +- nic_receive_steering_discard
> +        number of packets that completed RX flow
> +        steering but were discarded due to a mismatch in flow table.
 

[PATCH net v2 3/4] Documentation: net/mlx5: Add blank line separator before numbered lists

[Bagas Sanjaya]

The doc forgets to add separator before numbered lists, which causes the
lists to be appended to previous paragraph inline instead.

Add the missing separator.

Fixes: f2d51e579359b7 ("net/mlx5: Separate mlx5 driver documentation into multiple pages")
Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../device_drivers/ethernet/mellanox/mlx5/devlink.rst           | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
index 00687425d8b72d..f962c0975d8428 100644
--- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
+++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
@@ -40,6 +40,7 @@ flow_steering_mode: Device flow steering mode
 ---------------------------------------------
 The flow steering mode parameter controls the flow steering mode of the driver.
 Two modes are supported:
+
 1. 'dmfs' - Device managed flow steering.
 2. 'smfs' - Software/Driver managed flow steering.
 
@@ -99,6 +100,7 @@ between representors and stacked devices.
 By default metadata is enabled on the supported devices in E-switch.
 Metadata is applicable only for E-switch in switchdev mode and
 users may disable it when NONE of the below use cases will be in use:
+
 1. HCA is in Dual/multi-port RoCE mode.
 2. VF/SF representor bonding (Usually used for Live migration)
 3. Stacked devices
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net v2 3/4] Documentation: net/mlx5: Add blank line separator before numbered lists

[Simon Horman]

On Wed, May 10, 2023 at 10:54:14AM +0700, Bagas Sanjaya wrote:
> The doc forgets to add separator before numbered lists, which causes the
> lists to be appended to previous paragraph inline instead.
> 
> Add the missing separator.
> 
> Fixes: f2d51e579359b7 ("net/mlx5: Separate mlx5 driver documentation into multiple pages")
> Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

[PATCH net v2 4/4] Documentation: net/mlx5: Wrap notes in admonition blocks

[Bagas Sanjaya]

Wrap note paragraphs in note:: directive as it better fit for the
purpose of noting devlink commands.

Fixes: f2d51e579359b7 ("net/mlx5: Separate mlx5 driver documentation into multiple pages")
Fixes: cf14af140a5ad0 ("net/mlx5e: Add vnic devlink health reporter to representors")
Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../ethernet/mellanox/mlx5/devlink.rst             | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
index f962c0975d8428..3354ca3608ee67 100644
--- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
+++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/devlink.rst
@@ -182,7 +182,8 @@ User commands examples:
 
     $ devlink health diagnose pci/0000:82:00.0 reporter tx
 
-NOTE: This command has valid output only when interface is up, otherwise the command has empty output.
+.. note::
+   This command has valid output only when interface is up, otherwise the command has empty output.
 
 - Show number of tx errors indicated, number of recover flows ended successfully,
   is autorecover enabled and graceful period from last recover::
@@ -234,8 +235,9 @@ User commands examples:
 
     $ devlink health dump show pci/0000:82:00.0 reporter fw
 
-NOTE: This command can run only on the PF which has fw tracer ownership,
-running it on other PF or any VF will return "Operation not permitted".
+.. note::
+   This command can run only on the PF which has fw tracer ownership,
+   running it on other PF or any VF will return "Operation not permitted".
 
 fw fatal reporter
 -----------------
@@ -258,7 +260,8 @@ User commands examples:
 
     $ devlink health dump show pci/0000:82:00.1 reporter fw_fatal
 
-NOTE: This command can run only on PF.
+.. note::
+   This command can run only on PF.
 
 vnic reporter
 -------------
@@ -299,4 +302,5 @@ User commands examples:
 
         $ devlink health diagnose pci/0000:82:00.1/65537 reporter vnic
 
-NOTE: This command can run over all interfaces such as PF/VF and representor ports.
+.. note::
+   This command can run over all interfaces such as PF/VF and representor ports.
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net v2 4/4] Documentation: net/mlx5: Wrap notes in admonition blocks

[Simon Horman]

On Wed, May 10, 2023 at 10:54:15AM +0700, Bagas Sanjaya wrote:
> Wrap note paragraphs in note:: directive as it better fit for the
> purpose of noting devlink commands.
> 
> Fixes: f2d51e579359b7 ("net/mlx5: Separate mlx5 driver documentation into multiple pages")
> Fixes: cf14af140a5ad0 ("net/mlx5e: Add vnic devlink health reporter to representors")
> Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Hi,

I think you may have missed one 'NOTE:' around line 213.
Is that intentional?

Re: [PATCH net v2 4/4] Documentation: net/mlx5: Wrap notes in admonition blocks

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> Wrap note paragraphs in note:: directive as it better fit for the
> purpose of noting devlink commands.
>
> Fixes: f2d51e579359b7 ("net/mlx5: Separate mlx5 driver documentation into multiple pages")
> Fixes: cf14af140a5ad0 ("net/mlx5e: Add vnic devlink health reporter to representors")
> Reviewed-by: Leon Romanovsky <leonro@nvidia.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  .../ethernet/mellanox/mlx5/devlink.rst             | 14 +++++++++-----
>  1 file changed, 9 insertions(+), 5 deletions(-)

So these changes seem harmless, but the Fixes: tags seem completely
inappropriate here.  This is format tweaking, not a bug fix.

Thanks,

jon

Re: [PATCH net v2 0/4] Documentation fixes for Mellanox mlx5 devlink info

[Bagas Sanjaya]

On 5/10/23 10:54, Bagas Sanjaya wrote:
> Here are fixes for mlx5 devlink info documentation. The first fixes
> htmldocs warnings on the mainline, while the rest is formatting fixes.
> 
> Changes since v1 [1]:
> 
>   * Pick up Reviewed-by tags from Leon Romanovsky
>   * Rebase on current net tree
> 
> [1]: https://lore.kernel.org/linux-doc/20230503094248.28931-1-bagasdotme@gmail.com/
> 
> Bagas Sanjaya (4):
>   Documentation: net/mlx5: Wrap vnic reporter devlink commands in code
>     blocks
>   Documentation: net/mlx5: Use bullet and definition lists for vnic
>     counters description
>   Documentation: net/mlx5: Add blank line separator before numbered
>     lists
>   Documentation: net/mlx5: Wrap notes in admonition blocks
> 
>  .../ethernet/mellanox/mlx5/devlink.rst        | 60 ++++++++++++-------
>  1 file changed, 37 insertions(+), 23 deletions(-)
> 

Hi jon,

If there is no response from mellanox and/or netdev maintainers,
would you like to review and pick this series up?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH net v2 0/4] Documentation fixes for Mellanox mlx5 devlink info

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 5/10/23 10:54, Bagas Sanjaya wrote:
>> Here are fixes for mlx5 devlink info documentation. The first fixes
>> htmldocs warnings on the mainline, while the rest is formatting fixes.
>> 
>> Changes since v1 [1]:
>> 
>>   * Pick up Reviewed-by tags from Leon Romanovsky
>>   * Rebase on current net tree
>> 
>> [1]: https://lore.kernel.org/linux-doc/20230503094248.28931-1-bagasdotme@gmail.com/
>> 
>> Bagas Sanjaya (4):
>>   Documentation: net/mlx5: Wrap vnic reporter devlink commands in code
>>     blocks
>>   Documentation: net/mlx5: Use bullet and definition lists for vnic
>>     counters description
>>   Documentation: net/mlx5: Add blank line separator before numbered
>>     lists
>>   Documentation: net/mlx5: Wrap notes in admonition blocks
>> 
>>  .../ethernet/mellanox/mlx5/devlink.rst        | 60 ++++++++++++-------
>>  1 file changed, 37 insertions(+), 23 deletions(-)
>> 
>
> Hi jon,
>
> If there is no response from mellanox and/or netdev maintainers,
> would you like to review and pick this series up?
>
They seem OK other than the gratuitous use of Fixes tags.  The netdev
maintainers are generally responsive and on top of things, though, and I
don't think there would be any justification for bypassing them here.

Thanks,

jon

Re: [PATCH net v2 0/4] Documentation fixes for Mellanox mlx5 devlink info

[Jakub Kicinski]

On Tue, 16 May 2023 12:29:18 -0600 Jonathan Corbet wrote:
> > If there is no response from mellanox and/or netdev maintainers,
> > would you like to review and pick this series up?
> 
> They seem OK other than the gratuitous use of Fixes tags.  The netdev
> maintainers are generally responsive and on top of things, though, and I
> don't think there would be any justification for bypassing them here.

I'm expecting Saeed to pick them up to the mlx5 tree. Either that 
or tell us to take them in. I think he was out and traveling recently.
Let's give him some time :|