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

[lihuisong (C)]

在 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?
>
> 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.
>
>
> 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.
>
>
>>   * **[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?


>
>
> .