[PATCH] bitops: improve power of 2 alignment function documentation

[PATCH] bitops: improve power of 2 alignment function documentation

[Mattias Rönnblom]

In the documentation, make clear
rte_align(32|64)prevpow2(<n>) -> <n>, provided <n> is a power of 2.

The original documentation stated the "previous" power of 2 would be
returned, potentially leaving the user to erroneously conclude that,
for example, rte_align32prevpow2(32) -> 16.

The rte_align(32|64)pow2(<n>) documentation, suffering from a similar
issue, is reworded in the same manner.

Fixes: 08f683174e94 ("eal: add functions for previous power of 2 alignment")
Cc: stable@dpdk.org

Signed-off-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
---
 lib/eal/include/rte_bitops.h | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/eal/include/rte_bitops.h b/lib/eal/include/rte_bitops.h
index b9a6af381b..2d1b9d281c 100644
--- a/lib/eal/include/rte_bitops.h
+++ b/lib/eal/include/rte_bitops.h
@@ -1320,7 +1320,7 @@ rte_is_power_of_2(uint32_t n)
  *   The integer value to align
  *
  * @return
- *   Input parameter aligned to the next power of 2
+ *   The smallest power of 2 which is greater than or equal to @c x.
  */
 static inline uint32_t
 rte_align32pow2(uint32_t x)
@@ -1338,7 +1338,7 @@ rte_align32pow2(uint32_t x)
  *   The integer value to align
  *
  * @return
- *   Input parameter aligned to the previous power of 2
+ *   The greatest power of 2 which is smaller than or equal to @c x.
  */
 static inline uint32_t
 rte_align32prevpow2(uint32_t x)
@@ -1355,7 +1355,7 @@ rte_align32prevpow2(uint32_t x)
  *   The 64b value to align
  *
  * @return
- *   Input parameter aligned to the next power of 2
+ *   The smallest power of 2 which is greater than or equal to @c v.
  */
 static inline uint64_t
 rte_align64pow2(uint64_t v)
@@ -1373,7 +1373,7 @@ rte_align64pow2(uint64_t v)
  *   The 64b value to align
  *
  * @return
- *   Input parameter aligned to the previous power of 2
+ *   The greatest power of 2 which is smaller than or equal to @c v.
  */
 static inline uint64_t
 rte_align64prevpow2(uint64_t v)
-- 
2.43.0

Re: [PATCH] bitops: improve power of 2 alignment function documentation

[Bruce Richardson]

On Tue, Jul 22, 2025 at 09:53:21AM +0200, Mattias Rönnblom wrote:
> In the documentation, make clear
> rte_align(32|64)prevpow2(<n>) -> <n>, provided <n> is a power of 2.
> 
> The original documentation stated the "previous" power of 2 would be
> returned, potentially leaving the user to erroneously conclude that,
> for example, rte_align32prevpow2(32) -> 16.
> 
> The rte_align(32|64)pow2(<n>) documentation, suffering from a similar
> issue, is reworded in the same manner.
> 
> Fixes: 08f683174e94 ("eal: add functions for previous power of 2 alignment")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
> ---
>  lib/eal/include/rte_bitops.h | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/lib/eal/include/rte_bitops.h b/lib/eal/include/rte_bitops.h
> index b9a6af381b..2d1b9d281c 100644
> --- a/lib/eal/include/rte_bitops.h
> +++ b/lib/eal/include/rte_bitops.h
> @@ -1320,7 +1320,7 @@ rte_is_power_of_2(uint32_t n)
>   *   The integer value to align
>   *
>   * @return
> - *   Input parameter aligned to the next power of 2
> + *   The smallest power of 2 which is greater than or equal to @c x.
>   */

Much clearer, thanks.

Acked-by: Bruce Richardson <bruce.richardson@intel.com>

RE: [PATCH] bitops: improve power of 2 alignment function documentation

[Morten Brørup]

> From: Bruce Richardson [mailto:bruce.richardson@intel.com]
> Sent: Tuesday, 22 July 2025 10.40
> 
> On Tue, Jul 22, 2025 at 09:53:21AM +0200, Mattias Rönnblom wrote:
> > In the documentation, make clear
> > rte_align(32|64)prevpow2(<n>) -> <n>, provided <n> is a power of 2.
> >
> > The original documentation stated the "previous" power of 2 would be
> > returned, potentially leaving the user to erroneously conclude that,
> > for example, rte_align32prevpow2(32) -> 16.
> >
> > The rte_align(32|64)pow2(<n>) documentation, suffering from a similar
> > issue, is reworded in the same manner.
> >
> > Fixes: 08f683174e94 ("eal: add functions for previous power of 2
> alignment")
> > Cc: stable@dpdk.org
> >
> > Signed-off-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>
> > ---
> >  lib/eal/include/rte_bitops.h | 8 ++++----
> >  1 file changed, 4 insertions(+), 4 deletions(-)
> >
> > diff --git a/lib/eal/include/rte_bitops.h
> b/lib/eal/include/rte_bitops.h
> > index b9a6af381b..2d1b9d281c 100644
> > --- a/lib/eal/include/rte_bitops.h
> > +++ b/lib/eal/include/rte_bitops.h
> > @@ -1320,7 +1320,7 @@ rte_is_power_of_2(uint32_t n)
> >   *   The integer value to align
> >   *
> >   * @return
> > - *   Input parameter aligned to the next power of 2
> > + *   The smallest power of 2 which is greater than or equal to @c x.
> >   */
> 
> Much clearer, thanks.
> 
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>

Acked-by: Morten Brørup <mb@smartsharesystems.com>