[U-Boot] [PATCH 2/4] tools/env: javadoc for fw_printenv, fw_getenv and fw_parse_script

[Simon Glass]

On 27 June 2016 at 16:06, Andreas Fenkart
<andreas.fenkart at digitalstrom.com> wrote:
> there are two groups of functions:
> - application ready tools: fw_setenv/fw_getenv/fw_parse_script
> these are used, when creating a single binary containing multiple
> tools (busybox like)
> - file access like: open/read/write/close
> above functions are implemented on top of these. applications
> can use those to modify several variables without creating a
> temporary batch script file
>
> Signed-off-by: Andreas Fenkart <andreas.fenkart at digitalstrom.com>
> ---
>  tools/env/fw_env.h | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 74 insertions(+), 1 deletion(-)

Great to see this, thank you.

Reviewed-by: Simon Glass <sjg at chromium.org>

Nit below

>
> diff --git a/tools/env/fw_env.h b/tools/env/fw_env.h
> index dac964d..8bf74f3 100644
> --- a/tools/env/fw_env.h
> +++ b/tools/env/fw_env.h
> @@ -67,12 +67,85 @@ struct env_opts {
>
>  int parse_aes_key(char *key, uint8_t *bin_key);
>
> +/**
> + * fw_printenv - print one or several environment variables

We normally add function brackets:

   fw_printenv() - print ...

> + *
> + * @argc  number of variables names to be printed, print all if 0
> + * @argv  array of variable names to be printed
> + * @value_only  do not repeat the variable name, only print the value,
> + *          only one variable allowed with this option, argc must be 1
> + * @opts  encryption key, configuration file, defaults are used if NULL

@returns

> + */
>  int fw_printenv(int argc, char *argv[], int value_only, struct env_opts *opts);
> -char *fw_getenv(char *name);
> +
> +/**
> + * fw_setenv - adds or removes one variable from the environment
> + *
> + * @argc  number of strings in argv, argv[0] is variable name,
> + *          argc==1 means erase variable, argc > 1 means add a variable
> + * @argv  argv[0] is variable name, argv[1..argc-1] are concatenated separated
> + *           by single blank and set as the new value of the variable
> + * @opts  how to retrieve environment from flash, defaults are used if NULL
> + * @ret   EROFS if variable must not be changed (ethaddr, serial#)

@returns

> + */
>  int fw_setenv(int argc, char *argv[], struct env_opts *opts);
> +
> +/**
> + * fw_parse_script - add/remove multiple variables with a batch script
> + *
> + * @fname  batch script file name
> + * @opts  encryption key, configuration file, defaults are used if NULL

@returns

(please do for all)

> + *
> + * Script Syntax:
> + *   key [[space]+ value]
> + *   lines starting with '#' treated as comment
> + *
> + *   A variable without value will be deleted. Any number of spaces are allowed
> + *   between key and value. The value starts with the first non-space character
> + *   and ends with newline. No comments allowed on these lines.  Spaces inside
> + *   the value are preserved verbatim.
> + *
> + * Script Example:"
> + *   netdev         eth0
> + *   kernel_addr    400000
> + *   foo            spaces           are copied verbatim
> + *   # delete variable bar
> + *   bar\n"
> + */
>  int fw_parse_script(char *fname, struct env_opts *opts);
> +
> +
> +/**
> + * fw_env_open - read enviroment from flash and cache it in RAM
> + *
> + * @opts  encryption key, configuration file, defaults are used if NULL
> + */
>  int fw_env_open(struct env_opts *opts);
> +
> +/**
> + * fw_getenv - lookup variable in RAM cache
> + *
> + * @name  variable to be searched
> + * @ret   NULL if not found
> + */
> +char *fw_getenv(char *name);
> +
> +/**
> + * fw_env_write - set/clear a single variable in the RAM cache
> + *
> + * This is called in sequence to update the environment in RAM without updating
> + * the copy in flash after each set
> + *
> + * @name  variable
> + * @value delete variable if NULL, otherwise create or overwrite the variable
> + */
>  int fw_env_write(char *name, char *value);
> +
> +/**
> + * fw_env_close - writes environment from RAM back to flash
> + *
> + * @opts  encryption key, configuration file, defaults are used if NULL
> + */
>  int fw_env_close(struct env_opts *opts);
>
>  unsigned long crc32(unsigned long, const unsigned char *, unsigned);
> --
> 2.8.1
>
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> http://lists.denx.de/mailman/listinfo/u-boot