[PATCH v3 1/6] doc: add RSS hash algorithm feature

[lihuisong (C)]

在 2023/11/28 19:52, Ferruh Yigit 写道:
> On 11/28/2023 11:29 AM, lihuisong (C) wrote:
>> 在 2023/11/28 18:09, Ferruh Yigit 写道:
>>> On 11/28/2023 1:21 AM, lihuisong (C) wrote:
>>>> 在 2023/11/27 23:43, Ferruh Yigit 写道:
>>>>> On 11/27/2023 1:12 PM, lihuisong (C) wrote:
>>>>>> 在 2023/11/27 20:19, Ferruh Yigit 写道:
>>>>>>> On 11/25/2023 1:47 AM, Huisong Li wrote:
>>>>>>>> Add hash algorithm feature introduced by 23.11 and fix some RSS
>>>>>>>> features
>>>>>>>> description.
>>>>>>>>
>>>>>>>> Fixes: 34ff088cc241 ("ethdev: set and query RSS hash algorithm")
>>>>>>>>
>>>>>>>> Signed-off-by: Huisong Li <lihuisong at huawei.com>
>>>>>>>> Acked-by: Chengwen Feng <fengchengwen at huawei.com>
>>>>>>>> ---
>>>>>>>>      doc/guides/nics/features.rst | 26 ++++++++++++++++++++++----
>>>>>>>>      1 file changed, 22 insertions(+), 4 deletions(-)
>>>>>>>>
>>>>>>>> diff --git a/doc/guides/nics/features.rst
>>>>>>>> b/doc/guides/nics/features.rst
>>>>>>>> index 1a1dc16c1e..0d38c5c525 100644
>>>>>>>> --- a/doc/guides/nics/features.rst
>>>>>>>> +++ b/doc/guides/nics/features.rst
>>>>>>>> @@ -277,10 +277,12 @@ RSS hash
>>>>>>>>      Supports RSS hashing on RX.
>>>>>>>>        * **[uses]     user config**: ``dev_conf.rxmode.mq_mode`` =
>>>>>>>> ``RTE_ETH_MQ_RX_RSS_FLAG``.
>>>>>>>> -* **[uses]     user config**: ``dev_conf.rx_adv_conf.rss_conf``.
>>>>>>>> +* **[uses]     user config**: ``rss_conf.rss_hf``.
>>>>>>>>
>>>>>>> Feature title is "RSS hash", it can be two things,
>>>>>>> 1. "Receive Side Scaling" support
>>>>>>> 2. Provide RSS hash to application
>>>>>>>
>>>>>>> When this document first prepared RSS hash value was always
>>>>>>> provided to
>>>>>>> the application when RSS enabled.
>>>>>>> So intention with this feature was "Receive Side Scaling" support,
>>>>>>> hence
>>>>>>> 'RTE_ETH_MQ_RX_RSS_FLAG' added.
>>>>>>>
>>>>>>> Later providing RSS has to the application separated as optimization,
>>>>>>> 'RTE_ETH_RX_OFFLOAD_RSS_HASH' & 'RTE_MBUF_F_RX_RSS_HASH' added for
>>>>>>> this
>>>>>>> support.
>>>>>> What should I do for above two comments？
>>>>>> To tell application how to use it?
>>>>>>
>>>>> Just tried to give some context.
>>>> got it.
>>>>>   
>>>>>>> As the intention of this feature is "Receive Side Scaling"
>>>>>>> support, we
>>>>>>> shouldn't reduce configuration struct to 'rss_conf.rss_hf'.
>>>>>>>
>>>>>>> Instead perhaps can expand to:
>>>>>>> 'rte_eth_conf.rx_adv_conf.rss_conf', 'rte_eth_rss_conf'
>>>>>>     I just pick their common part.😁
>>>>>>
>>>>>> ok, will fix it.
>>>>>>
>>>>>>>>      * **[uses]     rte_eth_rxconf,rte_eth_rxmode**:
>>>>>>>> ``offloads:RTE_ETH_RX_OFFLOAD_RSS_HASH``.
>>>>>>>>      * **[provides] rte_eth_dev_info**: ``flow_type_rss_offloads``.
>>>>>>>>      * **[provides] mbuf**: ``mbuf.ol_flags:RTE_MBUF_F_RX_RSS_HASH``,
>>>>>>>> ``mbuf.rss``.
>>>>>>>> +* **[related]  API**: ``rte_eth_dev_configure``,
>>>>>>>> ``rte_eth_dev_rss_hash_update``
>>>>>>>> +  ``rte_eth_dev_rss_hash_conf_get()``.
>>>>>>>>      
>>>>>>> ack
>>>>>>>
>>>>>>>>        .. _nic_features_inner_rss:
>>>>>>>> @@ -288,7 +290,7 @@ Supports RSS hashing on RX.
>>>>>>>>      Inner RSS
>>>>>>>>      ---------
>>>>>>>>      -Supports RX RSS hashing on Inner headers.
>>>>>>>> +Supports RX RSS hashing on Inner headers by rte_flow API.
>>>>>>>>      
>>>>>>> This should be clarified with details below, not sure if it
>>>>>>> required to
>>>>>>> limit description to rte_flow.
>>>>>> But this block like rte_flow_action_rss is from rte_flow.
>>>>>> And ethdev ops doesn't support inner RSS.
>>>>>> So I think it is ok.
>>>>>>
>>>>> Yes it is supported by rte_flow, and '[uses]' information should
>>>>> already
>>>>> clarify it.
>>>> Should we remove the 'rte_flow API' wrods I added in above description?
>>>>
>>> I think it can be removed.
>> The latest version(V5, only three fix doc patch) has been sent out.
>> Do we I need to send V6 for this?😂
>>
> Nope, no new version needed for this, I already acked the one with it,
> but if there will be a new version this can be updated.
ok
> Thanks Huisong for improving the documentation.

