[U-Boot] [PATCH 2/3] image: move all function comments to header file

[Bryan Wu <cooloney@gmail.com>]

Several functions comments are C file with function definition, they
should be moved to header file with function declaration.

Also update genimg_get_kernel_addr() comments for CONFIG_FIT case.

Signed-off-by: Bryan Wu <pengw@nvidia.com>
---
 common/image.c  | 186 ---------------------------------------------------
 include/image.h | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 195 insertions(+), 194 deletions(-)

diff --git a/common/image.c b/common/image.c
index ea980cb..faccf88 100644
--- a/common/image.c
+++ b/common/image.c
@@ -181,19 +181,6 @@ int image_check_dcrc(const image_header_t *hdr)
 	return (dcrc == image_get_dcrc(hdr));
 }
 
-/**
- * image_multi_count - get component (sub-image) count
- * @hdr: pointer to the header of the multi component image
- *
- * image_multi_count() returns number of components in a multi
- * component image.
- *
- * Note: no checking of the image type is done, caller must pass
- * a valid multi component image.
- *
- * returns:
- *     number of components
- */
 ulong image_multi_count(const image_header_t *hdr)
 {
 	ulong i, count = 0;
@@ -210,23 +197,6 @@ ulong image_multi_count(const image_header_t *hdr)
 	return count;
 }
 
-/**
- * image_multi_getimg - get component data address and size
- * @hdr: pointer to the header of the multi component image
- * @idx: index of the requested component
- * @data: pointer to a ulong variable, will hold component data address
- * @len: pointer to a ulong variable, will hold component size
- *
- * image_multi_getimg() returns size and data address for the requested
- * component in a multi component image.
- *
- * Note: no checking of the image type is done, caller must pass
- * a valid multi component image.
- *
- * returns:
- *     data address and size of the component, if idx is valid
- *     0 in data and len, if idx is out of range
- */
 void image_multi_getimg(const image_header_t *hdr, ulong idx,
 			ulong *data, ulong *len)
 {
@@ -275,18 +245,6 @@ static void image_print_type(const image_header_t *hdr)
 	printf("%s %s %s (%s)\n", arch, os, type, comp);
 }
 
-/**
- * image_print_contents - prints out the contents of the legacy format image
- * @ptr: pointer to the legacy format image header
- * @p: pointer to prefix string
- *
- * image_print_contents() formats a multi line legacy image contents description.
- * The routine prints out all header fields followed by the size/offset data
- * for MULTI/SCRIPT images.
- *
- * returns:
- *     no returned results
- */
 void image_print_contents(const void *ptr)
 {
 	const image_header_t *hdr = (const image_header_t *)ptr;
@@ -524,20 +482,6 @@ void genimg_print_time(time_t timestamp)
 }
 #endif
 
-/**
- * get_table_entry_name - translate entry id to long name
- * @table: pointer to a translation table for entries of a specific type
- * @msg: message to be returned when translation fails
- * @id: entry id to be translated
- *
- * get_table_entry_name() will go over translation table trying to find
- * entry that matches given id. If matching entry is found, its long
- * name is returned to the caller.
- *
- * returns:
- *     long entry name if translation succeeds
- *     msg otherwise
- */
 char *get_table_entry_name(const table_entry_t *table, char *msg, int id)
 {
 	for (; table->id >= 0; ++table) {
@@ -573,20 +517,6 @@ const char *genimg_get_comp_name(uint8_t comp)
 					comp));
 }
 
-/**
- * get_table_entry_id - translate short entry name to id
- * @table: pointer to a translation table for entries of a specific type
- * @table_name: to be used in case of error
- * @name: entry short name to be translated
- *
- * get_table_entry_id() will go over translation table trying to find
- * entry that matches given short name. If matching entry is found,
- * its id returned to the caller.
- *
- * returns:
- *     entry id if translation succeeds
- *     -1 otherwise
- */
 int get_table_entry_id(const table_entry_t *table,
 		const char *table_name, const char *name)
 {
@@ -642,16 +572,6 @@ int genimg_get_comp_id(const char *name)
 }
 
 #ifndef USE_HOSTCC
