[PATCH v5 1/9] eal: annotate spinlock, rwlock and seqlock

[David Marchand]

Hello Intel CI team,

On Wed, Feb 1, 2023 at 12:16 PM David Marchand
<david.marchand at redhat.com> wrote:

[snip]

> Note:
> Doxygen preprocessor does not understand trailing function attributes
> (this can be observed with the rte_seqlock.h header).
> One would think that expanding the annotation macros to a noop in
> rte_lock_annotations.h would be enough (since RTE_ANNOTATE_LOCKS is not
> set during doxygen processing)). Unfortunately, the use of
> EXPAND_ONLY_PREDEF defeats this.
>
> Removing EXPAND_ONLY_PREDEF entirely is not an option as it would expand
> all other DPDK macros.
>
> The chosen solution is to expand the annotation macros explicitly to a
> noop in PREDEFINED.
>

[snip]

> ---
> Changes since v4:
> - hid annotations from Doxygen,
> - fixed typos,

[snip]

> diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
> index f0886c3bd1..e859426099 100644
> --- a/doc/api/doxy-api.conf.in
> +++ b/doc/api/doxy-api.conf.in
> @@ -84,6 +84,17 @@ FILE_PATTERNS           = rte_*.h \
>  PREDEFINED              = __DOXYGEN__ \
>                            RTE_HAS_CPUSET \
>                            VFIO_PRESENT \
> +                          __rte_lockable= \
> +                          __rte_guarded_by(x)= \
> +                          __rte_exclusive_locks_required(x)= \
> +                          __rte_exclusive_lock_function(x)= \
> +                          __rte_exclusive_trylock_function(x)= \
> +                          __rte_assert_exclusive_lock(x)= \
> +                          __rte_shared_locks_required(x)= \
> +                          __rte_shared_lock_function(x)= \
> +                          __rte_shared_trylock_function(x)= \
> +                          __rte_assert_shared_lock(x)= \
> +                          __rte_unlock_function(x)= \
>                            __attribute__(x)=
>
>  OPTIMIZE_OUTPUT_FOR_C   = YES

I received this report:
http://mails.dpdk.org/archives/test-report/2023-February/345705.html

FAILED: doc/api/html
/usr/bin/python3 ../doc/api/generate_doxygen.py doc/api/html
/usr/bin/doxygen doc/api/doxy-api.conf
/root/UB2204-64_K5.15.0_GCC11.3.0/x86_64-native-linuxapp-doc/26733/dpdk/lib/eal/include/rte_seqlock.h:218:
error: Found ')' without opening '(' for trailing return type ' ->
lock)...' (warning treated as error, aborting now)
Traceback (most recent call last):
  File "/root/UB2204-64_K5.15.0_GCC11.3.0/x86_64-native-linuxapp-doc/26733/dpdk/x86_64-native-linuxapp-doc/../doc/api/generate_doxygen.py",
line 13, in <module>
    subprocess.run(doxygen_command, check=True, stdout=out)
  File "/usr/lib/python3.10/subprocess.py", line 524, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['/usr/bin/doxygen',
'doc/api/doxy-api.conf']' returned non-zero exit status 1.

This error is what the patch 1 in this series (with the
doc/api/doxy-api.conf.in update) tries to avoid.

I tested my series in a fresh Ubuntu 22.04 container and I can't
reproduce this error.
Please share how this test was run in your lab so I can replicate.


Thanks.

-- 
David Marchand