[PATCH] doc: man-page for the env command
Patrick Delaunay
patrick.delaunay at foss.st.com
Thu Apr 14 19:07:05 CEST 2022
Describe the env command.
Signed-off-by: Patrick Delaunay <patrick.delaunay at foss.st.com>
---
doc/usage/cmd/askenv.rst | 2 +
doc/usage/cmd/env.rst | 365 ++++++++++++++++++++++++++++++++++++++
doc/usage/cmdline.rst | 2 +-
doc/usage/environment.rst | 2 +
doc/usage/index.rst | 1 +
5 files changed, 371 insertions(+), 1 deletion(-)
create mode 100644 doc/usage/cmd/env.rst
diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst
index 5c4ca35d4c..347bd59458 100644
--- a/doc/usage/cmd/askenv.rst
+++ b/doc/usage/cmd/askenv.rst
@@ -16,6 +16,8 @@ Description
Display message and get environment variable name of max size characters
from stdin.
+See also *env ask* in :doc:`env`.
+
name
name of the environment variable
diff --git a/doc/usage/cmd/env.rst b/doc/usage/cmd/env.rst
new file mode 100644
index 0000000000..e8c5797abd
--- /dev/null
+++ b/doc/usage/cmd/env.rst
@@ -0,0 +1,365 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later:
+
+env command
+===========
+
+Synopsis
+--------
+
+::
+
+ env ask name [message] [size]
+ env callbacks
+ env default [-f] (-a | var [...])
+ env delete [-f] var [...]
+ env edit name
+ env exists name
+ env export [-t | -b | -c] [-s size] addr [var ...]
+ env flags
+ env grep [-e] [-n | -v | -b] string [...]
+ env import [-d] [-t [-r] | -b | -c] addr [size] [var ...]
+ env info [-d] [-p] [-q]
+ env print [-a | name ...]
+ env print -e [-guid guid] [-n] [name ...]
+ env run var [...]
+ env save
+ env erase
+ env load
+ env select [target]
+ env set [-f] name [value]
+ env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value]
+
+Description
+-----------
+The *env* commands is used to handle the U-Boot (:doc:`../environment`) or
+the UEFI variables.
+
+The next commands are kept as alias and for compatibility:
+
++ *editenv* = *env edit*
++ *grepenv* = *env grep*
++ *setenv* = *env set*
++ *askenv* = *env ask*
++ *run* = *env run*
+
+Ask
+~~~
+
+The *env ask* command asks for environment variable (alias :doc:`askenv`).
+
+ name
+ name of the environment variable.
+
+ message
+ message is displayed while the command waits for the value to be
+ entered from stdin.if no message is specified,a default message
+ "Please enter name:" will be displayed.
+
+ size
+ maximum number of characters that will be stored in environment
+ variable name.this is in decimal number format (unlike in
+ other commands where size values are in hexa-decimal). Default
+ value of size is 1023 (CONFIG_SYS_CBSIZE - 1).
+
+Callbacks
+~~~~~~~~~
+
+The *env callbacks* command prints callbacks and their associated variables.
+
+Default
+~~~~~~~
+
+The *env default* command resets the selected variables in the U-Boot
+environment to their default values.
+
+ var
+ list of variable name.
+ \-a
+ all U-Boot environment.
+ \-f
+ forcibly, overwrite read-only/write-once variables.
+
+Delete
+~~~~~~
+
+The *env delete* command deletes the selected variables in the U-Boot
+environment.
+
+ var
+ name of the variable to delete.
+ \-f
+ forcibly, overwrite read-only/write-once variables.
+
+Edit
+~~~~
+
+The *env edit* command edits an environment variable.
+
+ name
+ name of the variable.
+
+Exists
+~~~~~~
+
+The *env exists* command tests for existence of variable.
+
+ name
+ name of the variable.
+
+Export
+~~~~~~
+
+The *env export* command exports the U-Boot environment in memory; on success,
+the variable "filesize" will be set.
+
+ addr
+ memory address where environment gets stored.
+ var
+ list of variable names that get included into the export.
+ Without arguments, the whole environment gets exported.
+ \-b
+ export as binary format (name=value pairs separated by
+ list end marked by double "\0\0").
+ \-t
+ export as text format; if size is given, data will be
+ padded with '\0' bytes; if not, one terminating '\0'
+ will be added.
+ \-c
+ Export as checksum protected environment format as used by
+ 'env save' command.
+ \-s size
+ size of output buffer.
+
+Flags
+~~~~~
+
+The *env flags* command prints variables that have non-default flags.
+
+Grep
+~~~~
+
+The *env grep* command searches environment, list environment name=value pairs
+matching the requested 'string'.
+
+ string
+ string to search in U-Boot environment.
+ \-e
+ enable regular expressions.
+ \-n
+ search string in variable names.
+ \-v
+ search string in vairable values.
+ \-b
+ search both names and values (default).
+
+Import
+~~~~~~
+
+The *env import* command imports environment from memory.
+
+ addr
+ memory address to read from.
+ size
+ length of input data; if missing, proper '\0' termination is mandatory
+ if var is set and size should be missing (i.e. '\0' termination),
+ set size to '-'.
+ var
+ List of the names of the only variables that get imported from
+ the environment at address 'addr'. Without arguments, the whole
+ environment gets imported.
+ \-d
+ delete existing environment before importing if no var is passed;
+ if vars are passed, if one var is in the current environment but not
+ in the environment at addr, delete var from current environment;
+ otherwise overwrite / append to existing definitions.
+ \-t
+ assume text format; either "size" must be given or the text data must
+ be '\0' terminated.
+ \-r
+ handle CRLF like LF, that means exported variables with a content which
+ ends with \r won't get imported. Used to import text files created with
+ editors which are using CRLF for line endings.
+ Only effective in addition to -t.
+ \-b
+ assume binary format ('\0' separated, "\0\0" terminated).
+ \-c
+ assume checksum protected environment format.
+
+Info
+~~~~
+
+The *env info* command displays (without argument) or evaluates the U-Boot
+environment information.
+
+ \-d
+ evaluate if the default environment is used.
+ \-p
+ evaluate if environment can be persisted.
+ \-q
+ quiet output, use only for command result, by example with
+ 'test' command.
+
+Print
+~~~~~
+
+The *env print* command prints the selected variables in U-Boot environment or
+in UEFI variables.
+
+ name
+ list of variable name.
+ \-a
+ all U-Boot environment, when 'name' is absent.
+ \-e
+ print UEFI variables, all by default when 'name'.
+ \-guid guid
+ print only the UEFI variables matching this GUID (any by default)
+ with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
+ \-n
+ suppress dumping variable's value for UEFI.
+
+Run
+~~~
+
+The *env run* command runs commands in an environment variable.
+
+ var
+ name of the variable.
+
+Save
+~~~~
+
+The *env save* command saves the U-Boot environment in persistent storage.
+
+Erase
+~~~~~
+
+The *env erase* command erases the U-Boot environment.
+
+Load
+~~~~
+
+The *env load* command loads the U-Boot environment from persistent storage.
+
+Select
+~~~~~~
+
+The *env select* command selects an U-Boot environment target, it is useful to
+overid the default location when several U-Boot environment backend are
+availables.
+
+ target
+ name of the U-Boot environment backend to select: EEPROM, EXT4, FAT,
+ Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI.
+
+
+Set
+~~~
+
+The *env set* command sets or delete (when 'value' or '-i' are absent)
+U-Boot variable in environment or UEFI variables (when -e is specified).
+
+ name
+ variable name to modify.
+ value
+ when present, set the environment variable 'name' to 'value'
+ when absent, delete the environment variable 'name'.
+ \-f
+ forcibly, overwrite read-only/write-once U-Boot variables.
+ \-e
+ update UEFI variables.
+ \-nv
+ set non-volatile attribute (UEFI).
+ \-bs
+ set boot-service attribute (UEFI).
+ \-rt
+ set runtime attribute (UEFI).
+ \-at
+ set time-based authentication attribute (UEFI).
+ \-a
+ append-write (UEFI).
+ \-i addr:size
+ use <addr,size> as variable's value (UEFI).
+ \-v
+ verbose message (UEFI).
+
+Example
+-------
+
+Print the U-Boot environment variables::
+
+ => env print -a
+ => env print bootcmd stdout
+
+Update environment variable in memory::
+
+ => env set bootcmd "run distro_bootcmd"
+ => env set stdout "serial,vidconsole"
+
+Delete environment variable in memory::
+
+ => env delete bootcmd
+ => env set bootcmd
+
+Reset environment variable to default value, in memory::
+
+ => env default bootcmd
+ => env default -a
+
+Save current environment in persistent storage::
+
+ => env save
+
+Restore the default environment in persistent storage::
+
+ => env erase
+
+Create a text snapshot/backup of the current settings in RAM
+(${filesize} can be use to save the snapshot in file)::
+
+ => env export -t ${backup_addr}
+
+Re-import this snapshot, deleting all other settings::
+
+ => env import -d -t ${backup_addr}
+
+Save environment if default enviromnent is used and persistent storage is selected::
+
+ => if env info -p -d -q; then env save; fi
+
+Configuration
+-------------
+
+The env command is always available but some sub-commands need to enable more
+configuration.
+
+ask
+ CONFIG_CMD_ASKENV
+callback
+ CONFIG_CMD_ENV_CALLBACK
+edit
+ CONFIG_CMD_EDITENV
+exists
+ CONFIG_CMD_ENV_EXISTS
+flsgs
+ CONFIG_CMD_ENV_FLAGS
+erase
+ CONFIG_CMD_ERASEENV
+export
+ CONFIG_CMD_EXPORTENV
+grep
+ CONFIG_CMD_GREPENV
+ CONFIG_REGEX for '-e' option
+import
+ CONFIG_CMD_IMPORTENV
+info
+ CONFIG_CMD_NVEDIT_INFO
+load
+ CONFIG_CMD_NVEDIT_LOAD
+run
+ CONFIG_CMD_RUN
+save
+ CONFIG_CMD_SAVEENV
+select
+ CONFIG_CMD_NVEDIT_SELECT
+set, print
+ CONFIG_CMD_NVEDIT_EFI for '-e' option
diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst
index 88f18c974c..58240c5279 100644
--- a/doc/usage/cmdline.rst
+++ b/doc/usage/cmdline.rst
@@ -14,7 +14,7 @@ Simple command-line parser
This takes very little code space and offers only basic features:
-- supports environment variables (through setenv / saveenv commands)
+- supports environment variables (through :doc:`cmd/env`)
- several commands on one line, separated by ';'
- variable substitution using "... ${name} ..." syntax
- special characters ('$', ';') can be escaped by prefixing with '\',
diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
index 80550fc447..dc61703944 100644
--- a/doc/usage/environment.rst
+++ b/doc/usage/environment.rst
@@ -15,6 +15,8 @@ environment. As long as you don't save the environment, you are
working with an in-memory copy. In case the Flash area containing the
environment is erased by accident, a default environment is provided.
+See :doc:`cmd/env` for details.
+
Some configuration is controlled by Environment Variables, so that setting the
variable can adjust the behaviour of U-Boot (e.g. autoboot delay, autoloading
from tftp).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index f457bffc2c..f343e4e05f 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -30,6 +30,7 @@ Shell commands
cmd/cbsysinfo
cmd/conitrace
cmd/echo
+ cmd/env
cmd/event
cmd/exception
cmd/extension
--
2.25.1
More information about the U-Boot
mailing list