[v9,06/10] math.h: Add macros for rounding to closest value
Commit Message
Add below rounding related macros:
round_closest_up(x, y) : Rounds x to closest multiple of y where y is a
power of 2, with a preference to round up in case two nearest values are
possible.
round_closest_down(x, y) : Rounds x to closest multiple of y where y is a
power of 2, with a preference to round down in case two nearest values are
possible.
roundclosest(x, y) : Rounds x to closest multiple of y, this macro should
generally be used only when y is not multiple of 2 as otherwise
round_closest* macros should be used which are much faster.
Examples:
* round_closest_up(17, 4) = 16
* round_closest_up(15, 4) = 16
* round_closest_up(14, 4) = 16
* round_closest_down(17, 4) = 16
* round_closest_down(15, 4) = 16
* round_closest_down(14, 4) = 12
* roundclosest(21, 5) = 20
* roundclosest(19, 5) = 20
* roundclosest(17, 5) = 15
Signed-off-by: Devarsh Thakkar <devarsht@ti.com>
---
NOTE: This patch is inspired from the Mentor Graphics IPU driver [1]
which uses similar macro locally and which is updated in further patch
in the series to use this generic macro instead along with other drivers
having similar requirements.
[1]:
https://elixir.bootlin.com/linux/v6.8.9/source/drivers/gpu/ipu-v3/ipu-image-convert.c#L480
V9:
- No change
V8:
- Add new macro to round to nearest value for non-multiple of 2
- Update commit message as suggested:
V1->V6 (No change, patch introduced in V7)
---
include/linux/math.h | 65 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
Comments
On Sun, May 26, 2024 at 11:38:56PM +0530, Devarsh Thakkar wrote:
> Add below rounding related macros:
>
> round_closest_up(x, y) : Rounds x to closest multiple of y where y is a
> power of 2, with a preference to round up in case two nearest values are
> possible.
>
> round_closest_down(x, y) : Rounds x to closest multiple of y where y is a
> power of 2, with a preference to round down in case two nearest values are
> possible.
>
> roundclosest(x, y) : Rounds x to closest multiple of y, this macro should
> generally be used only when y is not multiple of 2 as otherwise
> round_closest* macros should be used which are much faster.
>
> Examples:
> * round_closest_up(17, 4) = 16
> * round_closest_up(15, 4) = 16
> * round_closest_up(14, 4) = 16
> * round_closest_down(17, 4) = 16
> * round_closest_down(15, 4) = 16
> * round_closest_down(14, 4) = 12
> * roundclosest(21, 5) = 20
> * roundclosest(19, 5) = 20
> * roundclosest(17, 5) = 15
...
> +/**
> + * round_closest_up - round closest to be multiple of specified value (which is
> + * power of 2) with preference to rounding up
> +
Not that big deal, but missing '*' here. Personally I would not even put
a blank line between Summary and Field Descriptions.
> + * @x: the value to round
> + * @y: multiple to round closest to (must be a power of 2)
> + *
> + * Rounds @x to closest multiple of @y (which must be a power of 2).
> + * The value can be either rounded up or rounded down depending upon rounded
> + * value's closeness to the specified value. If there are two closest possible
> + * values, i.e. the difference between the specified value and it's rounded up
> + * and rounded down values is same then preference is given to rounded up
> + * value.
> + *
> + * To perform arbitrary rounding to closest value (not multiple of 2), use
> + * roundclosest().
> + *
> + * Examples :
What is this suppose to be rendered to?
> + * round_closest_up(17, 4) = 16
> + * round_closest_up(15, 4) = 16
> + * round_closest_up(14, 4) = 16
Btw, is kernel-doc validator happy about all kernel docs you added?
> + */
Hi Andy,
Thanks for the review.
On 28/05/24 02:02, Andy Shevchenko wrote:
> On Sun, May 26, 2024 at 11:38:56PM +0530, Devarsh Thakkar wrote:
...
>> +/**
>> + * round_closest_up - round closest to be multiple of specified value (which is
>> + * power of 2) with preference to rounding up
>> +
>
> Not that big deal, but missing '*' here. Personally I would not even put
> a blank line between Summary and Field Descriptions.
>
My bad. Yes I would remove the blank line here. This is picked up as warning
from kernel-doc too.
>> + * @x: the value to round
>> + * @y: multiple to round closest to (must be a power of 2)
>> + *
>> + * Rounds @x to closest multiple of @y (which must be a power of 2).
>> + * The value can be either rounded up or rounded down depending upon rounded
>> + * value's closeness to the specified value. If there are two closest possible
>> + * values, i.e. the difference between the specified value and it's rounded up
>> + * and rounded down values is same then preference is given to rounded up
>> + * value.
>> + *
>> + * To perform arbitrary rounding to closest value (not multiple of 2), use
>> + * roundclosest().
>> + *
>> + * Examples :
>
> What is this suppose to be rendered to?
>
The file math.h is not rendered as part of kernel-doc right now. I can put
this under Documentation/core-api/kernel-api.rst perhaps I can create a new
section as below:
Rounding, absolute diff and 32bit division macros
-------------------------------------------------
under the section:
CRC and Math Functions in Linux
===============================
is that okay ?
>> + * round_closest_up(17, 4) = 16
>> + * round_closest_up(15, 4) = 16
>> + * round_closest_up(14, 4) = 16
>
> Btw, is kernel-doc validator happy about all kernel docs you added?
>
Yes, except the aforementioned blank line.
Regards
Devarsh
On Tue, May 28, 2024 at 04:02:30PM +0530, Devarsh Thakkar wrote:
> On 28/05/24 02:02, Andy Shevchenko wrote:
> > On Sun, May 26, 2024 at 11:38:56PM +0530, Devarsh Thakkar wrote:
...
> >> +/**
> >> + * round_closest_up - round closest to be multiple of specified value (which is
> >> + * power of 2) with preference to rounding up
> >> +
> >
> > Not that big deal, but missing '*' here. Personally I would not even put
> > a blank line between Summary and Field Descriptions.
>
> My bad. Yes I would remove the blank line here. This is picked up as warning
> from kernel-doc too.
>
> >> + * @x: the value to round
> >> + * @y: multiple to round closest to (must be a power of 2)
> >> + *
> >> + * Rounds @x to closest multiple of @y (which must be a power of 2).
> >> + * The value can be either rounded up or rounded down depending upon rounded
> >> + * value's closeness to the specified value. If there are two closest possible
> >> + * values, i.e. the difference between the specified value and it's rounded up
> >> + * and rounded down values is same then preference is given to rounded up
> >> + * value.
> >> + *
> >> + * To perform arbitrary rounding to closest value (not multiple of 2), use
> >> + * roundclosest().
> >> + *
> >> + * Examples :
> >
> > What is this suppose to be rendered to?
>
> The file math.h is not rendered as part of kernel-doc right now. I can put
> this under Documentation/core-api/kernel-api.rst perhaps I can create a new
> section as below:
>
> Rounding, absolute diff and 32bit division macros
> -------------------------------------------------
>
> under the section:
> CRC and Math Functions in Linux
>
> ===============================
>
> is that okay ?
This is up to you, but what I meant is that you always can render manually
yourself. And I was asking about the result you got when you tried (and you
did, right?) to render to man, html, and pdf.
> >> + * round_closest_up(17, 4) = 16
> >> + * round_closest_up(15, 4) = 16
> >> + * round_closest_up(14, 4) = 16
> >
> > Btw, is kernel-doc validator happy about all kernel docs you added?
>
> Yes, except the aforementioned blank line.
@@ -34,6 +34,54 @@
*/
#define round_down(x, y) ((x) & ~__round_mask(x, y))
+/**
+ * round_closest_up - round closest to be multiple of specified value (which is
+ * power of 2) with preference to rounding up
+
+ * @x: the value to round
+ * @y: multiple to round closest to (must be a power of 2)
+ *
+ * Rounds @x to closest multiple of @y (which must be a power of 2).
+ * The value can be either rounded up or rounded down depending upon rounded
+ * value's closeness to the specified value. If there are two closest possible
+ * values, i.e. the difference between the specified value and it's rounded up
+ * and rounded down values is same then preference is given to rounded up
+ * value.
+ *
+ * To perform arbitrary rounding to closest value (not multiple of 2), use
+ * roundclosest().
+ *
+ * Examples :
+ * round_closest_up(17, 4) = 16
+ * round_closest_up(15, 4) = 16
+ * round_closest_up(14, 4) = 16
+ */
+#define round_closest_up(x, y) round_down((x) + (y) / 2, (y))
+
+/**
+ * round_closest_down - round closest to be multiple of specified value (which
+ * is power of 2) with preference to rounding down
+ *
+ * @x: the value to round
+ * @y: multiple to round closest to (must be a power of 2)
+ *
+ * Rounds @x to closest multiple of @y (which must be a power of 2).
+ * The value can be either rounded up or rounded down depending upon rounded
+ * value's closeness to the specified value. If there are two closest possible
+ * values, i.e. the difference between the specified value and it's rounded up
+ * and rounded down values is same then preference is given to rounded up
+ * value.
+ *
+ * To perform arbitrary rounding to closest value (not multiple of 2), use
+ * roundclosest().
+ *
+ * Examples :
+ * round_closest_down(17, 4) = 16
+ * round_closest_down(15, 4) = 16
+ * round_closest_down(14, 4) = 12
+ */
+#define round_closest_down(x, y) round_up((x) - (y) / 2, (y))
+
#define DIV_ROUND_UP __KERNEL_DIV_ROUND_UP
#define DIV_ROUND_DOWN_ULL(ll, d) \
@@ -77,6 +125,23 @@
} \
)
+/**
+ * roundclosest - round to nearest multiple
+ * @x: the value to round
+ * @y: multiple to round nearest to
+ *
+ * Rounds @x to nearest multiple of @y.
+ * The rounded value can be greater than or less than @x depending
+ * upon it's nearness to @x. If @y will always be a power of 2, consider
+ * using the faster round_closest_up() or round_closest_down().
+ *
+ * Examples :
+ * roundclosest(21, 5) = 20
+ * roundclosest(19, 5) = 20
+ * roundclosest(17, 5) = 15
+ */
+#define roundclosest(x, y) rounddown((x) + (y) / 2, (y))
+
/*
* Divide positive or negative dividend by positive or negative divisor
* and round to closest integer. Result is undefined for negative