Merge branch '2021-11-16-env-rework' into next

To quote Simon:

One barrier to completing the 7-year-long Kconfig migration is that
the default environment is implemented using ad-hoc CONFIG options.
At present U-Boot environment variables, and thus scripts, are defined
by CONFIG_EXTRA_ENV_SETTINGS.

It is not really feasible to move the environment to Kconfig as it is
hundreds of lines of text in some cases.

Even considering the current situation, it is painful to add large
amounts of text to the config-header file and dealing with quoting and
newlines is harder than it should be. It would be better if we could just
type the script into a text file and have it included by U-Boot.

This is already supported by the CONFIG_USE_DEFAULT_ENV_FILE feature. But
that does not support use of CONFIG options or comments, so is best suited
for use by other build systems wanting to define the U-Boot environment.

Add a feature that brings in a .env file associated with the board
config, if present. To use it, create a file board/<vendor>/<board>.env or
use CONFIG_ENV_SOURCE_FILE to set a filename.

The environment variables should be of the form "var=value". Values can
extend to multiple lines. This series converts the existing environment
documentation to rST and updates it to explain how to use this.

2 files changed, 52 insertions, 0 deletions

diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst
new file mode 100644
index 00000000000..0b86fafbff7
--- /dev/null
+++ b/doc/develop/environment.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Environment implementation
+==========================
+
+See :doc:`../usage/environment` for usage information.
+
+Callback functions for environment variables
+--------------------------------------------
+
+For some environment variables, the behavior of u-boot needs to change
+when their values are changed.  This functionality allows functions to
+be associated with arbitrary variables.  On creation, overwrite, or
+deletion, the callback will provide the opportunity for some side
+effect to happen or for the change to be rejected.
+
+The callbacks are named and associated with a function using the
+U_BOOT_ENV_CALLBACK macro in your board or driver code.
+
+These callbacks are associated with variables in one of two ways.  The
+static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC
+in the board configuration to a string that defines a list of
+associations.  The list must be in the following format::
+
+    entry = variable_name[:callback_name]
+    list = entry[,list]
+
+If the callback name is not specified, then the callback is deleted.
+Spaces are also allowed anywhere in the list.
+
+Callbacks can also be associated by defining the ".callbacks" variable
+with the same list format above.  Any association in ".callbacks" will
+override any association in the static list. You can define
+CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
+".callbacks" environment variable in the default or embedded environment.
+
+If CONFIG_REGEX is defined, the variable_name above is evaluated as a
+regular expression. This allows multiple variables to be connected to
+the same callback without explicitly listing them all out.
+
+The signature of the callback functions is::
+
+    int callback(const char *name, const char *value, enum env_op op, int flags)
+
+* name - changed environment variable
+* value - new value of the environment variable
+* op - operation (create, overwrite, or delete)
+* flags - attributes of the environment variable change, see flags H_* in
+  include/search.h
+
+The return value is 0 if the variable change is accepted and 1 otherwise.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index b3871b16f35..9592d193fca 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -16,6 +16,7 @@ Implementation
    devicetree/index
    distro
    driver-model/index
+   environment
    global_data
    logging
    makefiles