[PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Vlastimil Babka]

We have many SLAB_ flags but many are used only internally, by kunit
tests or debugging subsystems cooperating with slab, or are set
according to slab_debug boot parameter.

Create kerneldocs for the commonly used flags that may be passed to
kmem_cache_create(). SLAB_TYPESAFE_BY_RCU already had a detailed
description, so turn it to a kerneldoc. Add some details for
SLAB_ACCOUNT, SLAB_RECLAIM_ACCOUNT and SLAB_HWCACHE_ALIGN. Reference
them from the __kmem_cache_create_args() kerneldoc.

Signed-off-by: Vlastimil Babka <vbabka@suse.cz>
---
I plan to take this in the slab tree, but a question for Jon/linux-doc:

I think I'm doing properly the "Object-like macro documentation" for
parameter-less macros from the doc-guide. Yet I can see in the htmldocs
things like "SLAB_TYPESAFE_BY_RCU ()" and "Parameters". Is there a bug
in the sphinx machinery? Thanks.

 include/linux/slab.h | 60 ++++++++++++++++++++++++++++++--------------
 mm/slab_common.c     | 14 ++++++++++-
 2 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/include/linux/slab.h b/include/linux/slab.h
index b35e2db7eb0e..49e9fb93e864 100644
--- a/include/linux/slab.h
+++ b/include/linux/slab.h
@@ -77,7 +77,17 @@ enum _slab_flag_bits {
 #define SLAB_POISON		__SLAB_FLAG_BIT(_SLAB_POISON)
 /* Indicate a kmalloc slab */
 #define SLAB_KMALLOC		__SLAB_FLAG_BIT(_SLAB_KMALLOC)
-/* Align objs on cache lines */
+/**
+ * define SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.
+ *
+ * Sufficiently large objects are aligned on cache line boundary. For object
+ * size smaller than a half of cache line size, the alignment is on the half of
+ * cache line size. In general, if object size is smaller than 1/2^n of cache
+ * line size, the alignment is adjusted to 1/2^n.
+ *
+ * If explicit alignment is also requested by the respective
+ * &struct kmem_cache_args field, the greater of both is alignments is applied.
+ */
 #define SLAB_HWCACHE_ALIGN	__SLAB_FLAG_BIT(_SLAB_HWCACHE_ALIGN)
 /* Use GFP_DMA memory */
 #define SLAB_CACHE_DMA		__SLAB_FLAG_BIT(_SLAB_CACHE_DMA)
@@ -87,8 +97,8 @@ enum _slab_flag_bits {
 #define SLAB_STORE_USER		__SLAB_FLAG_BIT(_SLAB_STORE_USER)
 /* Panic if kmem_cache_create() fails */
 #define SLAB_PANIC		__SLAB_FLAG_BIT(_SLAB_PANIC)
-/*
- * SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS!
+/**
+ * define SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS!
  *
  * This delays freeing the SLAB page by a grace period, it does _NOT_
  * delay object freeing. This means that if you do kmem_cache_free()
@@ -99,20 +109,22 @@ enum _slab_flag_bits {
  * stays valid, the trick to using this is relying on an independent
  * object validation pass. Something like:
  *
- * begin:
- *  rcu_read_lock();
- *  obj = lockless_lookup(key);
- *  if (obj) {
- *    if (!try_get_ref(obj)) // might fail for free objects
- *      rcu_read_unlock();
- *      goto begin;
+ * ::
+ *
+ *  begin:
+ *   rcu_read_lock();
+ *   obj = lockless_lookup(key);
+ *   if (obj) {
+ *     if (!try_get_ref(obj)) // might fail for free objects
+ *       rcu_read_unlock();
+ *       goto begin;
  *
- *    if (obj->key != key) { // not the object we expected
- *      put_ref(obj);
- *      rcu_read_unlock();
- *      goto begin;
- *    }
- *  }
+ *     if (obj->key != key) { // not the object we expected
+ *       put_ref(obj);
+ *       rcu_read_unlock();
+ *       goto begin;
+ *     }
+ *   }
  *  rcu_read_unlock();
  *
  * This is useful if we need to approach a kernel structure obliquely,
@@ -137,7 +149,6 @@ enum _slab_flag_bits {
  *
  * Note that SLAB_TYPESAFE_BY_RCU was originally named SLAB_DESTROY_BY_RCU.
  */
-/* Defer freeing slabs to RCU */
 #define SLAB_TYPESAFE_BY_RCU	__SLAB_FLAG_BIT(_SLAB_TYPESAFE_BY_RCU)
 /* Trace allocations and frees */
 #define SLAB_TRACE		__SLAB_FLAG_BIT(_SLAB_TRACE)
@@ -170,7 +181,12 @@ enum _slab_flag_bits {
 #else
 # define SLAB_FAILSLAB		__SLAB_FLAG_UNUSED
 #endif
-/* Account to memcg */
+/**
+ * define SLAB_ACCOUNT - Account allocations to memcg.
+ *
+ * All object allocations from this cache will be memcg accounted, regardless of
+ * __GFP_ACCOUNT being or not being passed to individual allocations.
+ */
 #ifdef CONFIG_MEMCG
 # define SLAB_ACCOUNT		__SLAB_FLAG_BIT(_SLAB_ACCOUNT)
 #else
@@ -197,7 +213,13 @@ enum _slab_flag_bits {
 #endif
 
 /* The following flags affect the page allocator grouping pages by mobility */
-/* Objects are reclaimable */
+/**
+ * define SLAB_RECLAIM_ACCOUNT - Objects are reclaimable.
+ *
+ * Use this flag for caches that have an associated shrinker. As a result, slab
+ * pages are allocated with __GFP_RECLAIMABLE, which affects grouping pages by
+ * mobility, and are accounted in SReclaimable counter in /proc/meminfo
+ */
 #ifndef CONFIG_SLUB_TINY
 #define SLAB_RECLAIM_ACCOUNT	__SLAB_FLAG_BIT(_SLAB_RECLAIM_ACCOUNT)
 #else
diff --git a/mm/slab_common.c b/mm/slab_common.c
index 744324465615..4d8353b601a6 100644
--- a/mm/slab_common.c
+++ b/mm/slab_common.c
@@ -257,11 +257,23 @@ static struct kmem_cache *create_cache(const char *name,
  * @object_size: The size of objects to be created in this cache.
  * @args: Additional arguments for the cache creation (see
  *        &struct kmem_cache_args).
- * @flags: See %SLAB_* flags for an explanation of individual @flags.
+ * @flags: See the desriptions of individual flags. The common ones are listed
+ *         in the description below.
  *
  * Not to be called directly, use the kmem_cache_create() wrapper with the same
  * parameters.
  *
+ * Commonly used @flags:
+ *
+ * &SLAB_ACCOUNT - Account allocations to memcg.
+ *
+ * &SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.
+ *
+ * &SLAB_RECLAIM_ACCOUNT - Objects are reclaimable.
+ *
+ * &SLAB_TYPESAFE_BY_RCU - Slab page (not individual objects) freeing delayed
+ * by a grace period - see the full description before using.
+ *
  * Context: Cannot be called within a interrupt, but can be interrupted.
  *
  * Return: a pointer to the cache on success, NULL on failure.
-- 
2.46.1

Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Jonathan Corbet]

Vlastimil Babka <vbabka@suse.cz> writes:

> We have many SLAB_ flags but many are used only internally, by kunit
> tests or debugging subsystems cooperating with slab, or are set
> according to slab_debug boot parameter.
>
> Create kerneldocs for the commonly used flags that may be passed to
> kmem_cache_create(). SLAB_TYPESAFE_BY_RCU already had a detailed
> description, so turn it to a kerneldoc. Add some details for
> SLAB_ACCOUNT, SLAB_RECLAIM_ACCOUNT and SLAB_HWCACHE_ALIGN. Reference
> them from the __kmem_cache_create_args() kerneldoc.
>
> Signed-off-by: Vlastimil Babka <vbabka@suse.cz>
> ---
> I plan to take this in the slab tree, but a question for Jon/linux-doc:
>
> I think I'm doing properly the "Object-like macro documentation" for
> parameter-less macros from the doc-guide. Yet I can see in the htmldocs
> things like "SLAB_TYPESAFE_BY_RCU ()" and "Parameters". Is there a bug
> in the sphinx machinery? Thanks.

No, it's totally bug-free and any appearance to the contrary is entirely
in your imagination :)

I don't think anybody has tried to do kerneldoc for macros that don't
look like functions; it doesn't surprise me that it doesn't work right. 

>  include/linux/slab.h | 60 ++++++++++++++++++++++++++++++--------------
>  mm/slab_common.c     | 14 ++++++++++-
>  2 files changed, 54 insertions(+), 20 deletions(-)
>
> diff --git a/include/linux/slab.h b/include/linux/slab.h
> index b35e2db7eb0e..49e9fb93e864 100644
> --- a/include/linux/slab.h
> +++ b/include/linux/slab.h
> @@ -77,7 +77,17 @@ enum _slab_flag_bits {
>  #define SLAB_POISON		__SLAB_FLAG_BIT(_SLAB_POISON)
>  /* Indicate a kmalloc slab */
>  #define SLAB_KMALLOC		__SLAB_FLAG_BIT(_SLAB_KMALLOC)
> -/* Align objs on cache lines */
> +/**
> + * define SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.
> + *
> + * Sufficiently large objects are aligned on cache line boundary. For object
> + * size smaller than a half of cache line size, the alignment is on the half of
> + * cache line size. In general, if object size is smaller than 1/2^n of cache
> + * line size, the alignment is adjusted to 1/2^n.

I'm kind of surprised that kernel-doc doesn't complain about that; it's
definitely not something that was ever envisioned, as far as I know.

Making it work properly probably requires somebody to wander into Perl
regex hell.  In the short term, if you want to get this text into the
rendered docs, the usual approach is to make a DOC: block out of it and
include it explicitly.

Thanks,

jon

Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Vlastimil Babka]

On 10/9/24 17:08, Jonathan Corbet wrote:
> Vlastimil Babka <vbabka@suse.cz> writes:
> 
>> We have many SLAB_ flags but many are used only internally, by kunit
>> tests or debugging subsystems cooperating with slab, or are set
>> according to slab_debug boot parameter.
>>
>> Create kerneldocs for the commonly used flags that may be passed to
>> kmem_cache_create(). SLAB_TYPESAFE_BY_RCU already had a detailed
>> description, so turn it to a kerneldoc. Add some details for
>> SLAB_ACCOUNT, SLAB_RECLAIM_ACCOUNT and SLAB_HWCACHE_ALIGN. Reference
>> them from the __kmem_cache_create_args() kerneldoc.
>>
>> Signed-off-by: Vlastimil Babka <vbabka@suse.cz>
>> ---
>> I plan to take this in the slab tree, but a question for Jon/linux-doc:
>>
>> I think I'm doing properly the "Object-like macro documentation" for
>> parameter-less macros from the doc-guide. Yet I can see in the htmldocs
>> things like "SLAB_TYPESAFE_BY_RCU ()" and "Parameters". Is there a bug
>> in the sphinx machinery? Thanks.
> 
> No, it's totally bug-free and any appearance to the contrary is entirely
> in your imagination :)

:)

> I don't think anybody has tried to do kerneldoc for macros that don't
> look like functions; it doesn't surprise me that it doesn't work right. 

I tried to follow the Documentation/doc-guide/kernel-doc.rst section
"Object-like macro documentation" here. Looks like it's been added only in
January this year via commit 91a3d6be99e63 by Randy and references commit
cbb4d3e6510b implementing the support for that from 2014 (was it even sphinx
based back then?)

The DRM_GEM_VRAM_PLANE_HELPER_FUNCS from the example there still exists
(include/drm/drm_gem_vram_helper.h) and seems to have the same rendering
issue here. Somewhat weirdly it doesn't use the "define" keyword that the
example does. DRM_GEM_VRAM_DRIVER in the same file does have the "define"
keyword and with the same result.

>>  include/linux/slab.h | 60 ++++++++++++++++++++++++++++++--------------
>>  mm/slab_common.c     | 14 ++++++++++-
>>  2 files changed, 54 insertions(+), 20 deletions(-)
>>
>> diff --git a/include/linux/slab.h b/include/linux/slab.h
>> index b35e2db7eb0e..49e9fb93e864 100644
>> --- a/include/linux/slab.h
>> +++ b/include/linux/slab.h
>> @@ -77,7 +77,17 @@ enum _slab_flag_bits {
>>  #define SLAB_POISON		__SLAB_FLAG_BIT(_SLAB_POISON)
>>  /* Indicate a kmalloc slab */
>>  #define SLAB_KMALLOC		__SLAB_FLAG_BIT(_SLAB_KMALLOC)
>> -/* Align objs on cache lines */
>> +/**
>> + * define SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.
>> + *
>> + * Sufficiently large objects are aligned on cache line boundary. For object
>> + * size smaller than a half of cache line size, the alignment is on the half of
>> + * cache line size. In general, if object size is smaller than 1/2^n of cache
>> + * line size, the alignment is adjusted to 1/2^n.
> 
> I'm kind of surprised that kernel-doc doesn't complain about that; it's
> definitely not something that was ever envisioned, as far as I know.
> 
> Making it work properly probably requires somebody to wander into Perl
> regex hell.  In the short term, if you want to get this text into the
> rendered docs, the usual approach is to make a DOC: block out of it and
> include it explicitly.

Thanks for the hints. I hope if we can agree that documenting the macros was
intended to be supported, doesn't break the build (there are users already)
and has only those minor rendering issues, it can be used?

> Thanks,
> 
> jon

Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Jonathan Corbet]

Vlastimil Babka <vbabka@suse.cz> writes:

> Thanks for the hints. I hope if we can agree that documenting the macros was
> intended to be supported, doesn't break the build (there are users already)
> and has only those minor rendering issues, it can be used?

I'd totally forgotten that this was supposed to work.

Yes it can be used... $WE just need to find a way to make it work
properly.

Every now and then I ponder rewriting kernel-doc in Rust, both to make
it more reasonable to modify and as a learning exercise.  But then I
come to my senses and go back to stuff that actually needs to get done.

jon

Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/9/24 9:49 AM, Jonathan Corbet wrote:
> Vlastimil Babka <vbabka@suse.cz> writes:
> 
>> Thanks for the hints. I hope if we can agree that documenting the macros was
>> intended to be supported, doesn't break the build (there are users already)
>> and has only those minor rendering issues, it can be used?
> 
> I'd totally forgotten that this was supposed to work.
> 
> Yes it can be used... $WE just need to find a way to make it work
> properly.

The code probably isn't expecting a macro on the right side. I'll take a look,
but no promises.

> 
> Every now and then I ponder rewriting kernel-doc in Rust, both to make
> it more reasonable to modify and as a learning exercise.  But then I
> come to my senses and go back to stuff that actually needs to get done.

That's a good way to lose helpers, although it might also gain you a few...

Yesh, I know, current is Perl.

-- 
~Randy

Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/9/24 3:02 PM, Randy Dunlap wrote:
> 
> 
> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>> Vlastimil Babka <vbabka@suse.cz> writes:
>>
>>> Thanks for the hints. I hope if we can agree that documenting the macros was
>>> intended to be supported, doesn't break the build (there are users already)
>>> and has only those minor rendering issues, it can be used?
>>
>> I'd totally forgotten that this was supposed to work.
>>
>> Yes it can be used... $WE just need to find a way to make it work
>> properly.
> 
> The code probably isn't expecting a macro on the right side. I'll take a look,
> but no promises.
> 
That would have been too simple.
I haven't found the problem yet. Ran out of time. Will continue on it tommorrow/Thursday.

>>
>> Every now and then I ponder rewriting kernel-doc in Rust, both to make
>> it more reasonable to modify and as a learning exercise.  But then I
>> come to my senses and go back to stuff that actually needs to get done.
> 
> That's a good way to lose helpers, although it might also gain you a few...
> 
> Yesh, I know, current is Perl.
> 

-- 
~Randy

[partial fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/9/24 10:06 PM, Randy Dunlap wrote:
> 
> 
> On 10/9/24 3:02 PM, Randy Dunlap wrote:
>>
>>
>> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>>> Vlastimil Babka <vbabka@suse.cz> writes:
>>>
>>>> Thanks for the hints. I hope if we can agree that documenting the macros was
>>>> intended to be supported, doesn't break the build (there are users already)
>>>> and has only those minor rendering issues, it can be used?
>>>
>>> I'd totally forgotten that this was supposed to work.
>>>
>>> Yes it can be used... $WE just need to find a way to make it work
>>> properly.
>>
>> The code probably isn't expecting a macro on the right side. I'll take a look,
>> but no promises.
>>
> That would have been too simple.
> I haven't found the problem yet. Ran out of time. Will continue on it tommorrow/Thursday.

The main problem is that output_function_rst() does not support object-like macros while
output_function_man() does.  There is still a bunch of sphinx_version handling that I know
nothing about, so the present output (after my trivial patch) leaves more to be done.

Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail
as they did at first.


This patch drops the trailing "()" for object-like macros in output_function_rst()
but there is still more to be done.

---------------------
From: Randy Dunlap <rdunlap@infradead.org>
Subject: [PATCH] kernel-doc: allow object-like macros in ReST output

output_function_rst() does not handle object-like macros. It presents
a trailing "()" while output_function_man() handles these macros
correctly.

Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Horia Geanta <horia.geanta@freescale.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Vlastimil Babka <vbabka@suse.cz>
---
 scripts/kernel-doc |    8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

--- linux-next-20241009.orig/scripts/kernel-doc
+++ linux-next-20241009/scripts/kernel-doc
@@ -822,10 +822,12 @@ sub output_function_rst(%) {
     my $oldprefix = $lineprefix;
 
     my $signature = "";
+    my $noret = $signature eq "";
+
     if ($args{'functiontype'} ne "") {
         $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
     } else {
-        $signature = $args{'function'} . " (";
+        $signature = $args{'function'} . " ";
     }
 
     my $count = 0;
@@ -844,7 +846,9 @@ sub output_function_rst(%) {
         }
     }
 
-    $signature .= ")";
+    if (!$noret) {
+    	$signature .= ")";
+    }
 
     if ($sphinx_major < 3) {
         if ($args{'typedef'}) {

Re: [partial fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/10/24 4:43 PM, Randy Dunlap wrote:
> 
> 
> On 10/9/24 10:06 PM, Randy Dunlap wrote:
>>
>>
>> On 10/9/24 3:02 PM, Randy Dunlap wrote:
>>>
>>>
>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>>>> Vlastimil Babka <vbabka@suse.cz> writes:
>>>>
>>>>> Thanks for the hints. I hope if we can agree that documenting the macros was
>>>>> intended to be supported, doesn't break the build (there are users already)
>>>>> and has only those minor rendering issues, it can be used?
>>>>
>>>> I'd totally forgotten that this was supposed to work.
>>>>
>>>> Yes it can be used... $WE just need to find a way to make it work
>>>> properly.
>>>
>>> The code probably isn't expecting a macro on the right side. I'll take a look,
>>> but no promises.
>>>
>> That would have been too simple.
>> I haven't found the problem yet. Ran out of time. Will continue on it tommorrow/Thursday.
> 
> The main problem is that output_function_rst() does not support object-like macros while
> output_function_man() does.  There is still a bunch of sphinx_version handling that I know
> nothing about, so the present output (after my trivial patch) leaves more to be done.
> 
> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail
> as they did at first.
> 
> 
> This patch drops the trailing "()" for object-like macros in output_function_rst()
> but there is still more to be done.
> 
> ---------------------
> From: Randy Dunlap <rdunlap@infradead.org>
> Subject: [PATCH] kernel-doc: allow object-like macros in ReST output
> 
> output_function_rst() does not handle object-like macros. It presents
> a trailing "()" while output_function_man() handles these macros
> correctly.
> 
> Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Horia Geanta <horia.geanta@freescale.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Vlastimil Babka <vbabka@suse.cz>
> ---
>  scripts/kernel-doc |    8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)
> 
> --- linux-next-20241009.orig/scripts/kernel-doc
> +++ linux-next-20241009/scripts/kernel-doc
> @@ -822,10 +822,12 @@ sub output_function_rst(%) {
>      my $oldprefix = $lineprefix;
>  
>      my $signature = "";
> +    my $noret = $signature eq "";

^^^ That line is in the wrong location. Still working on it....

> +
>      if ($args{'functiontype'} ne "") {
>          $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
>      } else {
> -        $signature = $args{'function'} . " (";
> +        $signature = $args{'function'} . " ";
>      }
>  
>      my $count = 0;
> @@ -844,7 +846,9 @@ sub output_function_rst(%) {
>          }
>      }
>  
> -    $signature .= ")";
> +    if (!$noret) {
> +    	$signature .= ")";
> +    }
>  
>      if ($sphinx_major < 3) {
>          if ($args{'typedef'}) {
> 
> 

-- 
~Randy

Re: [partial fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/10/24 4:54 PM, Randy Dunlap wrote:
> 
> 
> On 10/10/24 4:43 PM, Randy Dunlap wrote:
>>
>>
>> On 10/9/24 10:06 PM, Randy Dunlap wrote:
>>>
>>>
>>> On 10/9/24 3:02 PM, Randy Dunlap wrote:
>>>>
>>>>
>>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>>>>> Vlastimil Babka <vbabka@suse.cz> writes:
>>>>>
>>
>> The main problem is that output_function_rst() does not support object-like macros while
>> output_function_man() does.  There is still a bunch of sphinx_version handling that I know
>> nothing about, so the present output (after my trivial patch) leaves more to be done.
>>
>> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail
>> as they did at first.
>>
>>
>> This patch drops the trailing "()" for object-like macros in output_function_rst()
>> but there is still more to be done.
>>
>> ---------------------

This one mostly works for me although I don't care for the second line
here. I guess it has something to do with cross-referencing(?), but IDK.


"""
SLAB_TYPESAFE_BY_RCU
``SLAB_TYPESAFE_BY_RCU ``

WARNING READ THIS!

Description
"""

---
From: Randy Dunlap <rdunlap@infradead.org>
Subject: [PATCH] kernel-doc: allow object-like macros in ReST output

output_function_rst() does not handle object-like macros. It presents
a trailing "()" while output_function_man() handles these macros
correctly.

Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Horia Geanta <horia.geanta@freescale.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Vlastimil Babka <vbabka@suse.cz>
---
 scripts/kernel-doc |   13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

--- linux-next-20241009.orig/scripts/kernel-doc
+++ linux-next-20241009/scripts/kernel-doc
@@ -822,10 +822,13 @@ sub output_function_rst(%) {
     my $oldprefix = $lineprefix;
 
     my $signature = "";
+    my $noret = 0;
+
     if ($args{'functiontype'} ne "") {
         $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
     } else {
-        $signature = $args{'function'} . " (";
+        $signature = $args{'function'} . " ";
+    	$noret = 1;
     }
 
     my $count = 0;
@@ -844,7 +847,9 @@ sub output_function_rst(%) {
         }
     }
 
-    $signature .= ")";
+    if (!$noret) {
+    	$signature .= ")";
+    }
 
     if ($sphinx_major < 3) {
         if ($args{'typedef'}) {
@@ -890,7 +895,9 @@ sub output_function_rst(%) {
     #
     print ".. container:: kernelindent\n\n";
     $lineprefix = "  ";
-    print $lineprefix . "**Parameters**\n\n";
+	if (!$noret) {
+   		print $lineprefix . "**Parameters**\n\n";
+    }
     foreach $parameter (@{$args{'parameterlist'}}) {
         my $parameter_name = $parameter;
         $parameter_name =~ s/\[.*//;

Re: [partial fix] Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags

[Randy Dunlap]

On 10/10/24 8:07 PM, Randy Dunlap wrote:
> 
> 
> On 10/10/24 4:54 PM, Randy Dunlap wrote:
>>
>>
>> On 10/10/24 4:43 PM, Randy Dunlap wrote:
>>>
>>>
>>> On 10/9/24 10:06 PM, Randy Dunlap wrote:
>>>>
>>>>
>>>> On 10/9/24 3:02 PM, Randy Dunlap wrote:
>>>>>
>>>>>
>>>>> On 10/9/24 9:49 AM, Jonathan Corbet wrote:
>>>>>> Vlastimil Babka <vbabka@suse.cz> writes:
>>>>>>
>>>
>>> The main problem is that output_function_rst() does not support object-like macros while
>>> output_function_man() does.  There is still a bunch of sphinx_version handling that I know
>>> nothing about, so the present output (after my trivial patch) leaves more to be done.
>>>
>>> Well, the *main* problem is that the output is not consistent. Sometimes my tests don't fail
>>> as they did at first.
>>>
>>>
>>> This patch drops the trailing "()" for object-like macros in output_function_rst()
>>> but there is still more to be done.
>>>
>>> ---------------------
> 
> This one mostly works for me although I don't care for the second line
> here. I guess it has something to do with cross-referencing(?), but IDK.
> 

That seems to be normal but this patch now causes regressions for macros that
do have parameters. Back to searching...

> 
> """
> SLAB_TYPESAFE_BY_RCU
> ``SLAB_TYPESAFE_BY_RCU ``
> 
> WARNING READ THIS!
> 
> Description
> """
> 
> ---
> From: Randy Dunlap <rdunlap@infradead.org>
> Subject: [PATCH] kernel-doc: allow object-like macros in ReST output
> 
> output_function_rst() does not handle object-like macros. It presents
> a trailing "()" while output_function_man() handles these macros
> correctly.
> 
> Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Horia Geanta <horia.geanta@freescale.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Vlastimil Babka <vbabka@suse.cz>
> ---
>  scripts/kernel-doc |   13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
> 
> --- linux-next-20241009.orig/scripts/kernel-doc
> +++ linux-next-20241009/scripts/kernel-doc
> @@ -822,10 +822,13 @@ sub output_function_rst(%) {
>      my $oldprefix = $lineprefix;
>  
>      my $signature = "";
> +    my $noret = 0;
> +
>      if ($args{'functiontype'} ne "") {
>          $signature = $args{'functiontype'} . " " . $args{'function'} . " (";
>      } else {
> -        $signature = $args{'function'} . " (";
> +        $signature = $args{'function'} . " ";
> +    	$noret = 1;
>      }
>  
>      my $count = 0;
> @@ -844,7 +847,9 @@ sub output_function_rst(%) {
>          }
>      }
>  
> -    $signature .= ")";
> +    if (!$noret) {
> +    	$signature .= ")";
> +    }
>  
>      if ($sphinx_major < 3) {
>          if ($args{'typedef'}) {
> @@ -890,7 +895,9 @@ sub output_function_rst(%) {
>      #
>      print ".. container:: kernelindent\n\n";
>      $lineprefix = "  ";
> -    print $lineprefix . "**Parameters**\n\n";
> +	if (!$noret) {
> +   		print $lineprefix . "**Parameters**\n\n";
> +    }
>      foreach $parameter (@{$args{'parameterlist'}}) {
>          my $parameter_name = $parameter;
>          $parameter_name =~ s/\[.*//;
> 
> 

-- 
~Randy