blob: 9778e3e4f2ce33e3530e3a941357a8df92c739bf [file] [log] [blame]
Simon Glassaf95f202019-08-01 09:46:40 -06001/* SPDX-License-Identifier: GPL-2.0+ */
2/*
Simon Glassdb197012019-08-01 09:47:04 -06003 * Common environment functions and definitions
Simon Glassaf95f202019-08-01 09:46:40 -06004 *
5 * (C) Copyright 2000-2009
6 * Wolfgang Denk, DENX Software Engineering, wd@denx.de.
7 */
8
9#ifndef __ENV_H
10#define __ENV_H
11
Pierre-Jean Texier664689f2019-08-26 13:06:17 +020012#include <compiler.h>
Simon Glassaf95f202019-08-01 09:46:40 -060013#include <stdbool.h>
Simon Glassc7694dd2019-08-01 09:46:46 -060014#include <linux/types.h>
Simon Glassaf95f202019-08-01 09:46:40 -060015
Simon Glass4e9ce8a2019-08-01 09:46:58 -060016struct environment_s;
17
Simon Glassdb197012019-08-01 09:47:04 -060018/* Value for environment validity */
19enum env_valid {
20 ENV_INVALID, /* No valid environment */
21 ENV_VALID, /* First or only environment is valid */
22 ENV_REDUND, /* Redundant environment is valid */
23};
24
Simon Glass02cf9332019-08-01 09:47:05 -060025/** enum env_op - environment callback operation */
26enum env_op {
27 env_op_create,
28 env_op_delete,
29 env_op_overwrite,
30};
31
32/** struct env_clbk_tbl - declares a new callback */
33struct env_clbk_tbl {
34 const char *name; /* Callback name */
35 int (*callback)(const char *name, const char *value, enum env_op op,
36 int flags);
37};
38
39/*
40 * Define a callback that can be associated with variables.
41 * when associated through the ".callbacks" environment variable, the callback
42 * will be executed any time the variable is inserted, overwritten, or deleted.
43 *
44 * For SPL these are silently dropped to reduce code size, since environment
45 * callbacks are not supported with SPL.
46 */
47#ifdef CONFIG_SPL_BUILD
48#define U_BOOT_ENV_CALLBACK(name, callback) \
49 static inline __maybe_unused void _u_boot_env_noop_##name(void) \
50 { \
51 (void)callback; \
52 }
53#else
54#define U_BOOT_ENV_CALLBACK(name, callback) \
55 ll_entry_declare(struct env_clbk_tbl, name, env_clbk) = \
56 {#name, callback}
57#endif
58
Simon Glassd3716dd2019-08-01 09:47:08 -060059/** enum env_redund_flags - Flags for the redundand_environment */
60enum env_redund_flags {
61 ENV_REDUND_OBSOLETE = 0,
62 ENV_REDUND_ACTIVE = 1,
63};
64
Simon Glassaf95f202019-08-01 09:46:40 -060065/**
Simon Glassf1f0ae62019-08-01 09:46:41 -060066 * env_get_id() - Gets a sequence number for the environment
67 *
68 * This value increments every time the environment changes, so can be used an
69 * an indication of this
70 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +010071 * Return: environment ID
Simon Glassf1f0ae62019-08-01 09:46:41 -060072 */
73int env_get_id(void);
74
75/**
Tom Rinid9721922023-10-26 14:31:16 -040076 * env_inc_id() - Increase the sequence number for the environment
77 *
78 * Increment the value that is used by env_get_id() to inform callers
79 * if the environment has changed since they last checked.
80 */
81void env_inc_id(void);
82
83/**
Simon Glass4bfd1f52019-08-01 09:46:43 -060084 * env_init() - Set up the pre-relocation environment
85 *
86 * This locates the environment or uses the default if nothing is available.
87 * This must be called before env_get() will work.
88 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +010089 * Return: 0 if OK, -ENODEV if no environment drivers are enabled
Simon Glass4bfd1f52019-08-01 09:46:43 -060090 */
91int env_init(void);
92
93/**
Simon Glass3f989e7b2019-08-01 09:46:44 -060094 * env_relocate() - Set up the post-relocation environment
95 *
96 * This loads the environment into RAM so that it can be modified. This is
97 * called after relocation, before the environment is used
98 */
99void env_relocate(void);
100
101/**
Simon Glass7b51b572019-08-01 09:46:52 -0600102 * env_get() - Look up the value of an environment variable
103 *
104 * In U-Boot proper this can be called before relocation (which is when the
105 * environment is loaded from storage, i.e. GD_FLG_ENV_READY is 0). In that
106 * case this function calls env_get_f().
107 *
108 * @varname: Variable to look up
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100109 * Return: value of variable, or NULL if not found
Simon Glass7b51b572019-08-01 09:46:52 -0600110 */
111char *env_get(const char *varname);
112
Patrice Chotard1ac2cb92019-11-25 09:07:36 +0100113/*
114 * Like env_get, but prints an error if envvar isn't defined in the
115 * environment. It always returns what env_get does, so it can be used in
116 * place of env_get without changing error handling otherwise.
117 *
118 * @varname: Variable to look up
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100119 * Return: value of variable, or NULL if not found
Patrice Chotard1ac2cb92019-11-25 09:07:36 +0100120 */
121char *from_env(const char *envvar);
122
Simon Glass7b51b572019-08-01 09:46:52 -0600123/**
Simon Glass3a7d5572019-08-01 09:46:42 -0600124 * env_get_f() - Look up the value of an environment variable (early)
125 *
126 * This function is called from env_get() if the environment has not been
127 * loaded yet (GD_FLG_ENV_READY flag is 0). Some environment locations will
128 * support reading the value (slowly) and some will not.
129 *
130 * @varname: Variable to look up
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100131 * Return: actual length of the variable value excluding the terminating
Marek BehĂșn3112ce02021-10-17 17:36:35 +0200132 * NULL-byte, or -1 if the variable is not found
Simon Glass3a7d5572019-08-01 09:46:42 -0600133 */
134int env_get_f(const char *name, char *buf, unsigned int len);
135
136/**
Simon Glass6bf6dbe2019-08-01 09:46:49 -0600137 * env_get_yesno() - Read an environment variable as a boolean
138 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100139 * Return: 1 if yes/true (Y/y/T/t), -1 if variable does not exist (i.e. default
Simon Glass6bf6dbe2019-08-01 09:46:49 -0600140 * to true), 0 if otherwise
141 */
142int env_get_yesno(const char *var);
143
144/**
Simon Glass78398652021-10-21 21:08:52 -0600145 * env_get_autostart() - Check if autostart is enabled
146 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100147 * Return: true if the "autostart" env var exists and is set to "yes"
Simon Glass78398652021-10-21 21:08:52 -0600148 */
149bool env_get_autostart(void);
150
151/**
Simon Glass9fb625c2019-08-01 09:46:51 -0600152 * env_set() - set an environment variable
153 *
154 * This sets or deletes the value of an environment variable. For setting the
155 * value the variable is created if it does not already exist.
156 *
157 * @varname: Variable to adjust
158 * @value: Value to set for the variable, or NULL or "" to delete the variable
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100159 * Return: 0 if OK, 1 on error
Simon Glass9fb625c2019-08-01 09:46:51 -0600160 */
161int env_set(const char *varname, const char *value);
162
163/**
Simon Glass9eef56d2019-08-01 09:46:48 -0600164 * env_get_ulong() - Return an environment variable as an integer value
165 *
166 * Most U-Boot environment variables store hex values. For those which store
167 * (e.g.) base-10 integers, this function can be used to read the value.
168 *
169 * @name: Variable to look up
170 * @base: Base to use (e.g. 10 for base 10, 2 for binary)
171 * @default_val: Default value to return if no value is found
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100172 * Return: the value found, or @default_val if none
Simon Glass9eef56d2019-08-01 09:46:48 -0600173 */
174ulong env_get_ulong(const char *name, int base, ulong default_val);
175
176/**
Simon Glass168068f2019-08-01 09:46:47 -0600177 * env_set_ulong() - set an environment variable to an integer
178 *
179 * @varname: Variable to adjust
180 * @value: Value to set for the variable (will be converted to a string)
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100181 * Return: 0 if OK, 1 on error
Simon Glass168068f2019-08-01 09:46:47 -0600182 */
183int env_set_ulong(const char *varname, ulong value);
184
185/**
Simon Glasscdbff9f2019-08-01 09:46:50 -0600186 * env_get_hex() - Return an environment variable as a hex value
187 *
188 * Decode an environment as a hex number (it may or may not have a 0x
189 * prefix). If the environment variable cannot be found, or does not start
190 * with hex digits, the default value is returned.
191 *
192 * @varname: Variable to decode
193 * @default_val: Value to return on error
194 */
195ulong env_get_hex(const char *varname, ulong default_val);
196
197/**
Simon Glassc7694dd2019-08-01 09:46:46 -0600198 * env_set_hex() - set an environment variable to a hex value
199 *
200 * @varname: Variable to adjust
201 * @value: Value to set for the variable (will be converted to a hex string)
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100202 * Return: 0 if OK, 1 on error
Simon Glassc7694dd2019-08-01 09:46:46 -0600203 */
204int env_set_hex(const char *varname, ulong value);
205
206/**
207 * env_set_addr - Set an environment variable to an address in hex
208 *
209 * @varname: Environment variable to set
210 * @addr: Value to set it to
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100211 * Return: 0 if ok, 1 on error
Simon Glassc7694dd2019-08-01 09:46:46 -0600212 */
213static inline int env_set_addr(const char *varname, const void *addr)
214{
215 return env_set_hex(varname, (ulong)addr);
216}
217
218/**
Simon Glassaf95f202019-08-01 09:46:40 -0600219 * env_complete() - return an auto-complete for environment variables
220 *
221 * @var: partial name to auto-complete
222 * @maxv: Maximum number of matches to return
223 * @cmdv: Returns a list of possible matches
224 * @maxsz: Size of buffer to use for matches
225 * @buf: Buffer to use for matches
226 * @dollar_comp: non-zero to wrap each match in ${...}
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100227 * Return: number of matches found (in @cmdv)
Simon Glassaf95f202019-08-01 09:46:40 -0600228 */
229int env_complete(char *var, int maxv, char *cmdv[], int maxsz, char *buf,
230 bool dollar_comp);
231
Simon Glassb79cf1a2019-08-01 09:46:53 -0600232/**
233 * eth_env_get_enetaddr() - Get an ethernet address from the environmnet
234 *
235 * @name: Environment variable to get (e.g. "ethaddr")
236 * @enetaddr: Place to put MAC address (6 bytes)
Marek Vasutfbc595b2022-12-18 08:05:02 +0100237 * Return: 1 if OK, 0 on error
Simon Glassb79cf1a2019-08-01 09:46:53 -0600238 */
239int eth_env_get_enetaddr(const char *name, uint8_t *enetaddr);
240
241/**
242 * eth_env_set_enetaddr() - Set an ethernet address in the environmnet
243 *
244 * @name: Environment variable to set (e.g. "ethaddr")
245 * @enetaddr: Pointer to MAC address to put into the variable (6 bytes)
Marek Vasutfbc595b2022-12-18 08:05:02 +0100246 * Return: 0 if OK, non-zero otherwise
Simon Glassb79cf1a2019-08-01 09:46:53 -0600247 */
248int eth_env_set_enetaddr(const char *name, const uint8_t *enetaddr);
249
Simon Glass03ed9182019-08-01 09:46:55 -0600250/**
Simon Glass0b9d8a02019-08-01 09:46:56 -0600251 * env_set_default_vars() - reset variables to their default value
252 *
253 * This resets individual variables to their value in the default environment
254 *
255 * @nvars: Number of variables to set/reset
256 * @vars: List of variables to set/reset
257 * @flags: Flags controlling matching (H_... - see search.h)
258 */
259int env_set_default_vars(int nvars, char *const vars[], int flags);
260
Simon Glass4be490a2019-08-01 09:46:57 -0600261/**
262 * env_load() - Load the environment from storage
263 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100264 * Return: 0 if OK, -ve on error
Simon Glass4be490a2019-08-01 09:46:57 -0600265 */
266int env_load(void);
267
268/**
Patrick Delaunay0115dd32020-07-28 11:51:20 +0200269 * env_reload() - Re-Load the environment from current storage
270 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100271 * Return: 0 if OK, -ve on error
Patrick Delaunay0115dd32020-07-28 11:51:20 +0200272 */
273int env_reload(void);
274
275/**
Simon Glass4be490a2019-08-01 09:46:57 -0600276 * env_save() - Save the environment to storage
277 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100278 * Return: 0 if OK, -ve on error
Simon Glass4be490a2019-08-01 09:46:57 -0600279 */
280int env_save(void);
281
282/**
283 * env_erase() - Erase the environment on storage
284 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100285 * Return: 0 if OK, -ve on error
Simon Glass4be490a2019-08-01 09:46:57 -0600286 */
287int env_erase(void);
288
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600289/**
Patrick Delaunaya97d22e2020-07-28 11:51:21 +0200290 * env_select() - Select the environment storage
291 *
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100292 * Return: 0 if OK, -ve on error
Patrick Delaunaya97d22e2020-07-28 11:51:21 +0200293 */
294int env_select(const char *name);
295
296/**
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600297 * env_import() - Import from a binary representation into hash table
298 *
299 * This imports the environment from a buffer. The format for each variable is
300 * var=value\0 with a double \0 at the end of the buffer.
301 *
302 * @buf: Buffer containing the environment (struct environemnt_s *)
303 * @check: non-zero to check the CRC at the start of the environment, 0 to
304 * ignore it
Marek Vasut890feec2020-07-07 20:51:35 +0200305 * @flags: Flags controlling matching (H_... - see search.h)
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100306 * Return: 0 if imported successfully, -ENOMSG if the CRC was bad, -EIO if
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600307 * something else went wrong
308 */
Marek Vasut890feec2020-07-07 20:51:35 +0200309int env_import(const char *buf, int check, int flags);
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600310
311/**
312 * env_export() - Export the environment to a buffer
313 *
314 * Export from hash table into binary representation
315 *
316 * @env_out: Buffer to contain the environment (must be large enough!)
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100317 * Return: 0 if OK, 1 on error
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600318 */
319int env_export(struct environment_s *env_out);
320
321/**
Heiko Schocher12295332020-10-10 10:28:04 +0200322 * env_check_redund() - check the two redundant environments
323 * and find out, which is the valid one.
324 *
325 * @buf1: First environment (struct environemnt_s *)
326 * @buf1_read_fail: 0 if buf1 is valid, non-zero if invalid
327 * @buf2: Second environment (struct environemnt_s *)
328 * @buf2_read_fail: 0 if buf2 is valid, non-zero if invalid
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100329 * Return: 0 if OK,
Heiko Schocher12295332020-10-10 10:28:04 +0200330 * -EIO if no environment is valid,
Heiko Schocher12295332020-10-10 10:28:04 +0200331 * -ENOMSG if the CRC was bad
332 */
333
334int env_check_redund(const char *buf1, int buf1_read_fail,
335 const char *buf2, int buf2_read_fail);
336
337/**
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600338 * env_import_redund() - Select and import one of two redundant environments
339 *
340 * @buf1: First environment (struct environemnt_s *)
341 * @buf1_read_fail: 0 if buf1 is valid, non-zero if invalid
342 * @buf2: Second environment (struct environemnt_s *)
343 * @buf2_read_fail: 0 if buf2 is valid, non-zero if invalid
Marek Vasut890feec2020-07-07 20:51:35 +0200344 * @flags: Flags controlling matching (H_... - see search.h)
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100345 * Return: 0 if OK, -EIO if no environment is valid, -ENOMSG if the CRC was bad
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600346 */
347int env_import_redund(const char *buf1, int buf1_read_fail,
Marek Vasut890feec2020-07-07 20:51:35 +0200348 const char *buf2, int buf2_read_fail,
349 int flags);
Simon Glass4e9ce8a2019-08-01 09:46:58 -0600350
Simon Glass0ac7d722019-08-01 09:47:00 -0600351/**
352 * env_get_default() - Look up a variable from the default environment
353 *
354 * @name: Variable to look up
Heinrich Schuchardt185f8122022-01-19 18:05:50 +0100355 * Return: value if found, NULL if not found in default environment
Simon Glass0ac7d722019-08-01 09:47:00 -0600356 */
357char *env_get_default(const char *name);
358
359/* [re]set to the default environment */
360void env_set_default(const char *s, int flags);
361
Simon Glassb5f449e2019-08-01 09:47:01 -0600362/**
Rasmus Villemoes95fd9772021-04-21 11:06:54 +0200363 * env_import_fdt() - Import environment values from device tree blob
364 *
365 * This uses the value of the environment variable "env_fdt_path" as a
366 * path to an fdt node, whose property/value pairs are added to the
367 * environment.
368 */
369#ifdef CONFIG_ENV_IMPORT_FDT
370void env_import_fdt(void);
371#else
372static inline void env_import_fdt(void) {}
373#endif
374
Simon Glassaf95f202019-08-01 09:46:40 -0600375#endif