]>
Commit | Line | Data |
---|---|---|
af95f206 SG |
1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* | |
db197010 | 3 | * Common environment functions and definitions |
af95f206 SG |
4 | * |
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 | ||
664689f1 | 12 | #include <compiler.h> |
af95f206 | 13 | #include <stdbool.h> |
c7694dd4 | 14 | #include <linux/types.h> |
af95f206 | 15 | |
4e9ce8a6 SG |
16 | struct environment_s; |
17 | ||
db197010 SG |
18 | /* Value for environment validity */ |
19 | enum 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 | ||
02cf9334 SG |
25 | /** enum env_op - environment callback operation */ |
26 | enum 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 */ | |
33 | struct 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 | ||
d3716dd6 SG |
59 | /** enum env_redund_flags - Flags for the redundand_environment */ |
60 | enum env_redund_flags { | |
61 | ENV_REDUND_OBSOLETE = 0, | |
62 | ENV_REDUND_ACTIVE = 1, | |
63 | }; | |
64 | ||
f1f0ae6a SG |
65 | /** |
66 | * 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 | * | |
185f812c | 71 | * Return: environment ID |
f1f0ae6a SG |
72 | */ |
73 | int env_get_id(void); | |
74 | ||
d9721925 TR |
75 | /** |
76 | * 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 | */ | |
81 | void env_inc_id(void); | |
82 | ||
4bfd1f5d SG |
83 | /** |
84 | * 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 | * | |
185f812c | 89 | * Return: 0 if OK, -ENODEV if no environment drivers are enabled |
4bfd1f5d SG |
90 | */ |
91 | int env_init(void); | |
92 | ||
3f989e7b SG |
93 | /** |
94 | * 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 | */ | |
99 | void env_relocate(void); | |
100 | ||
7b51b576 SG |
101 | /** |
102 | * 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 | |
185f812c | 109 | * Return: value of variable, or NULL if not found |
7b51b576 SG |
110 | */ |
111 | char *env_get(const char *varname); | |
112 | ||
1ac2cb97 PC |
113 | /* |
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 | |
185f812c | 119 | * Return: value of variable, or NULL if not found |
1ac2cb97 PC |
120 | */ |
121 | char *from_env(const char *envvar); | |
122 | ||
3a7d5571 SG |
123 | /** |
124 | * 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 | |
185f812c | 131 | * Return: actual length of the variable value excluding the terminating |
3112ce0c | 132 | * NULL-byte, or -1 if the variable is not found |
3a7d5571 SG |
133 | */ |
134 | int env_get_f(const char *name, char *buf, unsigned int len); | |
135 | ||
6bf6dbee SG |
136 | /** |
137 | * env_get_yesno() - Read an environment variable as a boolean | |
138 | * | |
185f812c | 139 | * Return: 1 if yes/true (Y/y/T/t), -1 if variable does not exist (i.e. default |
6bf6dbee SG |
140 | * to true), 0 if otherwise |
141 | */ | |
142 | int env_get_yesno(const char *var); | |
143 | ||
78398652 SG |
144 | /** |
145 | * env_get_autostart() - Check if autostart is enabled | |
146 | * | |
185f812c | 147 | * Return: true if the "autostart" env var exists and is set to "yes" |
78398652 SG |
148 | */ |
149 | bool env_get_autostart(void); | |
150 | ||
9fb625ce SG |
151 | /** |
152 | * 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 | |
185f812c | 159 | * Return: 0 if OK, 1 on error |
9fb625ce SG |
160 | */ |
161 | int env_set(const char *varname, const char *value); | |
162 | ||
9eef56db SG |
163 | /** |
164 | * 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 | |
185f812c | 172 | * Return: the value found, or @default_val if none |
9eef56db SG |
173 | */ |
174 | ulong env_get_ulong(const char *name, int base, ulong default_val); | |
175 | ||
168068fb SG |
176 | /** |
177 | * 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) | |
185f812c | 181 | * Return: 0 if OK, 1 on error |
168068fb SG |
182 | */ |
183 | int env_set_ulong(const char *varname, ulong value); | |
184 | ||
cdbff9fc SG |
185 | /** |
186 | * 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 | */ | |
195 | ulong env_get_hex(const char *varname, ulong default_val); | |
196 | ||
c7694dd4 SG |
197 | /** |
198 | * 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) | |
185f812c | 202 | * Return: 0 if OK, 1 on error |
c7694dd4 SG |
203 | */ |
204 | int 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 | |
185f812c | 211 | * Return: 0 if ok, 1 on error |
c7694dd4 SG |
212 | */ |
213 | static inline int env_set_addr(const char *varname, const void *addr) | |
214 | { | |
215 | return env_set_hex(varname, (ulong)addr); | |
216 | } | |
217 | ||
af95f206 SG |
218 | /** |
219 | * 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 ${...} | |
185f812c | 227 | * Return: number of matches found (in @cmdv) |
af95f206 SG |
228 | */ |
229 | int env_complete(char *var, int maxv, char *cmdv[], int maxsz, char *buf, | |
230 | bool dollar_comp); | |
231 | ||
b79cf1af SG |
232 | /** |
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) | |
fbc595b4 | 237 | * Return: 1 if OK, 0 on error |
b79cf1af SG |
238 | */ |
239 | int 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) | |
fbc595b4 | 246 | * Return: 0 if OK, non-zero otherwise |
b79cf1af SG |
247 | */ |
248 | int eth_env_set_enetaddr(const char *name, const uint8_t *enetaddr); | |
249 | ||
0b9d8a05 SG |
250 | /** |
251 | * 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 | */ | |
259 | int env_set_default_vars(int nvars, char *const vars[], int flags); | |
260 | ||
4be490ae SG |
261 | /** |
262 | * env_load() - Load the environment from storage | |
263 | * | |
185f812c | 264 | * Return: 0 if OK, -ve on error |
4be490ae SG |
265 | */ |
266 | int env_load(void); | |
267 | ||
0115dd3a PD |
268 | /** |
269 | * env_reload() - Re-Load the environment from current storage | |
270 | * | |
185f812c | 271 | * Return: 0 if OK, -ve on error |
0115dd3a PD |
272 | */ |
273 | int env_reload(void); | |
274 | ||
4be490ae SG |
275 | /** |
276 | * env_save() - Save the environment to storage | |
277 | * | |
185f812c | 278 | * Return: 0 if OK, -ve on error |
4be490ae SG |
279 | */ |
280 | int env_save(void); | |
281 | ||
282 | /** | |
283 | * env_erase() - Erase the environment on storage | |
284 | * | |
185f812c | 285 | * Return: 0 if OK, -ve on error |
4be490ae SG |
286 | */ |
287 | int env_erase(void); | |
288 | ||
a97d22eb PD |
289 | /** |
290 | * env_select() - Select the environment storage | |
291 | * | |
185f812c | 292 | * Return: 0 if OK, -ve on error |
a97d22eb PD |
293 | */ |
294 | int env_select(const char *name); | |
295 | ||
4e9ce8a6 SG |
296 | /** |
297 | * 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 | |
890feeca | 305 | * @flags: Flags controlling matching (H_... - see search.h) |
185f812c | 306 | * Return: 0 if imported successfully, -ENOMSG if the CRC was bad, -EIO if |
4e9ce8a6 SG |
307 | * something else went wrong |
308 | */ | |
890feeca | 309 | int env_import(const char *buf, int check, int flags); |
4e9ce8a6 SG |
310 | |
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!) | |
185f812c | 317 | * Return: 0 if OK, 1 on error |
4e9ce8a6 SG |
318 | */ |
319 | int env_export(struct environment_s *env_out); | |
320 | ||
1229533a HS |
321 | /** |
322 | * 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 | |
185f812c | 329 | * Return: 0 if OK, |
1229533a | 330 | * -EIO if no environment is valid, |
1229533a HS |
331 | * -ENOMSG if the CRC was bad |
332 | */ | |
333 | ||
334 | int env_check_redund(const char *buf1, int buf1_read_fail, | |
335 | const char *buf2, int buf2_read_fail); | |
336 | ||
4e9ce8a6 SG |
337 | /** |
338 | * 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 | |
890feeca | 344 | * @flags: Flags controlling matching (H_... - see search.h) |
185f812c | 345 | * Return: 0 if OK, -EIO if no environment is valid, -ENOMSG if the CRC was bad |
4e9ce8a6 SG |
346 | */ |
347 | int env_import_redund(const char *buf1, int buf1_read_fail, | |
890feeca MV |
348 | const char *buf2, int buf2_read_fail, |
349 | int flags); | |
4e9ce8a6 | 350 | |
0ac7d722 SG |
351 | /** |
352 | * env_get_default() - Look up a variable from the default environment | |
353 | * | |
354 | * @name: Variable to look up | |
185f812c | 355 | * Return: value if found, NULL if not found in default environment |
0ac7d722 SG |
356 | */ |
357 | char *env_get_default(const char *name); | |
358 | ||
23c1ab92 QS |
359 | /** |
360 | * env_get_default_into() - Look up a variable from the default environment and | |
361 | * copy its value in buf. | |
362 | * | |
363 | * @name: Variable to look up | |
364 | * Return: actual length of the variable value excluding the terminating | |
365 | * NULL-byte, or -1 if the variable is not found | |
366 | */ | |
367 | int env_get_default_into(const char *name, char *buf, unsigned int len); | |
368 | ||
0ac7d722 SG |
369 | /* [re]set to the default environment */ |
370 | void env_set_default(const char *s, int flags); | |
371 | ||
95fd9772 RV |
372 | /** |
373 | * env_import_fdt() - Import environment values from device tree blob | |
374 | * | |
375 | * This uses the value of the environment variable "env_fdt_path" as a | |
376 | * path to an fdt node, whose property/value pairs are added to the | |
377 | * environment. | |
378 | */ | |
379 | #ifdef CONFIG_ENV_IMPORT_FDT | |
380 | void env_import_fdt(void); | |
381 | #else | |
382 | static inline void env_import_fdt(void) {} | |
383 | #endif | |
384 | ||
af95f206 | 385 | #endif |