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

[Ferruh Yigit <ferruh.yigit@intel.com>]

On 4/27/2020 5:59 PM, Jerin Jacob wrote:
> On Mon, Apr 27, 2020 at 10:19 PM Ferruh Yigit <ferruh.yigit@intel.com> wrote:
>>
>> On 4/27/2020 5:29 PM, Jerin Jacob wrote:
>>> On Mon, Apr 27, 2020 at 9:42 PM Ferruh Yigit <ferruh.yigit@intel.com> wrote:
>>>>
>>>> On 4/27/2020 10:19 AM, Dumitrescu, Cristian wrote:
>>>>>
>>>>>
>>>>>> -----Original Message-----
>>>>>> From: Yigit, Ferruh <ferruh.yigit@intel.com>
>>>>>> Sent: Saturday, April 25, 2020 9:09 PM
>>>>>> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; Nithin Dabilpuram
>>>>>> <nithind1988@gmail.com>; Singh, Jasvinder <jasvinder.singh@intel.com>;
>>>>>> Thomas Monjalon <thomas@monjalon.net>; Andrew Rybchenko
>>>>>> <arybchenko@solarflare.com>
>>>>>> Cc: dev@dpdk.org; jerinj@marvell.com; kkanas@marvell.com; Nithin
>>>>>> Dabilpuram <ndabilpuram@marvell.com>
>>>>>> Subject: Re: [PATCH v4 1/4] ethdev: add tm support for shaper config in pkt
>>>>>> mode
>>>>>>
>>>>>> On 4/24/2020 11:28 AM, Dumitrescu, Cristian wrote:
>>>>>>>
>>>>>>>
>>>>>>>> -----Original Message-----
>>>>>>>> From: Nithin Dabilpuram <nithind1988@gmail.com>
>>>>>>>> Sent: Wednesday, April 22, 2020 6:21 PM
>>>>>>>> To: Singh, Jasvinder <jasvinder.singh@intel.com>; Dumitrescu, Cristian
>>>>>>>> <cristian.dumitrescu@intel.com>; Thomas Monjalon
>>>>>>>> <thomas@monjalon.net>; Yigit, Ferruh <ferruh.yigit@intel.com>; Andrew
>>>>>>>> Rybchenko <arybchenko@solarflare.com>
>>>>>>>> Cc: dev@dpdk.org; jerinj@marvell.com; kkanas@marvell.com; Nithin
>>>>>>>> Dabilpuram <ndabilpuram@marvell.com>
>>>>>>>> Subject: [PATCH v4 1/4] ethdev: add tm support for shaper config in pkt
>>>>>>>> mode
>>>>>>>>
>>>>>>>> From: Nithin Dabilpuram <ndabilpuram@marvell.com>
>>>>>>>>
>>>>>>>> Some NIC hardware support shaper to work in packet mode i.e
>>>>>>>> shaping or ratelimiting traffic is in packets per second (PPS) as
>>>>>>>> opposed to default bytes per second (BPS). Hence this patch
>>>>>>>> adds support to configure shared or private shaper in packet mode,
>>>>>>>> provide rate in PPS and add related tm capabilities in port/level/node
>>>>>>>> capability structures.
>>>>>>>>
>>>>>>>> This patch also updates tm port/level/node capability structures with
>>>>>>>> exiting features of scheduler wfq packet mode, scheduler wfq byte mode
>>>>>>>> and private/shared shaper byte mode.
>>>>>>>>
>>>>>>>> SoftNIC PMD is also updated with new capabilities.
>>>>>>>>
>>>>>>>> Signed-off-by: Nithin Dabilpuram <ndabilpuram@marvell.com>
>>>>>>>> ---
>>>>>>>> v3..v4:
>>>>>>>> - Update text under packet_mode as per Cristian.
>>>>>>>> - Update rte_eth_softnic_tm.c based on Jasvinder's comments.
>>>>>>>> - Add error enum
>>>>>> RTE_TM_ERROR_TYPE_SHAPER_PROFILE_PACKET_MODE
>>>>>>>> - Fix shaper_profile_check() with packet mode check
>>>>>>>> - Fix typo's
>>>>>>>>
>>>>>>>
>>>>>>> Acked-by: Cristian Dumitrescu <cristian.dumitrescu@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.
>>>
>>> I think, accidentally we can not make a library as NON-experimental.
>>> TM never went through experimental to mature transition(see git log
>>> lib/librte_ethdev/rte_tm.h)
>>> It was a bug to not mark as experimental in each function in the ABI process.
>>> Some of the features like packet marking are not even implemented by any HW.
>>> I think, we can make API stable only all the features are implemented
>>> by one or two HW.
>>
>> Fair enough, specially if the API is not ready yet.
>>
>> But they were part of stable ABI, and marking them as experimental now will
>> break the old applications using these APIs.
> 
> it is still marked as EXPERIMENTAL everywhere and API is not ready yet.

Existing experimental marks are text only for human parsing.

The compiler attribute and build time checks are missing, and the symbol in the
binary doesn't have experimental tag. Our scripts and automated checks won't
detect it as experimental.

My point is just having experimental comment in header file is not enough to
qualify the APIs as experimental.

> Anyway, we need to break the ABI to make it work on various HW.
> I am not sure what to do?
> IMO, We need to send a patch as Fixes: for the bug of not adding
> __rte_experimental in each function.

Yes, this is where we are, both you and Cristian suggest API is not ready and
should be experimental, but they were part of stable ABI, making them
experimental will break the ABI.
It looks like there is no good option but we should select one of the bad ones.

> 
> 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*
>>
>>>
>>>>
>>>> Ray, Neil, David, Luca, Kevin, what do you think?
>>