diff mbox series

[v10,06/11] math.h: Add macros for rounding to closest value

Message ID 20240530171225.2749312-1-devarsht@ti.com (mailing list archive)
State New, archived
Headers show
Series Add V4L2 M2M Driver for E5010 JPEG Encoder | expand

Commit Message

Devarsh Thakkar May 30, 2024, 5:12 p.m. UTC
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

V10:
- Update example comment to fix formatting issues as observed with html docs

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 | 72 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

Comments

Andy Shevchenko May 30, 2024, 7:19 p.m. UTC | #1
On Thu, May 30, 2024 at 10:42:25PM +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

...

> + * Examples :

It's inconsistent with the other one below.

> + * 	round_closest_up(17, 4) = 16
> + *
> + * 	round_closest_up(15, 4) = 16
> + *
> + * 	round_closest_up(14, 4) = 16

The three have TABs/spaces mixture.

I believe you wanted:

 * Examples::
 * * round_closest_up(17, 4) = 16
 * * round_closest_up(15, 4) = 16
 * * round_closest_up(14, 4) = 16

...

> + * Examples:
> + *
> + * 	round_closest_down(17, 4) = 16
> + *
> + * 	round_closest_down(15, 4) = 16
> + *
> + * 	round_closest_down(14, 4) = 12

As per above

...

> + * Examples :
> + *
> + * 	roundclosest(21, 5) = 20
> + *
> + * 	roundclosest(19, 5) = 20
> + *
> + * 	roundclosest(17, 5) = 15

As per above.
Devarsh Thakkar May 31, 2024, 8:36 a.m. UTC | #2
Hi Andy,

Thanks for the review.

On 31/05/24 00:49, Andy Shevchenko wrote:
> On Thu, May 30, 2024 at 10:42:25PM +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
> 
> ...
> 
>> + * Examples :
> 
> It's inconsistent with the other one below.
> 
>> + * 	round_closest_up(17, 4) = 16
>> + *
>> + * 	round_closest_up(15, 4) = 16
>> + *
>> + * 	round_closest_up(14, 4) = 16
> 
> The three have TABs/spaces mixture.
> 
> I believe you wanted:
> 
>  * Examples::
>  * * round_closest_up(17, 4) = 16
>  * * round_closest_up(15, 4) = 16
>  * * round_closest_up(14, 4) = 16
> 

I initially referred the style from this link [1] but probably missed to
remove extra space from my patch.

But what you suggested looks better, I will go with what you suggested.

[1]  https://elixir.bootlin.com/linux/v6.9/source/include/linux/int_log.h#L22

Regards
Devarsh
diff mbox series

Patch

diff --git a/include/linux/math.h b/include/linux/math.h
index dd4152711de7..1f6177191b66 100644
--- a/include/linux/math.h
+++ b/include/linux/math.h
@@ -34,6 +34,58 @@ 
  */
 #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 +129,26 @@ 
 }							\
 )
 
+/**
+ * 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