[PATCH] slab: recognize @GFP parameter as optional in kernel-doc

[PATCH] slab: recognize @GFP parameter as optional in kernel-doc

[Randy Dunlap]

Since the @GFP parameter in kmalloc_obj() etc. is now optional, change
the kernel-doc to indicate that it is optional. This avoids kernel-doc
warnings:

WARNING: include/linux/slab.h:1101 Excess function parameter 'GFP' description in 'kmalloc_obj'
WARNING: include/linux/slab.h:1113 Excess function parameter 'GFP' description in 'kmalloc_objs'
WARNING: include/linux/slab.h:1128 Excess function parameter 'GFP' description in 'kmalloc_flex'

Fixes: e19e1b480ac7 ("add default_gfp() helper macro and use it in the new *alloc_obj() helpers")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Vlastimil Babka <vbabka@kernel.org>
Cc: Harry Yoo <harry@kernel.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: linux-mm@kvack.org
Cc: stable@vger.kernel.org

 include/linux/slab.h |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

--- linux-next-20260615.orig/include/linux/slab.h
+++ linux-next-20260615/include/linux/slab.h
@@ -1094,7 +1094,7 @@ void *kmalloc_nolock(size_t size, gfp_t
 /**
  * kmalloc_obj - Allocate a single instance of the given type
  * @VAR_OR_TYPE: Variable or type to allocate.
- * @GFP: GFP flags for the allocation.
+ * @...: GFP flags for the allocation.
  *
  * Returns: newly allocated pointer to a @VAR_OR_TYPE on success, or NULL
  * on failure.
@@ -1106,7 +1106,7 @@ void *kmalloc_nolock(size_t size, gfp_t
  * kmalloc_objs - Allocate an array of the given type
  * @VAR_OR_TYPE: Variable or type to allocate an array of.
  * @COUNT: How many elements in the array.
- * @GFP: GFP flags for the allocation.
+ * @...: GFP flags for the allocation.
  *
  * Returns: newly allocated pointer to array of @VAR_OR_TYPE on success,
  * or NULL on failure.
@@ -1119,7 +1119,7 @@ void *kmalloc_nolock(size_t size, gfp_t
  * @VAR_OR_TYPE: Variable or type to allocate (with its flex array).
  * @FAM: The name of the flexible array member of the structure.
  * @COUNT: How many flexible array member elements are desired.
- * @GFP: GFP flags for the allocation.
+ * @...: GFP flags for the allocation.
  *
  * Returns: newly allocated pointer to @VAR_OR_TYPE on success, NULL on
  * failure. If @FAM has been annotated with __counted_by(), the allocation

Re: [PATCH] slab: recognize @GFP parameter as optional in kernel-doc

[Harry Yoo]

[-- Attachment #1.1: Type: text/plain, Size: 2666 bytes --]

[+Cc Kees and Jonathan]

On 6/17/26 4:39 AM, Randy Dunlap wrote:
> Since the @GFP parameter in kmalloc_obj() etc. is now optional, change
> the kernel-doc to indicate that it is optional. This avoids kernel-doc
> warnings:
> 
> WARNING: include/linux/slab.h:1101 Excess function parameter 'GFP' description in 'kmalloc_obj'
> WARNING: include/linux/slab.h:1113 Excess function parameter 'GFP' description in 'kmalloc_objs'
> WARNING: include/linux/slab.h:1128 Excess function parameter 'GFP' description in 'kmalloc_flex'
> 
> Fixes: e19e1b480ac7 ("add default_gfp() helper macro and use it in the new *alloc_obj() helpers")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---

I think there is no better way to specify an optional parameter, so:
Acked-by: Harry Yoo (Oracle) <harry@kernel.org>

By the way, the doc should probably say that it is GFP_KERNEL when it is
not specified?

> Cc: Vlastimil Babka <vbabka@kernel.org>
> Cc: Harry Yoo <harry@kernel.org>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: linux-mm@kvack.org
> Cc: stable@vger.kernel.org
> 
>  include/linux/slab.h |    6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> --- linux-next-20260615.orig/include/linux/slab.h
> +++ linux-next-20260615/include/linux/slab.h
> @@ -1094,7 +1094,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>  /**
>   * kmalloc_obj - Allocate a single instance of the given type
>   * @VAR_OR_TYPE: Variable or type to allocate.
> - * @GFP: GFP flags for the allocation.
> + * @...: GFP flags for the allocation.
>   *
>   * Returns: newly allocated pointer to a @VAR_OR_TYPE on success, or NULL
>   * on failure.
> @@ -1106,7 +1106,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>   * kmalloc_objs - Allocate an array of the given type
>   * @VAR_OR_TYPE: Variable or type to allocate an array of.
>   * @COUNT: How many elements in the array.
> - * @GFP: GFP flags for the allocation.
> + * @...: GFP flags for the allocation.
>   *
>   * Returns: newly allocated pointer to array of @VAR_OR_TYPE on success,
>   * or NULL on failure.
> @@ -1119,7 +1119,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>   * @VAR_OR_TYPE: Variable or type to allocate (with its flex array).
>   * @FAM: The name of the flexible array member of the structure.
>   * @COUNT: How many flexible array member elements are desired.
> - * @GFP: GFP flags for the allocation.
> + * @...: GFP flags for the allocation.
>   *
>   * Returns: newly allocated pointer to @VAR_OR_TYPE on success, NULL on
>   * failure. If @FAM has been annotated with __counted_by(), the allocation

-- 
Cheers,
Harry / Hyeonggon

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] slab: recognize @GFP parameter as optional in kernel-doc

[Randy Dunlap]

On 6/16/26 8:25 PM, Harry Yoo wrote:
> [+Cc Kees and Jonathan]
> 
> On 6/17/26 4:39 AM, Randy Dunlap wrote:
>> Since the @GFP parameter in kmalloc_obj() etc. is now optional, change
>> the kernel-doc to indicate that it is optional. This avoids kernel-doc
>> warnings:
>>
>> WARNING: include/linux/slab.h:1101 Excess function parameter 'GFP' description in 'kmalloc_obj'
>> WARNING: include/linux/slab.h:1113 Excess function parameter 'GFP' description in 'kmalloc_objs'
>> WARNING: include/linux/slab.h:1128 Excess function parameter 'GFP' description in 'kmalloc_flex'
>>
>> Fixes: e19e1b480ac7 ("add default_gfp() helper macro and use it in the new *alloc_obj() helpers")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
> 
> I think there is no better way to specify an optional parameter, so:
> Acked-by: Harry Yoo (Oracle) <harry@kernel.org>
> 
> By the way, the doc should probably say that it is GFP_KERNEL when it is
> not specified?

How about (in general):

 * @...: optional GFP flags for the allocation (GFP_KERNEL when not specified)

?
>> Cc: Vlastimil Babka <vbabka@kernel.org>
>> Cc: Harry Yoo <harry@kernel.org>
>> Cc: Andrew Morton <akpm@linux-foundation.org>
>> Cc: linux-mm@kvack.org
>> Cc: stable@vger.kernel.org
>>
>>  include/linux/slab.h |    6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> --- linux-next-20260615.orig/include/linux/slab.h
>> +++ linux-next-20260615/include/linux/slab.h
>> @@ -1094,7 +1094,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>>  /**
>>   * kmalloc_obj - Allocate a single instance of the given type
>>   * @VAR_OR_TYPE: Variable or type to allocate.
>> - * @GFP: GFP flags for the allocation.
>> + * @...: GFP flags for the allocation.
>>   *
>>   * Returns: newly allocated pointer to a @VAR_OR_TYPE on success, or NULL
>>   * on failure.
>> @@ -1106,7 +1106,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>>   * kmalloc_objs - Allocate an array of the given type
>>   * @VAR_OR_TYPE: Variable or type to allocate an array of.
>>   * @COUNT: How many elements in the array.
>> - * @GFP: GFP flags for the allocation.
>> + * @...: GFP flags for the allocation.
>>   *
>>   * Returns: newly allocated pointer to array of @VAR_OR_TYPE on success,
>>   * or NULL on failure.
>> @@ -1119,7 +1119,7 @@ void *kmalloc_nolock(size_t size, gfp_t
>>   * @VAR_OR_TYPE: Variable or type to allocate (with its flex array).
>>   * @FAM: The name of the flexible array member of the structure.
>>   * @COUNT: How many flexible array member elements are desired.
>> - * @GFP: GFP flags for the allocation.
>> + * @...: GFP flags for the allocation.
>>   *
>>   * Returns: newly allocated pointer to @VAR_OR_TYPE on success, NULL on
>>   * failure. If @FAM has been annotated with __counted_by(), the allocation
> 

-- 
~Randy

Re: [PATCH] slab: recognize @GFP parameter as optional in kernel-doc

[Harry Yoo]

[-- Attachment #1.1: Type: text/plain, Size: 1223 bytes --]



On 6/17/26 1:38 PM, Randy Dunlap wrote:
> On 6/16/26 8:25 PM, Harry Yoo wrote:
>> [+Cc Kees and Jonathan]
>>
>> On 6/17/26 4:39 AM, Randy Dunlap wrote:
>>> Since the @GFP parameter in kmalloc_obj() etc. is now optional, change
>>> the kernel-doc to indicate that it is optional. This avoids kernel-doc
>>> warnings:
>>>
>>> WARNING: include/linux/slab.h:1101 Excess function parameter 'GFP' description in 'kmalloc_obj'
>>> WARNING: include/linux/slab.h:1113 Excess function parameter 'GFP' description in 'kmalloc_objs'
>>> WARNING: include/linux/slab.h:1128 Excess function parameter 'GFP' description in 'kmalloc_flex'
>>>
>>> Fixes: e19e1b480ac7 ("add default_gfp() helper macro and use it in the new *alloc_obj() helpers")
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> ---
>>
>> I think there is no better way to specify an optional parameter, so:
>> Acked-by: Harry Yoo (Oracle) <harry@kernel.org>
>>
>> By the way, the doc should probably say that it is GFP_KERNEL when it is
>> not specified?
> 
> How about (in general):
> 
>  * @...: optional GFP flags for the allocation (GFP_KERNEL when not specified)
> 
> ?

Looks good to me!

-- 
Cheers,
Harry / Hyeonggon

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 228 bytes --]