-/**
- * genimg_get_kernel_addr - get the real kernel address
- * @img_addr: a string might contain real image address
- *
- * genimg_get_kernel_addr() get the real kernel start address from a string
- * which is normally the first argv of bootm/bootz
- *
- * returns:
- *     kernel start address
- */
 #if defined(CONFIG_FIT)
 ulong genimg_get_kernel_addr(char * const img_addr,
 			     const char **fit_uname_config,
@@ -686,20 +606,6 @@ ulong genimg_get_kernel_addr(char * const img_addr)
 	return kernel_addr;
 }
 
-/**
- * genimg_get_format - get image format type
- * @img_addr: image start address
- *
- * genimg_get_format() checks whether provided address points to a valid
- * legacy or FIT image.
- *
- * New uImage format and FDT blob are based on a libfdt. FDT blob
- * may be passed directly or embedded in a FIT image. In both situations
- * genimg_get_format() must be able to dectect libfdt header.
- *
- * returns:
- *     image format type or IMAGE_FORMAT_INVALID if no image is present
- */
 int genimg_get_format(const void *img_addr)
 {
 #if defined(CONFIG_IMAGE_FORMAT_LEGACY)
@@ -721,16 +627,6 @@ int genimg_get_format(const void *img_addr)
 	return IMAGE_FORMAT_INVALID;
 }
 
-/**
- * genimg_get_image - get image from special storage (if necessary)
- * @img_addr: image start address
- *
- * genimg_get_image() checks if provided image start adddress is located
- * in a dataflash storage. If so, image is moved to a system RAM memory.
- *
- * returns:
- *     image start address after possible relocation from special storage
- */
 ulong genimg_get_image(ulong img_addr)
 {
 	ulong ram_addr = img_addr;
@@ -796,17 +692,6 @@ ulong genimg_get_image(ulong img_addr)
 	return ram_addr;
 }
 
-/**
- * fit_has_config - check if there is a valid FIT configuration
- * @images: pointer to the bootm command headers structure
- *
- * fit_has_config() checks if there is a FIT configuration in use
- * (if FTI support is present).
- *
- * returns:
- *     0, no FIT support or no configuration found
- *     1, configuration found
- */
 int genimg_has_config(bootm_headers_t *images)
 {
 #if defined(CONFIG_FIT)
@@ -816,28 +701,6 @@ int genimg_has_config(bootm_headers_t *images)
 	return 0;
 }
 
