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

[lihuisong (C)]

在 2023/11/28 0:35, Ferruh Yigit 写道:
> On 11/27/2023 3:43 PM, Ferruh Yigit wrote:
>> 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.
>>
>>
>>>> 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.
>>
>>
>>>>
>>>> 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?
>>
>> My suggestion is double check that piece of information and fix it if
>> required.
>>
> Thinking twice, ethdev API or rte_flow or different ways to configure
> RSS, but datapath that puts hash value to mbuf is same.
> So same 'RTE_ETH_RX_OFFLOAD_RSS_HASH' check is used for both method, and
> it is OK to have it documented.
There was a check for  RTE_ETH_RX_OFFLOAD_RSS_HASH in 
rte_eth_dev_configure().
This offload flag depends on the RTE_ETH_MQ_RX_RSS_FLAG mode.
As far as I know, ethdev ops allows to enable RSS hash only when 
RTE_ETH_MQ_RX_RSS_FLAG mode is set.
But rte flow API enable RSS hash doesn't depend on this MQ mode.
So I guess that the mbuf.ol_flags:RTE_MBUF_F_RX_RSS_HASH and mbuf.rss 
also be set to report application when create RSS hash flow, even if 
application don't set RTE_ETH_MQ_RX_RSS_FLAG mode by ethdev ops.
>
>
>
>>>>
>>>>>    * **[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.
>>
> .