doc: add Linux rawio capability requirement in mlx5 guide
Checks
Commit Message
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(-)
Comments
+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?
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.
>
>
>
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?
@@ -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
^^^^^^^^^^^^^^