[dpdk-stable] [RFC PATCH] mark experimental variables

[David Marchand]

On Tue, Nov 26, 2019 at 10:26 AM Ray Kinsella <mdr at ashroe.eu> wrote:
>
>
> My 2c is that it feels a little unweildy to have to annotate, every variable declaration.
> and also extern reference with __rte_experimental_var.
>
> Is there any easier way?

We use this framework so that the users are aware they are relying on
experimental API that can change overnight.
It would not happen if we could hide all of this behind accessors.
But here we reference them through macros / inlines with performance in mind.


This performance impact needs to be confirmed as a real requirement.
I caught some oddity like the librte_port stuff (with no in-tree
users, but different topic).


> > @@ -90,11 +90,15 @@ check_experimental_tags() { # <patch>
> >                               "headers ("current_file")";
> >                       ret = 1;
> >               }
> > -             if ($1 != "+__rte_experimental" || $2 != "") {
> > -                     print "__rte_experimental must appear alone on the line" \
> > -                             " immediately preceding the return type of a function."
> > -                     ret = 1;
> > +
> > +             if (NF == 1 && ($1 == "+__rte_experimental" ||
> > +                             $1 == "+__rte_experimental_var")) {
> > +                     next;
> >               }
> > +             print "__rte_experimental or __rte_experimental_var must " \
> > +                     "appear alone on the line immediately preceding the " \
> > +                     "return type of a function.";
>
> or variable?

Yes.


> > @@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process.
> >  To mark an API as experimental, the symbols which are desired to be exported
> >  must be placed in an EXPERIMENTAL version block in the corresponding libraries'
> >  version map script.
> > -Secondly, the corresponding prototypes of those exported functions (in the
> > -development header files), must be marked with the ``__rte_experimental`` tag
> > -(see ``rte_compat.h``).
> > +Secondly, the corresponding prototypes of those exported functions (resp.
> > +variables) must be marked with the ``__rte_experimental`` (resp.
> > +``__rte_experimental_var``) tag in the development header files (see
> > +``rte_compat.h``).
>
> Suggest simplifying as follows (remove the resp.).
>
> Secondly, the corresponding prototypes of those exported functions (or
> variables) must be marked with the ``__rte_experimental`` (or
> ``__rte_experimental_var``) tag in the development header files (see
> ``rte_compat.h``).

"or" sounds better.


-- 
David Marchand