1.. SPDX-License-Identifier: GPL-2.0+
2
3Environment implementation
4==========================
5
6See :doc:`../usage/environment` for usage information.
7
8Callback functions for environment variables
9--------------------------------------------
10
11For some environment variables, the behavior of u-boot needs to change
12when their values are changed.  This functionality allows functions to
13be associated with arbitrary variables.  On creation, overwrite, or
14deletion, the callback will provide the opportunity for some side
15effect to happen or for the change to be rejected.
16
17The callbacks are named and associated with a function using the
18U_BOOT_ENV_CALLBACK macro in your board or driver code.
19
20These callbacks are associated with variables in one of two ways.  The
21static list can be added to by defining CFG_ENV_CALLBACK_LIST_STATIC
22in the board configuration to a string that defines a list of
23associations.  The list must be in the following format::
24
25    entry = variable_name[:callback_name]
26    list = entry[,list]
27
28If the callback name is not specified, then the callback is deleted.
29Spaces are also allowed anywhere in the list.
30
31Callbacks can also be associated by defining the ".callbacks" variable
32with the same list format above.  Any association in ".callbacks" will
33override any association in the static list. You can define
34CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the
35".callbacks" environment variable in the default or embedded environment.
36
37If CONFIG_REGEX is defined, the variable_name above is evaluated as a
38regular expression. This allows multiple variables to be connected to
39the same callback without explicitly listing them all out.
40
41The signature of the callback functions is::
42
43    int callback(const char *name, const char *value, enum env_op op, int flags)
44
45* name - changed environment variable
46* value - new value of the environment variable
47* op - operation (create, overwrite, or delete)
48* flags - attributes of the environment variable change, see flags H_* in
49  include/search.h
50
51The return value is 0 if the variable change is accepted and 1 otherwise.
52