[dpdk-stable] [PATCH] doc: add Linux rawio capability requirement in mlx5 guide

[dpdk-stable] [PATCH] doc: add Linux rawio capability requirement in mlx5 guide

[Eli Britstein]

For an application to be able to create "transfer" rte_flows for mlx5
devices, it should have cap_sys_rawio capability.
Document it.

Fixes: f772cc424c45 ("doc: add required Linux capabilities in mlx5 guide")
Cc: stable@dpdk.org

Signed-off-by: Eli Britstein <elibr@nvidia.com>
Reviewed-by: Gaetan Rivet <gaetanr@nvidia.com>
---
 doc/guides/nics/mlx5.rst | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
index 7c50497fbc..7ef682a8fb 100644
--- a/doc/guides/nics/mlx5.rst
+++ b/doc/guides/nics/mlx5.rst
@@ -458,16 +458,14 @@ Run as non-root
 ^^^^^^^^^^^^^^^
 
 In order to run as a non-root user,
-some capabilities must be granted to the application::
+some capabilities must be granted to the application, while others are
+optional for some use cases. Capabilities can be set for example using
+the setcap utilitiy::
 
-   setcap cap_sys_admin,cap_net_admin,cap_net_raw,cap_ipc_lock+ep <dpdk-app>
+   setcap cap_net_admin,cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_sys_rawio+ep <dpdk-app>
 
 Below are the reasons of the need for each capability:
 
-``cap_sys_admin``
-   When using physical addresses (PA mode), with Linux >= 4.0,
-   for access to ``/proc/self/pagemap``.
-
 ``cap_net_admin``
    For device configuration.
 
@@ -477,6 +475,14 @@ Below are the reasons of the need for each capability:
 ``cap_ipc_lock``
    For DMA memory pinning.
 
+``cap_sys_admin`` optional
+   When using physical addresses (PA mode), with Linux >= 4.0,
+   for access to ``/proc/self/pagemap``.
+
+``cap_sys_rawio`` optional
+   For the application to be able to apply rte_flow flows in transfer
+   mode.
+
 Driver options
 ^^^^^^^^^^^^^^
 
-- 
2.28.0.2311.g225365fb51

Re: [dpdk-stable] [dpdk-dev] [PATCH] doc: add Linux rawio capability requirement in mlx5 guide

[Thomas Monjalon]

+Cc mlx5 maintainers

About the title: "rawio" is not a word.
"raw IO" would be better.

01/04/2021 09:49, Eli Britstein:
> For an application to be able to create "transfer" rte_flows for mlx5

What is "tranfer" rule?

rte_flows does not exist. You probably mean rte_flow rule.

> devices, it should have cap_sys_rawio capability.
> Document it.
> 
> Fixes: f772cc424c45 ("doc: add required Linux capabilities in mlx5 guide")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Eli Britstein <elibr@nvidia.com>
> Reviewed-by: Gaetan Rivet <gaetanr@nvidia.com>
[...]
>  In order to run as a non-root user,
> -some capabilities must be granted to the application::
> +some capabilities must be granted to the application, while others are

If you wish to show that all are not a must,
better to replace "must be granted" by "may be required".

> +optional for some use cases. Capabilities can be set for example using

Please start new sentence on next line.

> +the setcap utilitiy::

typo: utility

>  
> -   setcap cap_sys_admin,cap_net_admin,cap_net_raw,cap_ipc_lock+ep <dpdk-app>
> +   setcap cap_net_admin,cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_sys_rawio+ep <dpdk-app>
>  
>  Below are the reasons of the need for each capability:
>  
> -``cap_sys_admin``
> -   When using physical addresses (PA mode), with Linux >= 4.0,
> -   for access to ``/proc/self/pagemap``.
> -
>  ``cap_net_admin``
>     For device configuration.
>  
> @@ -477,6 +475,14 @@ Below are the reasons of the need for each capability:
>  ``cap_ipc_lock``
>     For DMA memory pinning.
>  
> +``cap_sys_admin`` optional
> +   When using physical addresses (PA mode), with Linux >= 4.0,
> +   for access to ``/proc/self/pagemap``.
> +
> +``cap_sys_rawio`` optional
> +   For the application to be able to apply rte_flow flows in transfer
> +   mode.

"For the application" looks useless.
We don't apply "rte_flow flows" but "flow rules".
What is "transfer mode"? It is not mentioned elsewhere in this doc.
How this capability is related to dv_esw_en?
Do we need it in case of trusted VF?

Re: [dpdk-stable] [dpdk-dev] [PATCH] doc: add Linux rawio capability requirement in mlx5 guide

[Eli Britstein]

On 4/1/2021 2:39 PM, Thomas Monjalon wrote:
> External email: Use caution opening links or attachments
>
>
> +Cc mlx5 maintainers
>
> About the title: "rawio" is not a word.
> "raw IO" would be better.

It was meant for cap_sys_rawio. As underscores are not allowed in the 
title, I used "rawio".

