Skip to contentSkip to conversation

kasan: Fix kerneldoc comments in include/linux/kasan.h

PATCH In review Thomas Huth 2 participants 2 messages Aug 11 – Aug 14 KASAN

lore
Share & tools
lore
#0 lore raw

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
index bf233bde68c7e..479315d333e74 100644
@@ -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
#1 lore raw
Quoted 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_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.

Quoted 5 lines

---
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.

Quoted 63 lines
 include/linux/kasan.h | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)
include/linux/kasan.h +8 -6
index bf233bde68c7e..479315d333e74 100644
@@ -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