[U-Boot] [PATCH 2/3] image: move all function comments to header file
Bryan Wu
cooloney at gmail.com
Fri Aug 15 22:55:27 CEST 2014
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 at 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
More information about the U-Boot
mailing list