[PATCH] kasan: Fix kerneldoc comments in include/linux/kasan.h

[PATCH] kasan: Fix kerneldoc comments in include/linux/kasan.h

[Thomas Huth]

From: Thomas Huth <thuth@redhat.com>

To fix warnings when generating kerneldocs for this header, let's
make sure that all parameters are properly documented. And while we're
at it, provide a better name for the struct kmem_cache parameter than
the simple "s".

Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 Should we maybe also include this file from Documentation/dev-tools/kasan.rst
 with a  ".. kernel-doc:: include/linux/kasan.h" statement?
 
 include/linux/kasan.h | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/include/linux/kasan.h b/include/linux/kasan.h
index bf233bde68c7e..479315d333e74 100644
--- a/include/linux/kasan.h
+++ b/include/linux/kasan.h
@@ -183,6 +183,7 @@ bool __kasan_slab_pre_free(struct kmem_cache *s, void *object,
 			unsigned long ip);
 /**
  * kasan_slab_pre_free - Check whether freeing a slab object is safe.
+ * @kcache: Cache the object belongs to.
  * @object: Object to be freed.
  *
  * This function checks whether freeing the given object is safe. It may
@@ -192,11 +193,11 @@ bool __kasan_slab_pre_free(struct kmem_cache *s, void *object,
  *
  * @Return true if freeing the object is unsafe; false otherwise.
  */
-static __always_inline bool kasan_slab_pre_free(struct kmem_cache *s,
+static __always_inline bool kasan_slab_pre_free(struct kmem_cache *kcache,
 						void *object)
 {
 	if (kasan_enabled())
-		return __kasan_slab_pre_free(s, object, _RET_IP_);
+		return __kasan_slab_pre_free(kcache, object, _RET_IP_);
 	return false;
 }
 
@@ -204,9 +205,11 @@ bool __kasan_slab_free(struct kmem_cache *s, void *object, bool init,
 		       bool still_accessible, bool no_quarantine);
 /**
  * kasan_slab_free - Poison, initialize, and quarantine a slab object.
+ * @kcache: Cache the object belongs to.
  * @object: Object to be freed.
  * @init: Whether to initialize the object.
  * @still_accessible: Whether the object contents are still accessible.
+ * @no_quarantine: Whether to take ownership of the object to quarantine it.
  *
  * This function informs that a slab object has been freed and is not
  * supposed to be accessed anymore, except when @still_accessible is set
@@ -226,14 +229,14 @@ bool __kasan_slab_free(struct kmem_cache *s, void *object, bool init,
  *
  * @Return true if KASAN took ownership of the object; false otherwise.
  */
-static __always_inline bool kasan_slab_free(struct kmem_cache *s,
+static __always_inline bool kasan_slab_free(struct kmem_cache *kcache,
 					    void *object, bool init,
 					    bool still_accessible,
 					    bool no_quarantine)
 {
 	if (kasan_enabled())
-		return __kasan_slab_free(s, object, init, still_accessible,
-					 no_quarantine);
+		return __kasan_slab_free(kcache, object, init,
+					 still_accessible, no_quarantine);
 	return false;
 }
 
-- 
2.55.0

Re: [PATCH] kasan: Fix kerneldoc comments in include/linux/kasan.h

[Andrey Konovalov]

On Tue, Aug 11, 2026 at 10:17 AM Thomas Huth <thuth@redhat.com> wrote:
>
> From: Thomas Huth <thuth@redhat.com>
>

Hi Thomas!

> To fix warnings when generating kerneldocs for this header, let's
> make sure that all parameters are properly documented. And while we're
> at it, provide a better name for the struct kmem_cache parameter than
> the simple "s".

I'm not sure if the rename is consistent with the rest of the code:
calling the cache "s" is a convention used throughout the SLUB code.
And looks like include/linux/slab.h also uses "s". But I think this is
up to the mm maintainers.

If we were to rename, I think it's better to use "cache" rather than
"kcache" to be consistent with mm/kasan/*.c.

>
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  Should we maybe also include this file from Documentation/dev-tools/kasan.rst
>  with a  ".. kernel-doc:: include/linux/kasan.h" statement?

I'd rather just reference the file name somewhere in the Overview
section. I never found those long tables of functions in the doc files
to be useful.



>
>  include/linux/kasan.h | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/include/linux/kasan.h b/include/linux/kasan.h
> index bf233bde68c7e..479315d333e74 100644
> --- a/include/linux/kasan.h
> +++ b/include/linux/kasan.h
> @@ -183,6 +183,7 @@ bool __kasan_slab_pre_free(struct kmem_cache *s, void *object,
>                         unsigned long ip);
>  /**
>   * kasan_slab_pre_free - Check whether freeing a slab object is safe.
> + * @kcache: Cache the object belongs to.
>   * @object: Object to be freed.
>   *
>   * This function checks whether freeing the given object is safe. It may
> @@ -192,11 +193,11 @@ bool __kasan_slab_pre_free(struct kmem_cache *s, void *object,
>   *
>   * @Return true if freeing the object is unsafe; false otherwise.
>   */
> -static __always_inline bool kasan_slab_pre_free(struct kmem_cache *s,
> +static __always_inline bool kasan_slab_pre_free(struct kmem_cache *kcache,
>                                                 void *object)
>  {
>         if (kasan_enabled())
> -               return __kasan_slab_pre_free(s, object, _RET_IP_);
> +               return __kasan_slab_pre_free(kcache, object, _RET_IP_);
>         return false;
>  }
>
> @@ -204,9 +205,11 @@ bool __kasan_slab_free(struct kmem_cache *s, void *object, bool init,
>                        bool still_accessible, bool no_quarantine);
>  /**
>   * kasan_slab_free - Poison, initialize, and quarantine a slab object.
> + * @kcache: Cache the object belongs to.
>   * @object: Object to be freed.
>   * @init: Whether to initialize the object.
>   * @still_accessible: Whether the object contents are still accessible.
> + * @no_quarantine: Whether to take ownership of the object to quarantine it.
>   *
>   * This function informs that a slab object has been freed and is not
>   * supposed to be accessed anymore, except when @still_accessible is set
> @@ -226,14 +229,14 @@ bool __kasan_slab_free(struct kmem_cache *s, void *object, bool init,
>   *
>   * @Return true if KASAN took ownership of the object; false otherwise.
>   */
> -static __always_inline bool kasan_slab_free(struct kmem_cache *s,
> +static __always_inline bool kasan_slab_free(struct kmem_cache *kcache,
>                                             void *object, bool init,
>                                             bool still_accessible,
>                                             bool no_quarantine)
>  {
>         if (kasan_enabled())
> -               return __kasan_slab_free(s, object, init, still_accessible,
> -                                        no_quarantine);
> +               return __kasan_slab_free(kcache, object, init,
> +                                        still_accessible, no_quarantine);
>         return false;
>  }
>
> --
> 2.55.0
>