Re: [dpdk-dev] [PATCH v4 1/4] ethdev: add tm support for shaper config in pkt mode

["Dumitrescu, Cristian" <cristian.dumitrescu@intel.com>]

> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Tuesday, April 28, 2020 4:30 PM
> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
> Cc: Yigit, Ferruh <ferruh.yigit@intel.com>; Nithin Dabilpuram
> <nithind1988@gmail.com>; Singh, Jasvinder <jasvinder.singh@intel.com>;
> Andrew Rybchenko <arybchenko@solarflare.com>; dev@dpdk.org;
> jerinj@marvell.com; kkanas@marvell.com; Nithin Dabilpuram
> <ndabilpuram@marvell.com>; Kinsella, Ray <ray.kinsella@intel.com>; Neil
> Horman <nhorman@tuxdriver.com>; Luca Boccassi <bluca@debian.org>;
> Kevin Traynor <ktraynor@redhat.com>; David Marchand
> <david.marchand@redhat.com>; Richardson, Bruce
> <bruce.richardson@intel.com>
> Subject: Re: [PATCH v4 1/4] ethdev: add tm support for shaper config in pkt
> mode
> 
> 27/04/2020 18:28, Dumitrescu, Cristian:
> > From: Yigit, Ferruh <ferruh.yigit@intel.com>
> > > On 4/27/2020 10:19 AM, Dumitrescu, Cristian wrote:
> > > > From: Yigit, Ferruh <ferruh.yigit@intel.com>
> > > >> Hi Nithin,
> > > >>
> > > >> It looks like patch is causing ABI break, I am getting following warning
> [1],
> > > >> can you please check?
> > > >>
> > > >> [1]
> > > >> https://pastebin.com/XYNFg14u
> > > >
> > > >
> > > > Hi Ferruh,
> > > >
> > > > The RTE_TM API is marked as experimental, but it looks that this was
> not
> > > correctly marked when __rte_experimental ABI checker was introduced.
> > > >
> > > > It is marked as experimental at the top of the rte_tm.h, similarly to
> other
> > > APIs introduced around same time, but it was not correctly picked up by
> the
> > > ABI check procedure when later introduced, so __rte_experimental was
> not
> > > added to every function.
> > > >
> > >
> > > :(
> > >
> > > Is it time to mature them?
> > >
> > > As you said they are not marked as experimental both in header file
> > > (function
> > > declarations) and .map file.
> > >
> > > The problem is, they are not marked as experimental in DPDK_20.0 ABI
> > > (v19.11),
> > > so marking them as experimental now will break the ABI. Not sure what
> to
> > > do,
> > > cc'ed a few ABI related names for comment.
> > >
> > > For me, we need to proceed as the experimental tag removed and APIs
> > > become
> > > mature starting from v19.11, since this is what happened in practice, and
> > > remove
> > > a few existing being experimental references in the doxygen comments.
> > >
> > > Ray, Neil, David, Luca, Kevin, what do you think?
> >
> > Hi Ferruh,
> >
> > IMO your proposed approach is fixing the wrong problem and is
> > probably not the right way of doing things.
> >
> > This API is correctly marked as experimental in the header
> > file rte_tm.h and in the MAINTAINERS file,
> 
> in rte_tm.h:
> 	* @warning
> 	* @b EXPERIMENTAL: this API may change without prior notice
> 
> in MAINTAINERS:
> 	Traffic Management API - EXPERIMENTAL
> 	M: Cristian Dumitrescu <cristian.dumitrescu@intel.com>
> 	T: git://dpdk.org/next/dpdk-next-qos
> 	F: lib/librte_ethdev/rte_tm*
> 
> 
> > therefore it should remain experimental,
> 
> in rte_ethdev_version.map:
> 	before 19.11: DPDK_17.08 {
> 	since 19.11: DPDK_20.0 {
> 
> When adding rte_tm in 17.08:
> http://git.dpdk.org/dpdk/diff/lib/librte_ether/rte_ether_version.map?id=5
> d109deffa
> 
> In 17.08, early July 2017, the first EXPERIMENTAL section was declared in EAL:
> http://git.dpdk.org/dpdk/diff/lib/librte_eal/linuxapp/eal/rte_eal_version.m
> ap?id=a3ee360f444
> 
> When adding rte_mtr in 17.11, all functions are made experimental:
> http://git.dpdk.org/dpdk/diff/lib/librte_ether/rte_ethdev_version.map?id=
> 6613ffe1
> 
> In 18.02, the tag __rte_experimental was introduced:
> 	http://git.dpdk.org/dpdk/commit/?id=7d540a3e735
> and functions are marked (including rte_mtr but not rte_tm):
> 	http://git.dpdk.org/dpdk/commit/?id=77b7b81e32e
> 
> 

Thanks, Thomas, for taking the time to put all the historic events in their proper sequence.

> > as more changes are expected from the people like Nithin and others
> > currently upstreaming drivers for it.
> 
> They are doing changes in the API introduced 3 years ago.
> 
> 
> > For some reason, the __rte_experimental tags were not added to
> > this file when the ABI checker was introduced,
> > and this is the real problem that should be fixed.
> 
> The mistake was done 2 years ago.
> As maintainer of rte_tm code, you are expected to notice the issue.

Apologies for not noticing this gap at the time. As Thomas shows above, the __rte_experimental tags were introduced several DPDK releases after the rte_tm API.

> As maintainer of rte_mtr code, you were expected to review the change
> on the mtr functions being marked as experimental.

I did.

> I am sorry that it took 2 years to discover the gap.
> 
> We can fix the ABI in the ABI-breakage window: in 20.11.
>