2018-07-03 02:19:10

by Kees Cook

Subject: [PATCH v2] kernel.h: Documentation for roundup() vs round_up()

Things like commit 3619dec5103d ("dh key: fix rounding up KDF output
length") expose the lack of explicit documentation for roundup() vs
round_up(). At least we can try to document it better if anyone goes
looking.

Signed-off-by: Kees Cook <[email protected]>
---
v2: fix whitespace (willy)
---
include/linux/kernel.h | 35 ++++++++++++++++++++++++++++++++++-
1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/include/linux/kernel.h b/include/linux/kernel.h
index 941dc0a5a877..dce6ab779a83 100644
--- a/include/linux/kernel.h
+++ b/include/linux/kernel.h
@@ -85,7 +85,23 @@
* arguments just once each.
*/
#define __round_mask(x, y) ((__typeof__(x))((y)-1))
+/**
+ * round_up - round up to next specified power of 2
+ * @x: the value to round
+ * @y: multiple to round up to (must be a power of 2)
+ *
+ * Rounds @x up to next multiple of @y (which must be a power of 2).
+ * To perform arbitrary rounding up, use roundup() below.
+ */
#define round_up(x, y) ((((x)-1) | __round_mask(x, y))+1)
+/**
+ * round_down - round down to next specified power of 2
+ * @x: the value to round
+ * @y: multiple to round down to (must be a power of 2)
+ *
+ * Rounds @x down to next multiple of @y (which must be a power of 2).
+ * To perform arbitrary rounding down, use rounddown() below.
+ */
#define round_down(x, y) ((x) & ~__round_mask(x, y))

/**
@@ -110,13 +126,30 @@
# define DIV_ROUND_UP_SECTOR_T(ll,d) DIV_ROUND_UP(ll,d)
#endif

-/* The `const' in roundup() prevents gcc-3.3 from calling __divdi3 */
+/**
+ * roundup - round up to the next specified multiple
+ * @x: the value to up
+ * @y: multiple to round up to (must be a power of 2)
+ *
+ * Rounds @x up to next multiple of @y. If @y will always be a power
+ * of 2, consider using the faster round_up().
+ *
+ * The `const' here prevents gcc-3.3 from calling __divdi3
+ */
#define roundup(x, y) ( \
{ \
const typeof(y) __y = y; \
(((x) + (__y - 1)) / __y) * __y; \
} \
)
+/**
+ * rounddown - round down to next specified multiple
+ * @x: the value to round
+ * @y: multiple to round down to
+ *
+ * Rounds @x down to next multiple of @y. If @y will always be a power
+ * of 2, consider using the faster round_down().
+ */
#define rounddown(x, y) ( \
{ \
typeof(x) __x = (x); \
--
2.17.1


--
Kees Cook
Pixel Security

2018-07-03 02:30:19

by Adam Borowski

Subject: Re: [PATCH v2] kernel.h: Documentation for roundup() vs round_up()

On Mon, Jul 02, 2018 at 07:16:54PM -0700, Kees Cook wrote:
> Things like commit 3619dec5103d ("dh key: fix rounding up KDF output
> length") expose the lack of explicit documentation for roundup() vs
> round_up(). At least we can try to document it better if anyone goes
> looking.
>
> Signed-off-by: Kees Cook <[email protected]>
> ---

> +/**
> + * round_up - round up to next specified power of 2
> + * @x: the value to round
> + * @y: multiple to round up to (must be a power of 2)
^^^^^^^^^^^^^^^^^^^^
This matches the description -- so far, good.
> + *
> + * Rounds @x up to next multiple of @y (which must be a power of 2).
> + * To perform arbitrary rounding up, use roundup() below.
> + */

> +/**
> + * roundup - round up to the next specified multiple
> + * @x: the value to up
> + * @y: multiple to round up to (must be a power of 2)
^^^^^^^^^^^^^^^^^^^^
But isn't this supposed to differ from the above?
> + *
> + * Rounds @x up to next multiple of @y. If @y will always be a power
> + * of 2, consider using the faster round_up().
> + *
> + * The `const' here prevents gcc-3.3 from calling __divdi3
> + */
> #define roundup(x, y) ( \
> { \
> const typeof(y) __y = y; \
> (((x) + (__y - 1)) / __y) * __y; \
> } \


Meow!
--
⢀⣴⠾⠻⢶⣦⠀
⣾⠁⢰⠒⠀⣿⡁ Imagine there are bandits in your house, your kid is bleeding out,
⢿⡄⠘⠷⠚⠋⠀ the house is on fire, and seven big-ass trumpets are playing in the
⠈⠳⣄⠀⠀⠀⠀ sky. Your cat demands food. The priority should be obvious...