-/**
- * boot_get_ramdisk - main ramdisk handling routine
- * @argc: command argument count
- * @argv: command argument list
- * @images: pointer to the bootm images structure
- * @arch: expected ramdisk architecture
- * @rd_start: pointer to a ulong variable, will hold ramdisk start address
- * @rd_end: pointer to a ulong variable, will hold ramdisk end
- *
- * boot_get_ramdisk() is responsible for finding a valid ramdisk image.
- * Curently supported are the following ramdisk sources:
- *      - multicomponent kernel/ramdisk image,
- *      - commandline provided address of decicated ramdisk image.
- *
- * returns:
- *     0, if ramdisk image was found and valid, or skiped
- *     rd_start and rd_end are set to ramdisk start/end addresses if
- *     ramdisk image is found and valid
- *
- *     1, if ramdisk image is found but corrupted, or invalid
- *     rd_start and rd_end are set to 0 if no ramdisk exists
- */
 int boot_get_ramdisk(int argc, char * const argv[], bootm_headers_t *images,
 		uint8_t arch, ulong *rd_start, ulong *rd_end)
 {
@@ -1020,27 +883,6 @@ int boot_get_ramdisk(int argc, char * const argv[], bootm_headers_t *images,
 }
 
 #ifdef CONFIG_SYS_BOOT_RAMDISK_HIGH
-/**
- * boot_ramdisk_high - relocate init ramdisk
- * @lmb: pointer to lmb handle, will be used for memory mgmt
- * @rd_data: ramdisk data start address
- * @rd_len: ramdisk data length
- * @initrd_start: pointer to a ulong variable, will hold final init ramdisk
- *      start address (after possible relocation)
- * @initrd_end: pointer to a ulong variable, will hold final init ramdisk
- *      end address (after possible relocation)
- *
- * boot_ramdisk_high() takes a relocation hint from "initrd_high" environment
- * variable and if requested ramdisk data is moved to a specified location.
- *
- * Initrd_start and initrd_end are set to final (after relocation) ramdisk
- * start/end addresses if ramdisk image start and len were provided,
- * otherwise set initrd_start and initrd_end set to zeros.
- *
- * returns:
- *      0 - success
- *     -1 - failure
- */
 int boot_ramdisk_high(struct lmb *lmb, ulong rd_data, ulong rd_len,
 		  ulong *initrd_start, ulong *initrd_end)
 {
@@ -1121,21 +963,6 @@ error:
 #endif /* CONFIG_SYS_BOOT_RAMDISK_HIGH */
 
 #ifdef CONFIG_SYS_BOOT_GET_CMDLINE
-/**
- * boot_get_cmdline - allocate and initialize kernel cmdline
- * @lmb: pointer to lmb handle, will be used for memory mgmt
- * @cmd_start: pointer to a ulong variable, will hold cmdline start
- * @cmd_end: pointer to a ulong variable, will hold cmdline end
- *
- * boot_get_cmdline() allocates space for kernel command line below
- * BOOTMAPSZ + getenv_bootm_low() address. If "bootargs" U-boot environemnt
- * variable is present its contents is copied to allocated kernel
- * command line.
- *
- * returns:
- *      0 - success
- *     -1 - failure
- */
 int boot_get_cmdline(struct lmb *lmb, ulong *cmd_start, ulong *cmd_end)
 {
 	char *cmdline;
@@ -1162,19 +989,6 @@ int boot_get_cmdline(struct lmb *lmb, ulong *cmd_start, ulong *cmd_end)
 #endif /* CONFIG_SYS_BOOT_GET_CMDLINE */
 
 #ifdef CONFIG_SYS_BOOT_GET_KBD
-/**
- * boot_get_kbd - allocate and initialize kernel copy of board info
- * @lmb: pointer to lmb handle, will be used for memory mgmt
- * @kbd: double pointer to board info data
- *
- * boot_get_kbd() allocates space for kernel copy of board info data below
- * BOOTMAPSZ + getenv_bootm_low() address and kernel board info is initialized
- * with the current u-boot board info data.
- *
- * returns:
- *      0 - success
- *     -1 - failure
- */
 int boot_get_kbd(struct lmb *lmb, bd_t **kbd)
 {
 	*kbd = (bd_t *)(ulong)lmb_alloc_base(lmb, sizeof(bd_t), 0xf,
diff --git a/include/image.h b/include/image.h
index a47c146..b95b4d5 100644
--- a/include/image.h
+++ b/include/image.h
@@ -376,17 +376,36 @@ typedef struct table_entry {
 	char	*lname;		/* long (output) name to print for messages */
 } table_entry_t;
 
-/*
- * get_table_entry_id() scans the translation table trying to find an
- * entry that matches the given short name. If a matching entry is
- * found, it's id is returned to the caller.
+/**
+ * get_table_entry_id - translate short entry name to id
+ * @table: pointer to a translation table for entries of a specific type
+ * @table_name: to be used in case of error
+ * @name: entry short name to be translated
+ *
+ * get_table_entry_id() will go over translation table trying to find
+ * entry that matches given short name. If matching entry is found,
+ * its id returned to the caller.
+ *
+ * returns:
+ *     entry id if translation succeeds
+ *     -1 otherwise
  */
 int get_table_entry_id(const table_entry_t *table,
 		const char *table_name, const char *name);
-/*
- * get_table_entry_name() scans the translation table trying to find
- * an entry that matches the given id. If a matching entry is found,
- * its long name is returned to the caller.
+
+/**
+ * get_table_entry_name - translate entry id to long name
+ * @table: pointer to a translation table for entries of a specific type
+ * @msg: message to be returned when translation fails
+ * @id: entry id to be translated
+ *
+ * get_table_entry_name() will go over translation table trying to find
+ * entry that matches given id. If matching entry is found, its long
+ * name is returned to the caller.
+ *
+ * returns:
+ *     long entry name if translation succeeds
+ *     msg otherwise
  */
 char *get_table_entry_name(const table_entry_t *table, char *msg, int id);
 
@@ -424,6 +443,20 @@ enum fit_load_op {
 #define IMAGE_FORMAT_FIT	0x02	/* new, libfdt based format */
 #define IMAGE_FORMAT_ANDROID	0x03	/* Android boot image */
 
+/**
+ * genimg_get_kernel_addr - get the real kernel address
+ * @img_addr: a string might contain real image address
+ * @fit_uname_config: double pointer to a char, will hold pointer to a
+ *                    configuration unit name
+ * @fit_uname_kernel: double pointer to a char, will hold pointer to a
+ *                    subimage name
+ *
+ * genimg_get_kernel_addr() get the real kernel start address from a string
+ * which is normally the first argv of bootm/bootz
+ *
+ * returns:
+ *     kernel start address
+ */
 #if defined(CONFIG_FIT)
 ulong genimg_get_kernel_addr(char * const img_addr,
 			     const char	**fit_uname_config,
@@ -431,10 +464,70 @@ ulong genimg_get_kernel_addr(char * const img_addr,
 #else
 ulong genimg_get_kernel_addr(char * const img_addr);
 #endif
+
+/**
+ * genimg_get_format - get image format type
+ * @img_addr: image start address
+ *
+ * genimg_get_format() checks whether provided address points to a valid
+ * legacy or FIT image.
+ *
+ * New uImage format and FDT blob are based on a libfdt. FDT blob
+ * may be passed directly or embedded in a FIT image. In both situations
+ * genimg_get_format() must be able to dectect libfdt header.
+ *
+ * returns:
+ *     image format type or IMAGE_FORMAT_INVALID if no image is present
+ */
 int genimg_get_format(const void *img_addr);
+
+/**
+ * fit_has_config - check if there is a valid FIT configuration
+ * @images: pointer to the bootm command headers structure
+ *
+ * fit_has_config() checks if there is a FIT configuration in use
+ * (if FTI support is present).
+ *
+ * returns:
+ *     0, no FIT support or no configuration found
+ *     1, configuration found
+ */
 int genimg_has_config(bootm_headers_t *images);
+
+/**
+ * genimg_get_image - get image from special storage (if necessary)
+ * @img_addr: image start address
+ *
+ * genimg_get_image() checks if provided image start adddress is located
+ * in a dataflash storage. If so, image is moved to a system RAM memory.
+ *
+ * returns:
+ *     image start address after possible relocation from special storage
+ */
 ulong genimg_get_image(ulong img_addr);
 
+/**
+ * boot_get_ramdisk - main ramdisk handling routine
+ * @argc: command argument count
+ * @argv: command argument list
+ * @images: pointer to the bootm images structure
+ * @arch: expected ramdisk architecture
+ * @rd_start: pointer to a ulong variable, will hold ramdisk start address
+ * @rd_end: pointer to a ulong variable, will hold ramdisk end
+ *
+ * boot_get_ramdisk() is responsible for finding a valid ramdisk image.
+ * Curently supported are the following ramdisk sources:
+ *      - multicomponent kernel/ramdisk image,
+ *      - commandline provided address of decicated ramdisk image.
+ *
+ * returns:
+ *     0, if ramdisk image was found and valid, or skiped
+ *     rd_start and rd_end are set to ramdisk start/end addresses if
+ *     ramdisk image is found and valid
+ *
+ *     1, if ramdisk image is found but corrupted, or invalid
+ *     rd_start and rd_end are set to 0 if no ramdisk exists
+ */
 int boot_get_ramdisk(int argc, char * const argv[], bootm_headers_t *images,
 		uint8_t arch, ulong *rd_start, ulong *rd_end);
 #endif
@@ -511,10 +604,61 @@ int boot_get_fdt(int flag, int argc, char * const argv[], uint8_t arch,
 void boot_fdt_add_mem_rsv_regions(struct lmb *lmb, void *fdt_blob);
 int boot_relocate_fdt(struct lmb *lmb, char **of_flat_tree, ulong *of_size);
 
+/**
+ * boot_ramdisk_high - relocate init ramdisk
+ * @lmb: pointer to lmb handle, will be used for memory mgmt
+ * @rd_data: ramdisk data start address
+ * @rd_len: ramdisk data length
+ * @initrd_start: pointer to a ulong variable, will hold final init ramdisk
+ *      start address (after possible relocation)
+ * @initrd_end: pointer to a ulong variable, will hold final init ramdisk
+ *      end address (after possible relocation)
+ *
+ * boot_ramdisk_high() takes a relocation hint from "initrd_high" environment
+ * variable and if requested ramdisk data is moved to a specified location.
+ *
+ * Initrd_start and initrd_end are set to final (after relocation) ramdisk
+ * start/end addresses if ramdisk image start and len were provided,
+ * otherwise set initrd_start and initrd_end set to zeros.
+ *
+ * returns:
+ *      0 - success
+ *     -1 - failure
+ */
 int boot_ramdisk_high(struct lmb *lmb, ulong rd_data, ulong rd_len,
 		  ulong *initrd_start, ulong *initrd_end);
+
+/**
+ * boot_get_cmdline - allocate and initialize kernel cmdline
+ * @lmb: pointer to lmb handle, will be used for memory mgmt
+ * @cmd_start: pointer to a ulong variable, will hold cmdline start
+ * @cmd_end: pointer to a ulong variable, will hold cmdline end
+ *
+ * boot_get_cmdline() allocates space for kernel command line below
+ * BOOTMAPSZ + getenv_bootm_low() address. If "bootargs" U-boot environemnt
+ * variable is present its contents is copied to allocated kernel
+ * command line.
+ *
+ * returns:
+ *      0 - success
+ *     -1 - failure
+ */
 int boot_get_cmdline(struct lmb *lmb, ulong *cmd_start, ulong *cmd_end);
+
 #ifdef CONFIG_SYS_BOOT_GET_KBD
+/**
+ * boot_get_kbd - allocate and initialize kernel copy of board info
+ * @lmb: pointer to lmb handle, will be used for memory mgmt
+ * @kbd: double pointer to board info data
+ *
+ * boot_get_kbd() allocates space for kernel copy of board info data below
+ * BOOTMAPSZ + getenv_bootm_low() address and kernel board info is initialized
+ * with the current u-boot board info data.
+ *
+ * returns:
+ *      0 - success
+ *     -1 - failure
+ */
 int boot_get_kbd(struct lmb *lmb, bd_t **kbd);
 #endif /* CONFIG_SYS_BOOT_GET_KBD */
 #endif /* !USE_HOSTCC */
@@ -639,10 +783,53 @@ static inline int image_check_os(const image_header_t *hdr, uint8_t os)
 	return (image_get_os(hdr) == os);
 }
 
+/**
+ * image_multi_count - get component (sub-image) count
+ * @hdr: pointer to the header of the multi component image
+ *
+ * image_multi_count() returns number of components in a multi
+ * component image.
+ *
+ * Note: no checking of the image type is done, caller must pass
+ * a valid multi component image.
+ *
+ * returns:
+ *     number of components
+ */
 ulong image_multi_count(const image_header_t *hdr);
+
+/**
+ * image_multi_getimg - get component data address and size
+ * @hdr: pointer to the header of the multi component image
+ * @idx: index of the requested component
+ * @data: pointer to a ulong variable, will hold component data address
+ * @len: pointer to a ulong variable, will hold component size
+ *
+ * image_multi_getimg() returns size and data address for the requested
+ * component in a multi component image.
+ *
+ * Note: no checking of the image type is done, caller must pass
+ * a valid multi component image.
+ *
+ * returns:
+ *     data address and size of the component, if idx is valid
+ *     0 in data and len, if idx is out of range
+ */
 void image_multi_getimg(const image_header_t *hdr, ulong idx,
 			ulong *data, ulong *len);
 
+/**
+ * image_print_contents - prints out the contents of the legacy format image
+ * @ptr: pointer to the legacy format image header
+ * @p: pointer to prefix string
+ *
+ * image_print_contents() formats a multi line legacy image contents description.
+ * The routine prints out all header fields followed by the size/offset data
+ * for MULTI/SCRIPT images.
+ *
+ * returns:
+ *     no returned results
+ */
 void image_print_contents(const void *hdr);
 
 #ifndef USE_HOSTCC
-- 
1.9.1