| Message ID | 20240526180856.1124470-1-devarsht@ti.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Add V4L2 M2M Driver for E5010 JPEG Encoder | expand |
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.
diff --git a/include/linux/math.h b/include/linux/math.h index dd4152711de7..e2cc3769ed0e 100644 --- a/include/linux/math.h +++ b/include/linux/math.h @@ -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
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(+)