summaryrefslogtreecommitdiff
path: root/tools
diff options
context:
space:
mode:
authorAndreas Fenkart <andreas.fenkart@digitalstrom.com>2016-07-16 17:06:13 +0200
committerTom Rini <trini@konsulko.com>2016-07-22 14:46:21 -0400
commitfd4e3280e50983aa4d646f2c8fc93b38cc1dddf9 (patch)
treebb8b6bd8cdcc2aaac3fdfd08b59b35d28e97fa00 /tools
parent473c0abe6290aaf1471ce8129a67e3c2fbfc2597 (diff)
tools/env: kernel-doc for fw_printenv, fw_getenv and fw_parse_script
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 tested with "./scripts/kernel-doc -html -v tools/env/fw_env.h" Reviewed-by: Simon Glass <sjg@chromium.org> Signed-off-by: Andreas Fenkart <andreas.fenkart@digitalstrom.com>
Diffstat (limited to 'tools')
-rw-r--r--tools/env/fw_env.c2
-rw-r--r--tools/env/fw_env.h115
2 files changed, 115 insertions, 2 deletions
diff --git a/tools/env/fw_env.c b/tools/env/fw_env.c
index be338a5ba90..1dad1ce5476 100644
--- a/tools/env/fw_env.c
+++ b/tools/env/fw_env.c
@@ -484,7 +484,7 @@ int fw_setenv(int argc, char *argv[], struct env_opts *opts)
valc = argc - 1;
if (env_flags_validate_env_set_params(name, valv, valc) < 0)
- return 1;
+ return -1;
len = 0;
for (i = 0; i < valc; ++i) {
diff --git a/tools/env/fw_env.h b/tools/env/fw_env.h
index dac964d933f..436eca9ddc1 100644
--- a/tools/env/fw_env.h
+++ b/tools/env/fw_env.h
@@ -67,12 +67,125 @@ struct env_opts {
int parse_aes_key(char *key, uint8_t *bin_key);
+/**
+ * fw_printenv() - print one or several environment variables
+ *
+ * @argc: number of variables names to be printed, prints all if 0
+ * @argv: array of variable names to be printed, if argc != 0
+ * @value_only: do not repeat the variable name, print the bare value,
+ * only one variable allowed with this option, argc must be 1
+ * @opts: encryption key, configuration file, defaults are used if NULL
+ *
+ * Description:
+ * Uses fw_env_open, fw_getenv
+ *
+ * Return:
+ * 0 on success, -1 on failure (modifies errno)
+ */
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 to 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
+ *
+ * Description:
+ * Uses fw_env_open, fw_env_write, fw_env_close
+ *
+ * Return:
+ * 0 on success, -1 on failure (modifies errno)
+ *
+ * ERRORS:
+ * EROFS - some variables ("ethaddr", "serial#") cannot be modified
+ */
int fw_setenv(int argc, char *argv[], struct env_opts *opts);
+
+/**
+ * fw_parse_script() - adds or removes multiple variables with a batch script
+ *
+ * @fname: batch script file name
+ * @opts: encryption key, configuration file, defaults are used if NULL
+ *
+ * Description:
+ * Uses fw_env_open, fw_env_write, fw_env_close
+ *
+ * Return:
+ * 0 success, -1 on failure (modifies errno)
+ *
+ * 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
+ */
int fw_parse_script(char *fname, struct env_opts *opts);
+
+
+/**
+ * fw_env_open() - read enviroment from flash into RAM cache
+ *
+ * @opts: encryption key, configuration file, defaults are used if NULL
+ *
+ * Return:
+ * 0 on success, -1 on failure (modifies errno)
+ */
int fw_env_open(struct env_opts *opts);
+
+/**
+ * fw_getenv() - lookup variable in the RAM cache
+ *
+ * @name: variable to be searched
+ * Return:
+ * pointer to start of value, NULL if not found
+ */
+char *fw_getenv(char *name);
+
+/**
+ * fw_env_write() - modify a variable held in the RAM cache
+ *
+ * @name: variable
+ * @value: delete variable if NULL, otherwise create or overwrite the variable
+ *
+ * This is called in sequence to update the environment in RAM without updating
+ * the copy in flash after each set
+ *
+ * Return:
+ * 0 on success, -1 on failure (modifies errno)
+ *
+ * ERRORS:
+ * EROFS - some variables ("ethaddr", "serial#") cannot be modified
+ */
int fw_env_write(char *name, char *value);
+
+/**
+ * fw_env_close - write the environment from RAM cache back to flash
+ *
+ * @opts: encryption key, configuration file, defaults are used if NULL
+ *
+ * Return:
+ * 0 on success, -1 on failure (modifies errno)
+ */
int fw_env_close(struct env_opts *opts);
unsigned long crc32(unsigned long, const unsigned char *, unsigned);