[PATCH v2 2/6] eal: adapt EAL to present rte optional atomics API

[Morten Brørup]

> From: Tyler Retzlaff [mailto:roretzla at linux.microsoft.com]
> Sent: Monday, 14 August 2023 19.47
> 
> On Mon, Aug 14, 2023 at 10:00:49AM +0200, Morten Brørup wrote:
> > > From: Tyler Retzlaff [mailto:roretzla at linux.microsoft.com]
> > > Sent: Friday, 11 August 2023 19.32
> > >
> > > Adapt the EAL public headers to use rte optional atomics API instead
> of
> > > directly using and exposing toolchain specific atomic builtin
> intrinsics.
> > >
> > > Signed-off-by: Tyler Retzlaff <roretzla at linux.microsoft.com>
> > > ---
> >
> > [...]
> >
> 
> will fix the comments identified.
> 
> >
> > [...]
> >
> > > --- a/lib/eal/include/generic/rte_spinlock.h
> > > +++ b/lib/eal/include/generic/rte_spinlock.h
> > > @@ -29,7 +29,7 @@
> > >   * The rte_spinlock_t type.
> > >   */
> > >  typedef struct __rte_lockable {
> > > -	volatile int locked; /**< lock status 0 = unlocked, 1 = locked */
> > > +	volatile int __rte_atomic locked; /**< lock status 0 = unlocked, 1
> =
> > > locked */
> >
> > I think __rte_atomic should be before the type:
> > 	volatile __rte_atomic int locked; /**< lock status [...]
> > Alternatively (just mentioning it, I know we don't use this form):
> > 	volatile __rte_atomic(int) locked; /**< lock status [...]
> >
> > Thinking of where you would put "const" might help.

Regarding "const", I use the mental trick of reading from right-to-left when pointers are involved, e.g.:

const int * * const x;
----5---- 4 3 --2-- 1

x(1) is a const(2) pointer(3) to a pointer(4) to a const int(5).

And yes, treating "const int" as one word is cheating... formally it should be "int" "const", i.e. the reverse order; but that is not the convention, so I have learned to accept it.

> >
> > Maybe your order is also correct, so it is a matter of preference.
> 
> so for me what you suggest is the canonical convention for c and i did
> initially try to make the change with this convention but ran into
> trouble when using the keyword in a context used as a type specifier
> and the type was incomplete.
> 
> the rte_mcslock is a good example for illustration.
> 
>   // original struct
>   typedef struct rte_mcslock {
>     struct rte_mcslock *next;
>     ...
>   };
> 
>   it simply doesn't work / won't compile (at least with clang) which is
>   what drove me to use the less-often used syntax.
> 
>   typedef struct rte_mcslock {
>     _Atomic struct rte_mcslock *next;
>     ...
>   };
> 
>   In file included from ../app/test/test_mcslock.c:19:
>   ..\lib\eal\include\rte_mcslock.h:36:2: error: _Atomic cannot be
> applied
>   to incomplete type 'struct rte_mcslock'
> 	  _Atomic struct rte_mcslock *next;
> 	  ^
>   ..\lib\eal\include\rte_mcslock.h:35:16: note: definition of 'struct
>   rte_mcslock' is not complete until the closing '}'
>   typedef struct rte_mcslock {
> 		 ^
>   1 error generated.
> 
> so i ended up choosing to use a single syntax by convention consistently
> rather than using one for the exceptional case and one everywhere else.
> 
> i think (based on our other thread of discussion) i would recommend we
> use adopt and require the use of the _Atomic(T) macro to disambiguate it
> also has the advantage of not being churned later when we can do c++23.
> 
>   // using macro
>   typedef struct rte_mcslock {
>     _Atomic(struct rte_mcslock *) next;

This makes it an atomic pointer. Your example above tried making the struct rts_mcslock atomic. Probably what you wanted was:
  typedef struct rte_mcslock {
    struct rte_mcslock * _Atomic next;
    ...
  };

Like "const", the convention should be putting it before any type, but after the "*" for pointers.

I suppose clang doesn't accept applying _Atomic to incomplete types, regardless where you put it... I.e. this should also fail, I guess:
  typedef struct rte_mcslock {
    struct rte_mcslock _Atomic * next;
    ...
  };

>     ...
>   };
> 
> this is much easier at a glance to know when the specified type is the T
> or the T * similarly in parameter lists it becomes more clear too.
> 
> e.g.
> void foo(int *v)
> 
> that it is either void foo(_Atomic(int) *v) or void foo(_Atomic(int *)
> v) becomes
> much clearer without having to do mental gymnastics.

The same could be said about making "const" clearer:
void foo(const(int) * v) instead of void foo(const int * v), and
void foo(const(int *) v) instead of void foo(int * const v).

Luckily, we don't need toolchain specific handling of "const", so let's just leave that the way it is. :-)

> 
> so i propose we retain
> 
>   #define __rte_atomic _Atomic
> 
>   allow it to be used in contexts where we need a type-qualifier.
>   note:
>     most of the cases where _Atomic is used as a type-qualifier it
>     is a red flag that we are sensitive to an implementation detail
>     of the compiler. in time i hope most of these will go away as we
>     remove deprecated rte_atomic_xx apis.
> 
> but also introduce the following macro
> 
>   #define RTE_ATOMIC(type) _Atomic(type)
>   require it be used in the contexts that we are using it as a type-
> specifier.
> 
> if folks agree with this please reply back positively and i'll update
> the series. feel free to propose alternate names or whatever, but sooner
> than later so i don't have to churn things too much :)

+1 to Tyler's updated proposal, with macro names as suggested.

If anyone disagrees, please speak up soon!

If in doubt, please read https://en.cppreference.com/w/c/language/atomic carefully. It says:
(1) _Atomic(type-name) (since C11): Use as a type specifier; this designates a new atomic type.
(2) _Atomic type-name (since C11): Use as a type qualifier; this designates the atomic version of type-name. In this role, it may be mixed with const, volatile, and restrict, although unlike other qualifiers, the atomic version of type-name may have a different size, alignment, and object representation.

NB: I hadn't noticed this before, otherwise I had probably suggested using _Atomic(T) earlier on. We learn something new every day. :-)

> 
> thanks!

Sorry about the late response, Tyler. Other work prevented me from setting aside coherent time to review your updated proposal.

> 
> >
> > The DPDK coding style guidelines doesn't mention where to place
> "const", but looking at the code, it seems to use "const unsigned int"
> and "const char *".
> 
> we probably should document it as a convention and most likely we should
> adopt what is already in use more commonly.

+1, but not as part of this series. :-)