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

[Nithin Dabilpuram]

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 at 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. 

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