Re: [dpdk-dev] [EXT] Re: [PATCH v2] ethdev: mark all traffic manager API as experimental

[Nithin Dabilpuram <ndabilpuram@marvell.com>]

On Thu, Sep 10, 2020 at 12:01:49PM +0100, Kinsella, Ray wrote:
> 
> 
> On 10/09/2020 11:56, Nithin Dabilpuram wrote:
> > On Thu, Sep 10, 2020 at 09:30:15AM +0100, Kinsella, Ray wrote:
> >> External Email
> >>
> >> ----------------------------------------------------------------------
> >> On 10/09/2020 09:05, Nithin Dabilpuram wrote:
> >>> This patch marks all traffic manager API as experimental as
> >>> per discussion mentioned in below thread.
> >>>
> >>> https://urldefense.proofpoint.com/v2/url?u=https-3A__mails.dpdk.org_archives_dev_2020-2DApril_165364.html&d=DwIDaQ&c=nKjWec2b6R0mOyPaz7xtfQ&r=FZ_tPCbgFOh18zwRPO9H0yDx8VW38vuapifdDfc8SFQ&m=NlIUXSsugCPTKBv9qxsaMHOhTuC90TUqLcGg962VVyA&s=DZL_m0a73uef5Qgal1iFqc9dTdAuUd8J6eC0mZOQlFs&e= 
> >>>
> >>> Signed-off-by: Nithin Dabilpuram <ndabilpuram@marvell.com>
> >>> ---
> >>>
> >>> v2:
> >>> - Updated commit message.
> >>>
> >>>  lib/librte_ethdev/rte_ethdev_version.map | 62 ++++++++++++++++----------------
> >>>  lib/librte_ethdev/rte_tm.h               | 33 ++++++++++++++++-
> >>>  2 files changed, 64 insertions(+), 31 deletions(-)
> >>>
> >>> diff --git a/lib/librte_ethdev/rte_ethdev_version.map b/lib/librte_ethdev/rte_ethdev_version.map
> >>> index 1212a17..3da4512 100644
> >>> --- a/lib/librte_ethdev/rte_ethdev_version.map
> >>> +++ b/lib/librte_ethdev/rte_ethdev_version.map
> >>> @@ -135,36 +135,6 @@ DPDK_20.0 {
> >>>  	rte_flow_isolate;
> >>>  	rte_flow_query;
> >>>  	rte_flow_validate;
> >>> -	rte_tm_capabilities_get;
> >>> -	rte_tm_get_number_of_leaf_nodes;
> >>> -	rte_tm_hierarchy_commit;
> >>> -	rte_tm_level_capabilities_get;
> >>> -	rte_tm_mark_ip_dscp;
> >>> -	rte_tm_mark_ip_ecn;
> >>> -	rte_tm_mark_vlan_dei;
> >>> -	rte_tm_node_add;
> >>> -	rte_tm_node_capabilities_get;
> >>> -	rte_tm_node_cman_update;
> >>> -	rte_tm_node_delete;
> >>> -	rte_tm_node_parent_update;
> >>> -	rte_tm_node_resume;
> >>> -	rte_tm_node_shaper_update;
> >>> -	rte_tm_node_shared_shaper_update;
> >>> -	rte_tm_node_shared_wred_context_update;
> >>> -	rte_tm_node_stats_read;
> >>> -	rte_tm_node_stats_update;
> >>> -	rte_tm_node_suspend;
> >>> -	rte_tm_node_type_get;
> >>> -	rte_tm_node_wfq_weight_mode_update;
> >>> -	rte_tm_node_wred_context_update;
> >>> -	rte_tm_shaper_profile_add;
> >>> -	rte_tm_shaper_profile_delete;
> >>> -	rte_tm_shared_shaper_add_update;
> >>> -	rte_tm_shared_shaper_delete;
> >>> -	rte_tm_shared_wred_context_add_update;
> >>> -	rte_tm_shared_wred_context_delete;
> >>> -	rte_tm_wred_profile_add;
> >>> -	rte_tm_wred_profile_delete;
> >>>  
> >>>  	local: *;
> >>>  };
> >>> @@ -241,6 +211,38 @@ EXPERIMENTAL {
> >>>  	__rte_ethdev_trace_rx_burst;
> >>>  	__rte_ethdev_trace_tx_burst;
> >>>  	rte_flow_get_aged_flows;
> >>> +
> >>> +	# Marked as experimental in 20.11
> >>> +	rte_tm_capabilities_get;
> >>> +	rte_tm_get_number_of_leaf_nodes;
> >>> +	rte_tm_hierarchy_commit;
> >>> +	rte_tm_level_capabilities_get;
> >>> +	rte_tm_mark_ip_dscp;
> >>> +	rte_tm_mark_ip_ecn;
> >>> +	rte_tm_mark_vlan_dei;
> >>> +	rte_tm_node_add;
> >>> +	rte_tm_node_capabilities_get;
> >>> +	rte_tm_node_cman_update;
> >>> +	rte_tm_node_delete;
> >>> +	rte_tm_node_parent_update;
> >>> +	rte_tm_node_resume;
> >>> +	rte_tm_node_shaper_update;
> >>> +	rte_tm_node_shared_shaper_update;
> >>> +	rte_tm_node_shared_wred_context_update;
> >>> +	rte_tm_node_stats_read;
> >>> +	rte_tm_node_stats_update;
> >>> +	rte_tm_node_suspend;
> >>> +	rte_tm_node_type_get;
> >>> +	rte_tm_node_wfq_weight_mode_update;
> >>> +	rte_tm_node_wred_context_update;
> >>> +	rte_tm_shaper_profile_add;
> >>> +	rte_tm_shaper_profile_delete;
> >>> +	rte_tm_shared_shaper_add_update;
> >>> +	rte_tm_shared_shaper_delete;
> >>> +	rte_tm_shared_wred_context_add_update;
> >>> +	rte_tm_shared_wred_context_delete;
> >>> +	rte_tm_wred_profile_add;
> >>> +	rte_tm_wred_profile_delete;
> >>>  };
> >> [SNIP]
> >>
> >> So I will re-interate what I said in April, all of these API have existed since DPDK 17.08.
> >> I find it hard to believe they are all at imminent risk of changing to degree they _all_ warrant EXPERIMENTAL status.
> > 
> > As discussed earlier and agreed by TM and Ethdev maintainers, __rte_experimental tag was introduced several
> > releases after TM spec was added and TM spec remained untouched ending up making it stable unintentionally. 
> 
> We discussed it I agree, but to identify how this happened.
> I am not sure we all agreed it was ok to give a blanket EXPERIMENTAL. 
> 
> This API has been largely unchanged for 3 years.
> How can we justify keeping EXPERIMENTAL without a specific reason?
> Can you be more specific about planned changes?

Basically the changes atleast which initiated this discussion were

#1 Support to configure shaper in pkt mode that helps ratelimiting in
PPS(Packets per Sec) as opposed to BPS(Bits per Sec).
Needs change to a lot of existing tm param and capability structs.

#2 Support dynamic offload flags based Tx offload for tm packet marking.

#3 Support TM node color stats that report per tm color(red, green, yellow) pkt stats.

All the above three changes though add significant features and doesn't break existing
PMD's. 

> 
> > 
> > Bruce and other maintainers pointed out that we cannot fix it as a "Fixes:" patch in order
> > to honor ABI commitments, and suggestion was to change the complete spec back to
> > experimental in next ABI change window and proceed with improvements that make
> > it stable API in subsequent releases.
> >>
> >> Ray K