kernel.h: Documentation for roundup() vs round_up()
PATCH v2 1/1 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.
---
v2: fix whitespace (willy)
--- include/linux/kernel.h | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-)
include/linux/kernel.h +34 -1
@@ -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); \
Signature · 6 lines
2.17.1 -- Kees Cook Pixel Security
Quoted 5 lines · Kees Cook
Things like commit
3619dec5103d("dh key: fix rounding up KDF output length") expose the lack of explicit documentation forroundup()vsround_up(). At least we can try to document it better if anyone goes looking.
Quoted 7 lines
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.
Quoted 9 lines
+ *
+ * Rounds @x up to next multiple of @y (which must be a power of 2).
+ * To perform arbitrary rounding up, useroundup()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?
include/linux/kernel.h line 143
Quoted 11 lines
+ *
+ * Rounds @x up to next multiple of @y. If @y will always be a power
+ * of 2, consider using the fasterround_up().
+ *
+ * The `const' here prevents gcc-3.3 from calling__divdi3
+ */
#defineroundup(x, y)( \
{ \include/linux/kernel.h +0
-0const typeof (y) __y = y; \ (((x) + (__y -1 )) / __y) * __y; \ } \
Meow!
Signature · 8 lines
⢀⣴⠾⠻⢶⣦⠀ ⣾⠁⢰⠒⠀⣿⡁ 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... -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html