Re: linux-next: [DOCS] build warning after merge of the tip tree

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Randy Dunlap]

+ linux-doc + Jon

On 1/7/26 2:10 PM, Randy Dunlap wrote:
> 
> 
> On 1/7/26 1:54 PM, Peter Zijlstra wrote:
>> On Wed, Jan 07, 2026 at 04:15:48PM +1100, Stephen Rothwell wrote:
>>> Hi all,
>>>
>>> After merging the tip tree, today's linux-next build (htmldocs) produced
>>> this warning:
>>>
>>> Documentation/core-api/kref:328: include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
>>>   int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), str
>>> uct mutex *mutex) __cond_acquires(true# mutex)
>>>   ------------------------------------------------------------------------------------------------^
>>> Documentation/core-api/kref:328: include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
>>>   int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
>>>   --------------------------------------------------------------------------------------------^
>>>
>>> Introduced by commit
>>>
>>>   5e256db9325e ("kref: Add context-analysis annotations")
>>
>> I really have no clue what that thing is on about. The code is fine and
>> works as intended.
>>
>> My go-to fix for anything kdoc is to change '/**' into '/*' until it
>> goes away.
> 
> Yes, that works.
> 
> I think that kernel-doc is just confused by the trailing __cond_acquires(true# lock).
> 
> Mauro, would you take a look, please?
We can trivially ignore "__cond_acquires(.*)" in kernel-doc to
eliminate such build warnings.

Is that sufficient? Sure.
Is it the right thing to do? IDK.
Comments?

~Randy
---
 tools/lib/python/kdoc/kdoc_parser.py |    1 +
 1 file changed, 1 insertion(+)

--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -186,6 +186,7 @@ function_xforms  = [
     (KernRe(r"__sched +"), ""),
     (KernRe(r"_noprof"), ""),
     (KernRe(r"__always_unused *"), ""),
+    (KernRe(r"__cond_acquires\s*\(.*\)"), ""),
     (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""),
     (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
     (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Mauro Carvalho Chehab]

On Thu, 22 Jan 2026 17:06:28 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> + linux-doc + Jon
> 
> On 1/7/26 2:10 PM, Randy Dunlap wrote:
> > 
> > 
> > On 1/7/26 1:54 PM, Peter Zijlstra wrote:  
> >> On Wed, Jan 07, 2026 at 04:15:48PM +1100, Stephen Rothwell wrote:  
> >>> Hi all,
> >>>
> >>> After merging the tip tree, today's linux-next build (htmldocs) produced
> >>> this warning:
> >>>
> >>> Documentation/core-api/kref:328: include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
> >>>   int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), str
> >>> uct mutex *mutex) __cond_acquires(true# mutex)
> >>>   ------------------------------------------------------------------------------------------------^
> >>> Documentation/core-api/kref:328: include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
> >>>   int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
> >>>   --------------------------------------------------------------------------------------------^
> >>>
> >>> Introduced by commit
> >>>
> >>>   5e256db9325e ("kref: Add context-analysis annotations")  
> >>
> >> I really have no clue what that thing is on about. The code is fine and
> >> works as intended.
> >>
> >> My go-to fix for anything kdoc is to change '/**' into '/*' until it
> >> goes away.  
> > 
> > Yes, that works.
> > 
> > I think that kernel-doc is just confused by the trailing __cond_acquires(true# lock).
> > 
> > Mauro, would you take a look, please?  
> We can trivially ignore "__cond_acquires(.*)" in kernel-doc to
> eliminate such build warnings.
> 
> Is that sufficient? Sure.
> Is it the right thing to do? IDK.
> Comments?

This fix sounds right to me. If not there at the patch,
I would improve the include/linux/kref.h documentation to 
describe __cond_requires() inside the kernel-doc documentation
(or at kref.rst).

> 
> ~Randy
> ---
>  tools/lib/python/kdoc/kdoc_parser.py |    1 +
>  1 file changed, 1 insertion(+)
> 
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -186,6 +186,7 @@ function_xforms  = [
>      (KernRe(r"__sched +"), ""),
>      (KernRe(r"_noprof"), ""),
>      (KernRe(r"__always_unused *"), ""),
> +    (KernRe(r"__cond_acquires\s*\(.*\)"), ""),

Regex here is too broad, as it is greedy: it may drop more
than expected. Perhaps:

    (KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),

With that, feel free to add:

	Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

>      (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""),
>      (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
>      (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
> 


Thanks,
Mauro

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Randy Dunlap]

Hi Mauro,

On 1/22/26 11:11 PM, Mauro Carvalho Chehab wrote:
> On Thu, 22 Jan 2026 17:06:28 -0800
> Randy Dunlap <rdunlap@infradead.org> wrote:
> 
>> + linux-doc + Jon
>>
>> On 1/7/26 2:10 PM, Randy Dunlap wrote:
>>>
>>>
>>> On 1/7/26 1:54 PM, Peter Zijlstra wrote:  
>>>> On Wed, Jan 07, 2026 at 04:15:48PM +1100, Stephen Rothwell wrote:  
>>>>> Hi all,
>>>>>
>>>>> After merging the tip tree, today's linux-next build (htmldocs) produced
>>>>> this warning:
>>>>>
>>>>> Documentation/core-api/kref:328: include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
>>>>>   int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), str
>>>>> uct mutex *mutex) __cond_acquires(true# mutex)
>>>>>   ------------------------------------------------------------------------------------------------^
>>>>> Documentation/core-api/kref:328: include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
>>>>>   int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
>>>>>   --------------------------------------------------------------------------------------------^
>>>>>
>>>>> Introduced by commit
>>>>>
>>>>>   5e256db9325e ("kref: Add context-analysis annotations")  
>>>>
>>>> I really have no clue what that thing is on about. The code is fine and
>>>> works as intended.
>>>>
>>>> My go-to fix for anything kdoc is to change '/**' into '/*' until it
>>>> goes away.  
>>>
>>> Yes, that works.
>>>
>>> I think that kernel-doc is just confused by the trailing __cond_acquires(true# lock).
>>>
>>> Mauro, would you take a look, please?  
>> We can trivially ignore "__cond_acquires(.*)" in kernel-doc to
>> eliminate such build warnings.
>>
>> Is that sufficient? Sure.
>> Is it the right thing to do? IDK.
>> Comments?
> 
> This fix sounds right to me. If not there at the patch,
> I would improve the include/linux/kref.h documentation to 
> describe __cond_requires() inside the kernel-doc documentation
> (or at kref.rst).

It's there in include/linux/compiler-context-analysis.h.

> 
>>
>> ~Randy
>> ---
>>  tools/lib/python/kdoc/kdoc_parser.py |    1 +
>>  1 file changed, 1 insertion(+)
>>
>> --- a/tools/lib/python/kdoc/kdoc_parser.py
>> +++ b/tools/lib/python/kdoc/kdoc_parser.py
>> @@ -186,6 +186,7 @@ function_xforms  = [
>>      (KernRe(r"__sched +"), ""),
>>      (KernRe(r"_noprof"), ""),
>>      (KernRe(r"__always_unused *"), ""),
>> +    (KernRe(r"__cond_acquires\s*\(.*\)"), ""),
> 
> Regex here is too broad, as it is greedy: it may drop more
> than expected. Perhaps:
> 
>     (KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),

Ah, thanks.

> With that, feel free to add:
> 
> 	Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
>>      (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""),
>>      (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
>>      (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
>>
> 
> 
> Thanks,
> Mauro

-- 
~Randy

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Peter Zijlstra]

On Fri, Jan 23, 2026 at 08:11:26AM +0100, Mauro Carvalho Chehab wrote:

> >  tools/lib/python/kdoc/kdoc_parser.py |    1 +
> >  1 file changed, 1 insertion(+)
> > 
> > --- a/tools/lib/python/kdoc/kdoc_parser.py
> > +++ b/tools/lib/python/kdoc/kdoc_parser.py
> > @@ -186,6 +186,7 @@ function_xforms  = [
> >      (KernRe(r"__sched +"), ""),
> >      (KernRe(r"_noprof"), ""),
> >      (KernRe(r"__always_unused *"), ""),
> > +    (KernRe(r"__cond_acquires\s*\(.*\)"), ""),
> 
> Regex here is too broad, as it is greedy: it may drop more
> than expected. Perhaps:
> 
>     (KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),

I have of course no idea what so ever how any of this works, but it
occurs to me that __acquires() and __releases() are not in that same
list, what happens to them?

Also, there will 'soon' be an equivalent: __cond_releases():

  https://lkml.kernel.org/r/20260121111213.634625032@infradead.org

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Mauro Carvalho Chehab]

Hi Peter,

On Fri, 23 Jan 2026 12:28:56 +0100
Peter Zijlstra <peterz@infradead.org> wrote:

> On Fri, Jan 23, 2026 at 08:11:26AM +0100, Mauro Carvalho Chehab wrote:
> 
> > >  tools/lib/python/kdoc/kdoc_parser.py |    1 +
> > >  1 file changed, 1 insertion(+)
> > > 
> > > --- a/tools/lib/python/kdoc/kdoc_parser.py
> > > +++ b/tools/lib/python/kdoc/kdoc_parser.py
> > > @@ -186,6 +186,7 @@ function_xforms  = [
> > >      (KernRe(r"__sched +"), ""),
> > >      (KernRe(r"_noprof"), ""),
> > >      (KernRe(r"__always_unused *"), ""),
> > > +    (KernRe(r"__cond_acquires\s*\(.*\)"), ""),  
> > 
> > Regex here is too broad, as it is greedy: it may drop more
> > than expected. Perhaps:
> > 
> >     (KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),  
> 
> I have of course no idea what so ever how any of this works, but it
> occurs to me that __acquires() and __releases() are not in that same
> list, what happens to them?

You mean in functions like those, for instance:

	int device_links_read_lock(void) __acquires(&device_links_srcu)
	{
	        return srcu_read_lock(&device_links_srcu);
	}

	void device_links_read_unlock(int idx) __releases(&device_links_srcu)
	{
	        srcu_read_unlock(&device_links_srcu, idx);
	}

Yeah, we need to add something for those as well.

> 
> Also, there will 'soon' be an equivalent: __cond_releases():
> 
>   https://lkml.kernel.org/r/20260121111213.634625032@infradead.org

The table "function_xforms" is a set of regular expressions to replace 
macros into something that will be a pure C function declaration.
It should be able to handle most macros (*).

Each line in the table has two arguments:

	- a regex
	- a replace expression

In this specific case, if we remove __cond_acquires(.*) from the
function prototype, the remaining function will be a pure C 
prototype.

So, I'd say we need to have all 4 macros there:

	(KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),
	(KernRe(r"__cond_releases\s*\([^\)]*\)"), ""),
	(KernRe(r"__acquires\s*\([^\)]*\)"), ""),
	(KernRe(r"__releases\s*\([^\)]*\)"), ""),

to avoid any warnings related to such annotations.

(*) there is a variant for very complex macros - currently used
    only for struct_group_*.

Thanks,
Mauro

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Peter Zijlstra]

On Fri, Jan 23, 2026 at 01:20:54PM +0100, Mauro Carvalho Chehab wrote:

> > I have of course no idea what so ever how any of this works, but it
> > occurs to me that __acquires() and __releases() are not in that same
> > list, what happens to them?
> 
> You mean in functions like those, for instance:
> 
> 	int device_links_read_lock(void) __acquires(&device_links_srcu)
> 	{
> 	        return srcu_read_lock(&device_links_srcu);
> 	}
> 
> 	void device_links_read_unlock(int idx) __releases(&device_links_srcu)
> 	{
> 	        srcu_read_unlock(&device_links_srcu, idx);
> 	}
> 
> Yeah, we need to add something for those as well.

Yes those. They are pre-existing sparse annotations that have been
co-opted and morphed into the clang thread-safety-analysis.

> > Also, there will 'soon' be an equivalent: __cond_releases():
> > 
> >   https://lkml.kernel.org/r/20260121111213.634625032@infradead.org
> 
> The table "function_xforms" is a set of regular expressions to replace 
> macros into something that will be a pure C function declaration.
> It should be able to handle most macros (*).
> 
> Each line in the table has two arguments:
> 
> 	- a regex
> 	- a replace expression
> 
> In this specific case, if we remove __cond_acquires(.*) from the
> function prototype, the remaining function will be a pure C 
> prototype.
> 
> So, I'd say we need to have all 4 macros there:
> 
> 	(KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),
> 	(KernRe(r"__cond_releases\s*\([^\)]*\)"), ""),
> 	(KernRe(r"__acquires\s*\([^\)]*\)"), ""),
> 	(KernRe(r"__releases\s*\([^\)]*\)"), ""),
> 
> to avoid any warnings related to such annotations.

There's also:

	__must_hold()
	__must_not_hold()
	__must_hold_shared()

	__acquires_shared()
	__cond_acquires_shared()
	__releases_shared()

	__no_context_analysis

On top of that, structure members can be annotated with:

	__guarded_by()
	__pt_guarded_by()


Thanks!

Re: linux-next: [DOCS] build warning after merge of the tip tree

[Randy Dunlap]

On 1/23/26 7:18 AM, Peter Zijlstra wrote:
> On Fri, Jan 23, 2026 at 01:20:54PM +0100, Mauro Carvalho Chehab wrote:
> 
>>> I have of course no idea what so ever how any of this works, but it
>>> occurs to me that __acquires() and __releases() are not in that same
>>> list, what happens to them?
>>
>> You mean in functions like those, for instance:
>>
>> 	int device_links_read_lock(void) __acquires(&device_links_srcu)
>> 	{
>> 	        return srcu_read_lock(&device_links_srcu);
>> 	}
>>
>> 	void device_links_read_unlock(int idx) __releases(&device_links_srcu)
>> 	{
>> 	        srcu_read_unlock(&device_links_srcu, idx);
>> 	}
>>
>> Yeah, we need to add something for those as well.
> 
> Yes those. They are pre-existing sparse annotations that have been
> co-opted and morphed into the clang thread-safety-analysis.
> 
>>> Also, there will 'soon' be an equivalent: __cond_releases():
>>>
>>>   https://lkml.kernel.org/r/20260121111213.634625032@infradead.org
>>
>> The table "function_xforms" is a set of regular expressions to replace 
>> macros into something that will be a pure C function declaration.
>> It should be able to handle most macros (*).
>>
>> Each line in the table has two arguments:
>>
>> 	- a regex
>> 	- a replace expression
>>
>> In this specific case, if we remove __cond_acquires(.*) from the
>> function prototype, the remaining function will be a pure C 
>> prototype.
>>
>> So, I'd say we need to have all 4 macros there:
>>
>> 	(KernRe(r"__cond_acquires\s*\([^\)]*\)"), ""),
>> 	(KernRe(r"__cond_releases\s*\([^\)]*\)"), ""),
>> 	(KernRe(r"__acquires\s*\([^\)]*\)"), ""),
>> 	(KernRe(r"__releases\s*\([^\)]*\)"), ""),
>>
>> to avoid any warnings related to such annotations.
> 
> There's also:
> 
> 	__must_hold()
> 	__must_not_hold()
> 	__must_hold_shared()
> 
> 	__acquires_shared()
> 	__cond_acquires_shared()
> 	__releases_shared()
> 
> 	__no_context_analysis
> 
> On top of that, structure members can be annotated with:
> 
> 	__guarded_by()
> 	__pt_guarded_by()

I was aware of some of these but not all of them.
Thanks for the list.
I'll update my patch for one regex to include all of these.

-- 
~Randy