Simon Glass | 420febd | 2021-10-21 21:08:50 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | |
| 3 | Environment implementation |
| 4 | ========================== |
| 5 | |
| 6 | See :doc:`../usage/environment` for usage information. |
| 7 | |
| 8 | Callback functions for environment variables |
| 9 | -------------------------------------------- |
| 10 | |
| 11 | For some environment variables, the behavior of u-boot needs to change |
| 12 | when their values are changed. This functionality allows functions to |
| 13 | be associated with arbitrary variables. On creation, overwrite, or |
| 14 | deletion, the callback will provide the opportunity for some side |
| 15 | effect to happen or for the change to be rejected. |
| 16 | |
| 17 | The callbacks are named and associated with a function using the |
| 18 | U_BOOT_ENV_CALLBACK macro in your board or driver code. |
| 19 | |
| 20 | These callbacks are associated with variables in one of two ways. The |
Tom Rini | 364d002 | 2023-01-10 11:19:45 -0500 | [diff] [blame^] | 21 | static list can be added to by defining CFG_ENV_CALLBACK_LIST_STATIC |
Simon Glass | 420febd | 2021-10-21 21:08:50 -0600 | [diff] [blame] | 22 | in the board configuration to a string that defines a list of |
| 23 | associations. The list must be in the following format:: |
| 24 | |
| 25 | entry = variable_name[:callback_name] |
| 26 | list = entry[,list] |
| 27 | |
| 28 | If the callback name is not specified, then the callback is deleted. |
| 29 | Spaces are also allowed anywhere in the list. |
| 30 | |
| 31 | Callbacks can also be associated by defining the ".callbacks" variable |
| 32 | with the same list format above. Any association in ".callbacks" will |
| 33 | override any association in the static list. You can define |
| 34 | CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the |
| 35 | ".callbacks" environment variable in the default or embedded environment. |
| 36 | |
| 37 | If CONFIG_REGEX is defined, the variable_name above is evaluated as a |
| 38 | regular expression. This allows multiple variables to be connected to |
| 39 | the same callback without explicitly listing them all out. |
| 40 | |
| 41 | The 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 | |
| 51 | The return value is 0 if the variable change is accepted and 1 otherwise. |