Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Kees Cook <keescook@chromium.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Kees Cook <keescook@chromium.org>,
        Akira Yokosawa <akiyks@gmail.com>, linux-doc@vger.kernel.org,
        linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH] overflow: Fix kern-doc markup for functions
Date:   Mon, 26 Sep 2022 12:47:13 -0700
Message-Id: <20220926194713.1806917-1-keescook@chromium.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Fix the kern-doc markings for several of the overflow helpers and move
their location into the core kernel API documentation, where it belongs
(it's not driver-specific).

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-hardening@vger.kernel.org
Signed-off-by: Kees Cook <keescook@chromium.org>
---
 Documentation/core-api/kernel-api.rst |  6 ++++
 Documentation/driver-api/basics.rst   |  3 --
 include/linux/overflow.h              | 43 +++++++++++++++------------
 3 files changed, 30 insertions(+), 22 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 20569f26dde1..0d0c4f87057c 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -121,6 +121,12 @@ Text Searching
 CRC and Math Functions in Linux
 ===============================
 
+Arithmetic Overflow Checking
+----------------------------
+
+.. kernel-doc:: include/linux/overflow.h
+   :internal:
+
 CRC Functions
 -------------
 
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 3e2dae954898..4b4d8e28d3be 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -107,9 +107,6 @@ Kernel utility functions
 .. kernel-doc:: kernel/panic.c
    :export:
 
-.. kernel-doc:: include/linux/overflow.h
-   :internal:
-
 Device Resource Management
 --------------------------
 
diff --git a/include/linux/overflow.h b/include/linux/overflow.h
index 58eb34aa2af9..4b5b3ec91233 100644
--- a/include/linux/overflow.h
+++ b/include/linux/overflow.h
@@ -51,7 +51,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
 	return unlikely(overflow);
 }
 
-/** check_add_overflow() - Calculate addition with overflow checking
+/**
+ * check_add_overflow - Calculate addition with overflow checking
  *
  * @a: first addend
  * @b: second addend
@@ -66,7 +67,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
 #define check_add_overflow(a, b, d)	\
 	__must_check_overflow(__builtin_add_overflow(a, b, d))
 
-/** check_sub_overflow() - Calculate subtraction with overflow checking
+/**
+ * check_sub_overflow - Calculate subtraction with overflow checking
  *
  * @a: minuend; value to subtract from
  * @b: subtrahend; value to subtract from @a
@@ -81,7 +83,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
 #define check_sub_overflow(a, b, d)	\
 	__must_check_overflow(__builtin_sub_overflow(a, b, d))
 
-/** check_mul_overflow() - Calculate multiplication with overflow checking
+/**
+ * check_mul_overflow - Calculate multiplication with overflow checking
  *
  * @a: first factor
  * @b: second factor
@@ -96,7 +99,8 @@ static inline bool __must_check __must_check_overflow(bool overflow)
 #define check_mul_overflow(a, b, d)	\
 	__must_check_overflow(__builtin_mul_overflow(a, b, d))
 
-/** check_shl_overflow() - Calculate a left-shifted value and check overflow
+/**
+ * check_shl_overflow - Calculate a left-shifted value and check overflow
  *
  * @a: Value to be shifted
  * @s: How many bits left to shift
@@ -104,15 +108,16 @@ static inline bool __must_check __must_check_overflow(bool overflow)
  *
  * Computes *@d = (@a << @s)
  *
- * Returns true if '*d' cannot hold the result or when 'a << s' doesn't
+ * Returns true if '*@d' cannot hold the result or when '@a << @s' doesn't
  * make sense. Example conditions:
- * - 'a << s' causes bits to be lost when stored in *d.
- * - 's' is garbage (e.g. negative) or so large that the result of
- *   'a << s' is guaranteed to be 0.
- * - 'a' is negative.
- * - 'a << s' sets the sign bit, if any, in '*d'.
  *
- * '*d' will hold the results of the attempted shift, but is not
+ * - '@a << @s' causes bits to be lost when stored in *@d.
+ * - '@s' is garbage (e.g. negative) or so large that the result of
+ *   '@a << @s' is guaranteed to be 0.
+ * - '@a' is negative.
+ * - '@a << @s' sets the sign bit, if any, in '*@d'.
+ *
+ * '*@d' will hold the results of the attempted shift, but is not
  * considered "safe for use" if true is returned.
  */
 #define check_shl_overflow(a, s, d) __must_check_overflow(({		\
@@ -176,7 +181,7 @@ static inline bool __must_check __must_check_overflow(bool overflow)
 			      __same_type(n, T))
 
 /**
- * size_mul() - Calculate size_t multiplication with saturation at SIZE_MAX
+ * size_mul - Calculate size_t multiplication with saturation at SIZE_MAX
  *
  * @factor1: first factor
  * @factor2: second factor
@@ -196,7 +201,7 @@ static inline size_t __must_check size_mul(size_t factor1, size_t factor2)
 }
 
 /**
- * size_add() - Calculate size_t addition with saturation at SIZE_MAX
+ * size_add - Calculate size_t addition with saturation at SIZE_MAX
  *
  * @addend1: first addend
  * @addend2: second addend
@@ -216,7 +221,7 @@ static inline size_t __must_check size_add(size_t addend1, size_t addend2)
 }
 
 /**
- * size_sub() - Calculate size_t subtraction with saturation at SIZE_MAX
+ * size_sub - Calculate size_t subtraction with saturation at SIZE_MAX
  *
  * @minuend: value to subtract from
  * @subtrahend: value to subtract from @minuend
@@ -239,7 +244,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
 }
 
 /**
- * array_size() - Calculate size of 2-dimensional array.
+ * array_size - Calculate size of 2-dimensional array.
  *
  * @a: dimension one
  * @b: dimension two
@@ -252,7 +257,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
 #define array_size(a, b)	size_mul(a, b)
 
 /**
- * array3_size() - Calculate size of 3-dimensional array.
+ * array3_size - Calculate size of 3-dimensional array.
  *
  * @a: dimension one
  * @b: dimension two
@@ -266,8 +271,8 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
 #define array3_size(a, b, c)	size_mul(size_mul(a, b), c)
 
 /**
- * flex_array_size() - Calculate size of a flexible array member
- *                     within an enclosing structure.
+ * flex_array_size - Calculate size of a flexible array member
+ *                   within an enclosing structure.
  *
  * @p: Pointer to the structure.
  * @member: Name of the flexible array member.
@@ -284,7 +289,7 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend)
 		size_mul(count, sizeof(*(p)->member) + __must_be_array((p)->member)))
 
 /**
- * struct_size() - Calculate size of structure with trailing flexible array.
+ * struct_size - Calculate size of structure with trailing flexible array.
  *
  * @p: Pointer to the structure.
  * @member: Name of the array member.
-- 
2.34.1