Willing to contribute my strength to the community.😁

>
>>>
>>>>>>> And I guess similar confusion exist with the providing hash to user.
>>>>>>> Need to check if rte_flow implementation puts hash to mbuf along with
>>>>>>> doing the RSS, or if it checks 'RTE_ETH_RX_OFFLOAD_RSS_HASH' offload,
>>>>>>> and update below items accordingly.
>>>>>> Do we need to tell user how to use it here?
>>>>>> I feel this document is a little simple and main to list interface for
>>>>>> user.
>>>>>> In addition, it is better that the more detail about RSS should be
>>>>>> presented  in rte_flow features.
>>>>>>
>>>>> No, I am not suggesting to add more detail.
>>>>>
>>>>> My concern is 'RTE_ETH_RX_OFFLOAD_RSS_HASH' information may not be
>>>>> correct, ethdev APIs checks offload flags, but does rte_flow
>>>>> implementation check it?
>>>> As far as I know, It is possibly verified in PMD if have or required.
>>>>> My suggestion is double check that piece of information and fix it if
>>>>> required.
>>>>>
>>>>>
>>>>>>>>      * **[uses]    rte_flow_action_rss**: ``level``.
>>>>>>>>      * **[uses]    rte_eth_rxconf,rte_eth_rxmode**:
>>>>>>>> ``offloads:RTE_ETH_RX_OFFLOAD_RSS_HASH``.
>>>>>>>> @@ -303,9 +305,25 @@ RSS key update
>>>>>>>>      Supports configuration of Receive Side Scaling (RSS) hash
>>>>>>>> computation. Updating
>>>>>>>>      Receive Side Scaling (RSS) hash key.
>>>>>>>>      -* **[implements] eth_dev_ops**: ``rss_hash_update``,
>>>>>>>> ``rss_hash_conf_get``.
>>>>>>>> +* **[implements] eth_dev_ops**: ``dev_configure``,
>>>>>>>> ``rss_hash_update``, ``rss_hash_conf_get``.
>>>>>>>> +* **[uses]     user config**: ``rss_conf.rss_key``,
>>>>>>>> ``rss_conf.rss_key_len``
>>>>>>>>      * **[provides]   rte_eth_dev_info**: ``hash_key_size``.
>>>>>>>> -* **[related]    API**: ``rte_eth_dev_rss_hash_update()``,
>>>>>>>> +* **[related]    API**: ``rte_eth_dev_configure``,
>>>>>>>> ``rte_eth_dev_rss_hash_update()``,
>>>>>>>> +  ``rte_eth_dev_rss_hash_conf_get()``.
>>>>>>>> +
>>>>>>> ack
>>>>>>>
>>>>>>> There is an inconsistency in the documentation but I think it is
>>>>>>> good to
>>>>>>> use '()' when documenting API, like: 'rte_eth_dev_configure()'
>>>>>> +1 will fix it.
>>>>>>>> +
>>>>>>>> +.. _nic_features_rss_hash_algo_update:
>>>>>>>> +
>>>>>>>> +RSS hash algorithm update
>>>>>>>> +-------------------------
>>>>>>>> +
>>>>>>>> +Supports configuration of Receive Side Scaling (RSS) hash
>>>>>>>> algorithm.
>>>>>>>> Updating
>>>>>>>> +RSS hash algorithm.
>>>>>>>> +
>>>>>>>> +* **[implements] eth_dev_ops**: ``dev_configure``,
>>>>>>>> ``rss_hash_update``, ``rss_hash_conf_get``.
>>>>>>>> +* **[uses]     user config**: ``rss_conf.algorithm``
>>>>>>>> +* **[provides]   rte_eth_dev_info**: ``rss_algo_capa``.
>>>>>>>> +* **[related]    API**: ``rte_eth_dev_configure``,
>>>>>>>> ``rte_eth_dev_rss_hash_update()``,
>>>>>>>>        ``rte_eth_dev_rss_hash_conf_get()``.
>>>>>>>>        
>>>>>>> This document describes features listed in the 'default.ini', so we
>>>>>>> shouldn't have above.
>>>>>>>
>>>>>>> And I don't think RSS hash algorithm update is a big enough
>>>>>>> feature to
>>>>>>> list in the feature list, perhaps it can be embedded in the RSS
>>>>>>> support
>>>>>>> block, what do you think?
>>>>>> Yes it is not a bit feature.
>>>>>> so put it to RSS hash, right?
>>>>>>
>>>>> Yes please.
>>>>>
>>>>> .
>>> .
> .