I think "raw IO" misses that meaning. What do you think?

>
> 01/04/2021 09:49, Eli Britstein:
>> For an application to be able to create "transfer" rte_flows for mlx5
> What is "tranfer" rule?

https://doc.dpdk.org/guides/prog_guide/rte_flow.html#attribute-transfer

How would you suggest to call it?

>
> rte_flows does not exist. You probably mean rte_flow rule.
OK
>
>> devices, it should have cap_sys_rawio capability.
>> Document it.
>>
>> Fixes: f772cc424c45 ("doc: add required Linux capabilities in mlx5 guide")
>> Cc: stable@dpdk.org
>>
>> Signed-off-by: Eli Britstein <elibr@nvidia.com>
>> Reviewed-by: Gaetan Rivet <gaetanr@nvidia.com>
> [...]
>>   In order to run as a non-root user,
>> -some capabilities must be granted to the application::
>> +some capabilities must be granted to the application, while others are
> If you wish to show that all are not a must,
> better to replace "must be granted" by "may be required".
OK
>
>> +optional for some use cases. Capabilities can be set for example using
> Please start new sentence on next line.
OK
>
>> +the setcap utilitiy::
> typo: utility
OK
>
>> -   setcap cap_sys_admin,cap_net_admin,cap_net_raw,cap_ipc_lock+ep <dpdk-app>
>> +   setcap cap_net_admin,cap_net_raw,cap_ipc_lock,cap_sys_admin,cap_sys_rawio+ep <dpdk-app>
>>
>>   Below are the reasons of the need for each capability:
>>
>> -``cap_sys_admin``
>> -   When using physical addresses (PA mode), with Linux >= 4.0,
>> -   for access to ``/proc/self/pagemap``.
>> -
>>   ``cap_net_admin``
>>      For device configuration.
>>
>> @@ -477,6 +475,14 @@ Below are the reasons of the need for each capability:
>>   ``cap_ipc_lock``
>>      For DMA memory pinning.
>>
>> +``cap_sys_admin`` optional
>> +   When using physical addresses (PA mode), with Linux >= 4.0,
>> +   for access to ``/proc/self/pagemap``.
>> +
>> +``cap_sys_rawio`` optional
>> +   For the application to be able to apply rte_flow flows in transfer
>> +   mode.
> "For the application" looks useless.
> We don't apply "rte_flow flows" but "flow rules".
> What is "transfer mode"? It is not mentioned elsewhere in this doc.
> How this capability is related to dv_esw_en?
I think FDB flows are applicable only if dv_esw_en=1. Do you think need 
to mention it here?
> Do we need it in case of trusted VF?
I think a VF, even if trusted cannot apply FDB flows. Only the ESW manager.
>
>
>

Re: [dpdk-stable] [dpdk-dev] [PATCH] doc: add Linux rawio capability requirement in mlx5 guide

[Thomas Monjalon]

01/04/2021 14:06, Eli Britstein:
> On 4/1/2021 2:39 PM, Thomas Monjalon wrote:
> > About the title: "rawio" is not a word.
> > "raw IO" would be better.
> 
> It was meant for cap_sys_rawio. As underscores are not allowed in the 
> title, I used "rawio".
> 
> I think "raw IO" misses that meaning. What do you think?

I think "raw IO capability" can be understood by everybody.
Otherwise "cap_sys_rawio" may be more explicit for those who know.

> > 01/04/2021 09:49, Eli Britstein:
> >> For an application to be able to create "transfer" rte_flows for mlx5
> > What is "tranfer" rule?
> 
> https://doc.dpdk.org/guides/prog_guide/rte_flow.html#attribute-transfer
> 
> How would you suggest to call it?

"transfer flow rule" is OK.
Or maybe more explicit: "flow rule with transfer attribute".

[...]
> >> +``cap_sys_rawio`` optional
> >> +   For the application to be able to apply rte_flow flows in transfer
> >> +   mode.
> > 
> > "For the application" looks useless.
> > We don't apply "rte_flow flows" but "flow rules".
> > What is "transfer mode"? It is not mentioned elsewhere in this doc.

You could add the link to the transfer attribute here.

> > How this capability is related to dv_esw_en?
> 
> I think FDB flows are applicable only if dv_esw_en=1. Do you think need 
> to mention it here?

Yes

> > Do we need it in case of trusted VF?
> 
> I think a VF, even if trusted cannot apply FDB flows. Only the ESW manager.

Please confirm, and document if it applies only to PF, etc.

When looking at the Linux driver, it seems cap_sys_rawio
is required for all these features:
	MLX5_UCTX_CAP_INTERNAL_DEV_RES
	MLX5_IB_UAPI_DM_TYPE_STEERING_SW_ICM
	MLX5_IB_UAPI_DM_TYPE_HEADER_MODIFY_SW_ICM
	IB_WQ_FLAGS_DELAY_DROP
What does apply to the DPDK driver?