[PATCH v4 1/9] kernel: Document ALIGN macros

[Heinrich Schuchardt]

On 11/3/24 01:28, Simon Glass wrote:
> Add comments for these macros, so it is clear what they do.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
> (no changes since v1)
>
>   include/linux/kernel.h | 31 +++++++++++++++++++++++++++++++
>   1 file changed, 31 insertions(+)
>
> diff --git a/include/linux/kernel.h b/include/linux/kernel.h
> index 9467edd65ab..e5557257e6f 100644
> --- a/include/linux/kernel.h
> +++ b/include/linux/kernel.h
> @@ -35,9 +35,40 @@
>
>   #define REPEAT_BYTE(x)	((~0ul / 0xff) * (x))
>
> +/**
> + * Rounds a value up to a given alignment
> + *
> + * Note that @a must be a power of two
> + *
> + * Returns the lowest value >= @x which is a multiple of @a
> + *
> + * For example ALIGN(0x123, 8) == 0x128
> + */

Thanks for describing the macros.

We follow
https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation
for function-like macros:

/**
  * ALIGN() - Rounds a value up to a given alignment
  *
  * @x: value to be rounded up
  * @a: alignment factor. @a must be a power of two.
  * Return: lowest value >= @x which is a multiple of @a
  *
  * For example ALIGN(0x123, 8) == 0x128.
  */

Please, apply the same to all macros.

On the webpage there is also a rule for object like macros.

Best regards

Heinrich

>   #define ALIGN(x,a)		__ALIGN_MASK((x),(typeof(x))(a)-1)
> +
> +/**
> + * Rounds a down to a given alignment
> + *
> + * Note that @a must be a power of two
> + *
> + * Returns the highest value <= @x which is a multiple of @a
> + *
> + * For example ALIGN_DOWN(0x123, 8) == 0x120
> + * ALIGN_DOWN(0x120, 16) == 0x120
> + */
>   #define ALIGN_DOWN(x, a)	ALIGN((x) - ((a) - 1), (a))
> +
> +/**
> + * Rounds a value up to a given alignment-mask
> +*
> + * Note that @mask must be one less than a power of two
> + *
> + * Returns the lowest value >= @x where the bits set in @mask are 0
> + *
> + * For example __ALIGN_MASK(0x123, 0xf) == 0x130
> + */
>   #define __ALIGN_MASK(x,mask)	(((x)+(mask))&~(mask))
> +
>   #define PTR_ALIGN(p, a)		((typeof(p))ALIGN((unsigned long)(p), (a)))
>   #define IS_ALIGNED(x, a)		(((x) & ((typeof(x))(a) - 1)) == 0)
>