doc: add Linux rawio capability requirement in mlx5 guide
PATCH 1/1 doc: add Linux rawio capability requirement in mlx5 guide
For an application to be able to create "transfer" rte_flows for mlx5 devices, it should have cap_sys_rawio capability.
Document it.
--- doc/guides/nics/mlx5.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-)
doc/guides/nics/mlx5.rst +12 -6
@@ -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 ^^^^^^^^^^^^^^
Signature · 1 line
2.28.0.2311.g225365fb51
+Cc mlx5 maintainers
About the title: "rawio" is not a word.
"raw IO" would be better.
01/04/2021 09:49, Eli Britstein:
Quoted 1 line
For an application to be able to create "transfer"
rte_flowsfor mlx5
What is "tranfer" rule?
rte_flows does not exist. You probably mean rte_flow rule.
Quoted 8 lines
devices, it should have
cap_sys_rawiocapability.
Document it.Fixes f772cc424c45 ("doc: add required Linux capabilities in mlx5 guide")Signed-off-by Eli Britstein <[email protected]>Reviewed-by Gaetan Rivet <[email protected]>
[...]
doc/guides/nics/mlx5.rst Run as non-root · line 461
Quoted 3 lines
In order to run as a non-root user,
doc/guides/nics/mlx5.rst +1
-1-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".
Quoted 1 line
+optional for some use cases. Capabilities can be set for example using
Please start new sentence on next line.
Quoted 1 line
+the setcap utilitiy::
typo: utility
Quoted 14 lines
doc/guides/nics/mlx5.rst +1
-5- 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.
doc/guides/nics/mlx5.rst Below are the reasons of the need for each capability: · line 484
Quoted 10 lines
doc/guides/nics/mlx5.rst +7
-0@@ -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?
Quoted 7 lines · Thomas Monjalon
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?
Quoted 4 lines
01/04/2021 09:49, Eli Britstein:
Quoted 1 line
For an application to be able to create "transfer"
rte_flowsfor mlx5What is "tranfer" rule?
https://doc.dpdk.org/guides/prog_guide/rte_flow.html#attribute-transfer
How would you suggest to call it?
Quoted 2 lines
rte_flowsdoes not exist. You probably meanrte_flowrule.
OK
Quoted 7 lines
Quoted 7 lines
devices, it should have
cap_sys_rawiocapability.
Document it.Fixes f772cc424c45 ("doc: add required Linux capabilities in mlx5 guide")
Quoted 8 lines
Quoted 2 lines
Signed-off-by Eli Britstein <[email protected]>Reviewed-by Gaetan Rivet <[email protected]>[...]
doc/guides/nics/mlx5.rst Run as non-root · line 461
Quoted 3 lines
In order to run as a non-root user,
doc/guides/nics/mlx5.rst +1
-1-some capabilities must be granted to the application:: +some capabilities must be granted to the application, while others areIf you wish to show that all are not a must, better to replace "must be granted" by "may be required".
OK
Quoted 3 lines
Quoted 2 lines
+optional for some use cases. Capabilities can be set for example using
Please start new sentence on next line.
OK
Quoted 3 lines
Quoted 2 lines
+the setcap utilitiy::
typo: utility
OK
Quoted 17 lines
Quoted 17 lines
doc/guides/nics/mlx5.rst +1
-5- 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.
Quoted 11 lines
doc/guides/nics/mlx5.rst Below are the reasons of the need for each capability: · line 484
Quoted 7 lines
doc/guides/nics/mlx5.rst +7
-0+``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_flowflows" but "flow rules".
What is "transfer mode"? It is not mentioned elsewhere in this doc. How this capability is related todv_esw_en?
I think FDB flows are applicable only if dv_esw_en=1. Do you think need to mention it here?
Quoted 1 line
Do we need it in case of trusted VF?
I think a VF, even if trusted cannot apply FDB flows. Only the ESW manager.
Quoted 3 lines
01/04/2021 14:06, Eli Britstein:
Quoted 8 lines · Thomas Monjalon
Quoted 2 lines
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.
Quoted 7 lines
Quoted 3 lines
01/04/2021 09:49, Eli Britstein:
Quoted 1 line
For an application to be able to create "transfer"
rte_flowsfor mlx5What 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".
[...]
Quoted 7 lines
Quoted 7 lines
doc/guides/nics/mlx5.rst Below are the reasons of the need for each capability: · line 484
Quoted 3 lines
+``cap_sys_rawio`` optional
doc/guides/nics/mlx5.rst +2
-0+ For the application to be able to apply rte_flow flows in transfer + mode."For the application" looks useless.
We don't apply "rte_flowflows" 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.
Quoted 4 lines
Quoted 1 line
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
Quoted 3 lines
Quoted 1 line
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?