Re: [dpdk-dev] [PATCH v2] doc: add reserve fields to eventdev public structures

[Jerin Jacob <jerinjacobk@gmail.com>]

On Thu, Aug 6, 2020 at 6:29 AM Stephen Hemminger
<stephen@networkplumber.org> wrote:
>
> On Wed, 5 Aug 2020 14:40:01 +0530
> Jerin Jacob <jerinjacobk@gmail.com> wrote:
>
> > On Wed, Aug 5, 2020 at 2:16 PM Kinsella, Ray <mdr@ashroe.eu> wrote:
> > >
> > >
> > >
> > > On 04/08/2020 17:20, Stephen Hemminger wrote:
> > > > On Tue, 4 Aug 2020 11:41:53 +0100
> > > > Bruce Richardson <bruce.richardson@intel.com> wrote:
> > > >
> > > >> On Mon, Aug 03, 2020 at 12:59:03PM +0530, pbhagavatula@marvell.com wrote:
> > > >>> From: Pavan Nikhilesh <pbhagavatula@marvell.com>
> > > >>>
> > > >>> Add 64 byte padding at the end of event device public structure to allow
> > > >>> future extensions.
> > > >>>
> > > >>> Signed-off-by: Pavan Nikhilesh <pbhagavatula@marvell.com>
> > > >>> Acked-by: Jerin Jacob <jerinj@marvell.com>
> > > >>> ---
> > > >>>  v2 Changes:
> > > >>>  - Modify commit title.
> > > >>>  - Add patch reference to doc.
> > > >>>
> > > >>>  doc/guides/rel_notes/deprecation.rst | 11 +++++++++++
> > > >>>  1 file changed, 11 insertions(+)
> > > >>>
> > > >>> diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst
> > > >>> index ea4cfa7a4..ec5db68e9 100644
> > > >>> --- a/doc/guides/rel_notes/deprecation.rst
> > > >>> +++ b/doc/guides/rel_notes/deprecation.rst
> > > >>> @@ -151,3 +151,14 @@ Deprecation Notices
> > > >>>    Python 2 support will be completely removed in 20.11.
> > > >>>    In 20.08, explicit deprecation warnings will be displayed when running
> > > >>>    scripts with Python 2.
> > > >>> +
> > > >>> +* eventdev: A 64 byte padding is added at the end of the following structures
> > > >>> +  in event device library to support future extensions:
> > > >>> +  ``rte_event_crypto_adapter_conf``, ``rte_event_eth_rx_adapter_conf``,
> > > >>> +  ``rte_event_eth_rx_adapter_queue_conf``, ``rte_event_eth_tx_adapter_conf``,
> > > >>> +  ``rte_event_timer_adapter_conf``, ``rte_event_timer_adapter_info``,
> > > >>> +  ``rte_event_dev_info``, ``rte_event_dev_config``, ``rte_event_queue_conf``,
> > > >>> +  ``rte_event_port_conf``, ``rte_event_timer_adapter``,
> > > >>> +  ``rte_event_timer_adapter_data``.
> > > >>> +  Reference:
> > > >>> +  http://patches.dpdk.org/project/dpdk/list/?series=10728&archive=both&state=*
> > > >>> --
> > > >>
> > > >> I don't like this idea of adding lots of padding to the ends of these
> > > >> structures. For some structures, such as the public arrays for devices it
> > > >> may be necessary, but for all the conf structures passed as parameters to
> > > >> functions I think we can do better. Since these structures are passed by
> > > >> the user to various functions, function versioning can be used to ensure
> > > >> that the correct function in eventdev is always called. From there to the
> > > >> individual PMDs, we can implement ABI compatibility by either:
> > > >> 1. including the length of the struct as a parameter to the driver. (This is
> > > >>   a bit similar to my proposal for rawdev [1])
> > > >> 2. including the ABI version as a parameter to the driver.
> > > >>
> > > >> Regards
> > > >> /Bruce
> > > >>
> > > >> [1] http://inbox.dpdk.org/dev/?q=enhance+rawdev+APIs
> > > >
> > > > This is a bad idea.
> > > >
> > > > Reserved fields won't work because nothing requires that the application
> > > > zero them. You can't start using them later because the application
> > > > may put uninitialized or junk data there.
> > > >
> > >
> > > +1, to Stephens comments.
> >
> > Since the problem is not specific to one substem, if we need to add a
> > field in config structures,
> > What will the expected way of handling across the DPDK?
>
> If you need fields go through the normal enhancement process, and get it
> reviewed and put them in a major release milestone.
> Sorry, there is no free lunch by adding reserved fields.
>
> Look up YAGNI

YAGNI is useful. But If we need to wait for one year to change the API
then it is the problem.
That's time frame silicon companies are making the next generation of
silicon nowadays.

We just tried to follow the existing scheme of things in the codebase[1].

But I am also not a great fan of the Reserved filed scheme either.
Probably it is better to add the new feature as a new API or config
structure with
out breaking anything(as experimental) and upcoming next release, rework to
adapt to subsystem API philosophy.


[1]
lib/librte_ethdev/rte_ethdev.h: uint64_t reserved_64s[2]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: void *reserved_ptrs[2];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: uint64_t reserved_64s[2]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: void *reserved_ptrs[2];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: uint64_t reserved_64s[2]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: void *reserved_ptrs[2];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: uint64_t reserved_64s[2]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: void *reserved_ptrs[2];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: uint64_t reserved_64s[2]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev.h: void *reserved_ptrs[2];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev_core.h:    uint64_t reserved_64s[4]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev_core.h:    void *reserved_ptrs[4];   /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev_core.h:    uint64_t reserved_64s[4]; /**<
Reserved for future fields */
lib/librte_ethdev/rte_ethdev_core.h:    void *reserved_ptrs[4];   /**<
Reserved for future fields */
lib/librte_eal/linux/eal_timer.c:       uint64_t reserved0;
/**< Reserved for future use. */
lib/librte_eal/linux/eal_timer.c:       uint64_t reserved1;
/**< Reserved for future use. */
lib/librte_eal/linux/eal_timer.c:       uint64_t reserved2[25];
/**< Reserved for future use. */
lib/librte_eal/linux/eal_timer.c:       uint64_t reserved3;
/**< Reserved for future use. */
lib/librte_eal/linux/eal_timer.c:               uint64_t reserved4;
/**< Reserved for future use. */
lib/librte_eventdev/rte_eventdev.h:                     /**< Reserved
for future use */
lib/librte_eventdev/rte_eventdev.h:     uint64_t reserved_64s[4]; /**<
Reserved for future fields */
lib/librte_eventdev/rte_eventdev.h:     void *reserved_ptrs[4];   /**<
Reserved for future fields */
lib/librte_eventdev/rte_eventdev.h:     uint64_t reserved_64s[4]; /**<
Reserved for future fields */
lib/librte_eventdev/rte_eventdev.h:     void *reserved_ptrs[4];   /**<
Reserved for future fields */