kasan: Fix kerneldoc comments in include/linux/kasan.h
PATCH 1/1 kasan: Fix kerneldoc comments in include/linux/kasan.h
From: Thomas Huth <[email protected]>
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".
---
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(-)
include/linux/kasan.h +8 -5
@@ -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; }
Signature · 1 line
2.55.0
Andrey Konovalov
reviewerQuoted 3 lines · Thomas Huth
From: Thomas Huth <[email protected]>
Hi Thomas!
Quoted 4 lines
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_cacheparameter 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.
Quoted 5 lines
Signed-off-by Thomas Huth <[email protected]>---
Should we maybe also include this file fromDocumentation/dev-tools/kasan.rstwith 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.
Quoted 63 lines
include/linux/kasan.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-)include/linux/kasan.h +8
-6@@ -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