Re: [PATCH 22/45] image: Move comment for fit_conf_find_compat()

[Heinrich Schuchardt <xypron.glpk@gmx.de>]

On 9/25/22 17:02, Simon Glass wrote:
> Move this comment to the header file, where the APIs should be defined.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
>   boot/image-fit.c | 43 -------------------------------------------
>   include/image.h  | 43 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 43 insertions(+), 43 deletions(-)
>
> diff --git a/boot/image-fit.c b/boot/image-fit.c
> index a7acd762272..94074515258 100644
> --- a/boot/image-fit.c
> +++ b/boot/image-fit.c
> @@ -1687,49 +1687,6 @@ int fit_check_format(const void *fit, ulong size)
>   	return 0;
>   }
>
> -/**
> - * fit_conf_find_compat
> - * @fit: pointer to the FIT format image header
> - * @fdt: pointer to the device tree to compare against
> - *
> - * fit_conf_find_compat() attempts to find the configuration whose fdt is the
> - * most compatible with the passed in device tree.
> - *
> - * Example:
> - *
> - * / o image-tree
> - *   |-o images
> - *   | |-o fdt-1
> - *   | |-o fdt-2
> - *   |
> - *   |-o configurations
> - *     |-o config-1
> - *     | |-fdt = fdt-1
> - *     |
> - *     |-o config-2
> - *       |-fdt = fdt-2
> - *
> - * / o U-Boot fdt
> - *   |-compatible = "foo,bar", "bim,bam"
> - *
> - * / o kernel fdt1
> - *   |-compatible = "foo,bar",
> - *
> - * / o kernel fdt2
> - *   |-compatible = "bim,bam", "baz,biz"
> - *
> - * Configuration 1 would be picked because the first string in U-Boot's
> - * compatible list, "foo,bar", matches a compatible string in the root of fdt1.
> - * "bim,bam" in fdt2 matches the second string which isn't as good as fdt1.
> - *
> - * As an optimization, the compatible property from the FDT's root node can be
> - * copied into the configuration node in the FIT image. This is required to
> - * match configurations with compressed FDTs.
> - *
> - * returns:
> - *     offset to the configuration to use if one was found
> - *     -1 otherwise
> - */
>   int fit_conf_find_compat(const void *fit, const void *fdt >   {
>   	int ndepth = 0;
> diff --git a/include/image.h b/include/image.h
> index b336cfa0842..ca1c6c5b3c2 100644
> --- a/include/image.h
> +++ b/include/image.h
> @@ -1136,6 +1136,49 @@ int fit_image_check_comp(const void *fit, int noffset, uint8_t comp);
>    */
>   int fit_check_format(const void *fit, ulong size);
>
> +/**
> + * fit_conf_find_compat

Please, adjust to style defined in
https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation:

fit_conf_find_compat() - Brief description

> + * @fit: pointer to the FIT format image header
> + * @fdt: pointer to the device tree to compare against
> + *
> + * fit_conf_find_compat() attempts to find the configuration whose fdt is the
> + * most compatible with the passed in device tree.
> + *
> + * Example:
> + *
> + * / o image-tree
> + *   |-o images
> + *   | |-o fdt-1
> + *   | |-o fdt-2
> + *   |
> + *   |-o configurations
> + *     |-o config-1
> + *     | |-fdt = fdt-1
> + *     |
> + *     |-o config-2
> + *       |-fdt = fdt-2
> + *
> + * / o U-Boot fdt
> + *   |-compatible = "foo,bar", "bim,bam"
> + *
> + * / o kernel fdt1
> + *   |-compatible = "foo,bar",
> + *
> + * / o kernel fdt2
> + *   |-compatible = "bim,bam", "baz,biz"

Preformatted text should be indented and preceded by ::.

> + *
> + * Configuration 1 would be picked because the first string in U-Boot's
> + * compatible list, "foo,bar", matches a compatible string in the root of fdt1.
> + * "bim,bam" in fdt2 matches the second string which isn't as good as fdt1.
> + *
> + * As an optimization, the compatible property from the FDT's root node can be
> + * copied into the configuration node in the FIT image. This is required to
> + * match configurations with compressed FDTs.
> + *
> + * returns:

Return:

Best regards

Heinrich

> + *     offset to the configuration to use if one was found
> + *     -1 otherwise
> + */
>   int fit_conf_find_compat(const void *fit, const void *fdt);
>
>   /**