lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
Open Source and information security mailing list archives
| ||
|
Message-Id: <20220926194713.1806917-1-keescook@chromium.org> Date: Mon, 26 Sep 2022 12:47:13 -0700 From: Kees Cook <keescook@...omium.org> To: Jonathan Corbet <corbet@....net> Cc: Kees Cook <keescook@...omium.org>, Akira Yokosawa <akiyks@...il.com>, linux-doc@...r.kernel.org, linux-hardening@...r.kernel.org, linux-kernel@...r.kernel.org Subject: [PATCH] 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@....net> Cc: Akira Yokosawa <akiyks@...il.com> Cc: linux-doc@...r.kernel.org Cc: linux-hardening@...r.kernel.org Signed-off-by: Kees Cook <keescook@...omium.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
Powered by blists - more mailing lists