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@xxxxxxxxxx> wrote:
>
> From: Thomas Huth <thuth@xxxxxxxxxx>
>

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@xxxxxxxxxx>
> ---
>  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
>