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

[Tu, Lijuan]

> -----Original Message-----
> From: David Marchand <david.marchand at redhat.com>
> Sent: Wednesday, February 1, 2023 8:33 PM
> To: Chen, Zhaoyan <zhaoyan.chen at intel.com>; Tu, Lijuan
> <lijuan.tu at intel.com>; sys_stv <sys_stv at intel.com>
> Cc: dev at dpdk.org; Coquelin, Maxime <maxime.coquelin at redhat.com>;
> stephen at networkplumber.org; Xia, Chenbo <chenbo.xia at intel.com>; Hu, Jiayu
> <jiayu.hu at intel.com>; Wang, YuanX <yuanx.wang at intel.com>; Ding, Xuan
> <xuan.ding at intel.com>; mb at smartsharesystems.com; Burakov, Anatoly
> <anatoly.burakov at intel.com>; mattias.ronnblom
> <mattias.ronnblom at ericsson.com>; David Christensen
> <drc at linux.vnet.ibm.com>; Richardson, Bruce <bruce.richardson at intel.com>;
> Konstantin Ananyev <konstantin.v.ananyev at yandex.ru>
> Subject: Re: [PATCH v5 1/9] eal: annotate spinlock, rwlock and seqlock
> 
> 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.

Hi David,

Sorry, bothered you. There is no error with this series. 

The error is caused by the CI doesn't apply any changes with doc/*.
Community decided to exclude doc/*,  as doc/* change frequently,
especially the release notes, cause a lot of conflict with main tree.

Here is command we used:
git pw series apply 26733 --exclude=doc/** 

We will raise a discussion for this in community CI meeting.
My thought is to narrow down exclude scope to doc/guides or 
doc/guides/rel_notes/*

thanks,
Lijuan

> 
> 
> Thanks.
> 
> --
> David Marchand