Commit 31970608 authored by Kees Cook's avatar Kees Cook
Browse files

overflow: Fix kern-doc markup for functions 



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: linux-doc@vger.kernel.org
Cc: linux-hardening@vger.kernel.org
Reviewed-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Signed-off-by: default avatarKees Cook <keescook@chromium.org>
parent 9abf2313

Documentation/core-api/kernel-api.rst

+6 −0
Original line number Diff line number Diff line
@@ -118,6 +118,12 @@ Text Searching 
CRC and Math Functions in Linux

===============================



Arithmetic Overflow Checking

----------------------------



.. kernel-doc:: include/linux/overflow.h

   :internal:



CRC Functions

-------------

Documentation/driver-api/basics.rst

+0 −3
Original line number Diff line number Diff line
@@ -107,9 +107,6 @@ Kernel utility functions 
.. kernel-doc:: kernel/panic.c

   :export:



.. kernel-doc:: include/linux/overflow.h

   :internal:



Device Resource Management

--------------------------

include/linux/overflow.h

+16 −22
Original line number Diff line number Diff line
@@ -51,8 +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

 * @d: pointer to store sum
@@ -66,8 +66,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

 * @d: pointer to store difference
@@ -81,8 +81,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

 * @d: pointer to store product
@@ -96,23 +96,24 @@ 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

 * @d: Pointer to where to store the result

 *

 * 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(({		\
@@ -129,7 +130,6 @@ static inline bool __must_check __must_check_overflow(bool overflow) 


/**

 * size_mul() - Calculate size_t multiplication with saturation at SIZE_MAX

 *

 * @factor1: first factor

 * @factor2: second factor

 *
@@ -149,7 +149,6 @@ 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

 *

 * @addend1: first addend

 * @addend2: second addend

 *
@@ -169,7 +168,6 @@ 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

 *

 * @minuend: value to subtract from

 * @subtrahend: value to subtract from @minuend

 *
@@ -192,7 +190,6 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend) 


/**

 * array_size() - Calculate size of 2-dimensional array.

 *

 * @a: dimension one

 * @b: dimension two

 *
@@ -205,7 +202,6 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend) 


/**

 * array3_size() - Calculate size of 3-dimensional array.

 *

 * @a: dimension one

 * @b: dimension two

 * @c: dimension three
@@ -220,7 +216,6 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend) 
/**

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

 * @count: Number of elements in the array.
@@ -237,7 +232,6 @@ static inline size_t __must_check size_sub(size_t minuend, size_t subtrahend) 


/**

 * struct_size() - Calculate size of structure with trailing flexible array.

 *

 * @p: Pointer to the structure.

 * @member: Name of the array member.

 * @count: Number of elements in the array.