jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0-or-later:
2
3.. index::
4 single: env (command)
5
6env command
7===========
8
9Synopsis
10--------
11
12::
13
14 env ask name [message] [size]
15 env callbacks
16 env default [-f] (-a | var [...])
17 env delete [-f] var [...]
18 env edit name
19 env erase
20 env exists name
21 env export [-t | -b | -c] [-s size] addr [var ...]
22 env flags
23 env grep [-e] [-n | -v | -b] string [...]
24 env import [-d] [-t [-r] | -b | -c] addr [size] [var ...]
25 env info [-d] [-p] [-q]
26 env load
27 env print [-a | name ...]
28 env print -e [-guid guid] [-n] [name ...]
29 env run var [...]
30 env save
31 env select [target]
32 env set [-f] name [value]
33 env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value]
34
35Description
36-----------
37
38The *env* commands is used to handle the U-Boot (:doc:`../environment`) or
39the UEFI variables.
40
41The next commands are kept as alias and for compatibility:
42
43+ :doc:`askenv <askenv>` = *env ask*
44+ *editenv* = *env edit*
45+ *grepenv* = *env grep*
46+ :doc:`printenv <printenv>` = *env print*
47+ *run* = *env run*
48+ *setenv* = *env set*
49
50Ask
51~~~
52
53The *env ask* command asks for the new value of an environment variable
54(alias :doc:`askenv`).
55
56 name
57 name of the environment variable.
58
59 message
60 message to be displayed while the command waits for the value to be
61 entered from stdin. If no message is specified, a default message
62 "Please enter name:" will be displayed.
63
64 size
65 maximum number of characters that will be stored in the environment
66 variable name. This is in decimal number format (unlike in
67 other commands where size values are hexa-decimal). The default
68 value of size is 1023 (CONFIG_SYS_CBSIZE - 1).
69
70Callbacks
71~~~~~~~~~
72
73The *env callbacks* command prints callbacks and their associated variables.
74
75Default
76~~~~~~~
77
78The *env default* command resets the selected variables in the U-Boot
79environment to their default values.
80
81 var
82 list of variable names. If variable is not part of default
83 environment, it is deleted with a warning message on console.
84 \-a
85 all U-Boot environment.
86 \-f
87 forcibly, overwrite read-only/write-once variables.
88
89Delete
90~~~~~~
91
92The *env delete* command deletes the selected variables from the U-Boot
93environment.
94
95 var
96 name of the variable to delete.
97 \-f
98 forcibly, overwrite read-only/write-once variables.
99
100Edit
101~~~~
102
103The *env edit* command edits an environment variable.
104
105 name
106 name of the variable.
107
108Erase
109~~~~~
110
111The *env erase* command erases the U-Boot environment.
112
113Exists
114~~~~~~
115
116The *env exists* command tests for existence of variable.
117
118 name
119 name of the variable.
120
121Export
122~~~~~~
123
124The *env export* command exports the U-Boot environment in memory; on success,
125the variable $filesize will be set.
126
127 addr
128 memory address where environment gets stored.
129 var
130 list of variable names that get included into the export.
131 Without arguments, the whole environment gets exported.
132 \-b
133 export as binary format (name=value pairs separated by
134 list end marked by double "\0\0").
135 \-t
136 export as text format; if size is given, data will be
137 padded with '\0' bytes; if not, one terminating '\0'
138 will be added.
139 \-c
140 Export as checksum protected environment format as used by
141 'env save' command.
142 \-s size
143 size of output buffer.
144
145Flags
146~~~~~
147
148The *env flags* command prints variables that have non-default flags.
149
150Grep
151~~~~
152
153The *env grep* command searches environment, list environment name=value pairs
154matching the requested 'string'.
155
156 string
157 string to search in U-Boot environment.
158 \-e
159 enable regular expressions.
160 \-n
161 search string in variable names.
162 \-v
163 search string in vairable values.
164 \-b
165 search both names and values (default).
166
167Import
168~~~~~~
169
170The *env import* command imports environment from memory.
171
172 addr
173 memory address to read from.
174 size
175 length of input data; if missing, proper '\0' termination is mandatory
176 if var is set and size should be missing (i.e. '\0' termination),
177 set size to '-'.
178 var
179 List of the names of the only variables that get imported from
180 the environment at address 'addr'. Without arguments, the whole
181 environment gets imported.
182 \-d
183 delete existing environment before importing if no var is passed;
184 if vars are passed, if one var is in the current environment but not
185 in the environment at addr, delete var from current environment;
186 otherwise overwrite / append to existing definitions.
187 \-t
188 assume text format; either "size" must be given or the text data must
189 be '\0' terminated.
190 \-r
191 handle CRLF like LF, that means exported variables with a content which
192 ends with \r won't get imported. Used to import text files created with
193 editors which are using CRLF for line endings.
194 Only effective in addition to -t.
195 \-b
196 assume binary format ('\0' separated, "\0\0" terminated).
197 \-c
198 assume checksum protected environment format.
199
200Info
201~~~~
202
203The *env info* command displays (without argument) or evaluates the U-Boot
204environment information.
205
206 \-d
207 evaluate if the default environment is used.
208 \-p
209 evaluate if environment can be persisted.
210 \-q
211 quiet output, use only for command result, by example with
212 'test' command.
213
214Load
215~~~~
216
217The *env load* command loads the U-Boot environment from persistent storage.
218
219Print
220~~~~~
221
222The *env print* command prints the selected variables in U-Boot environment or
223in UEFI variables.
224
225 name
226 list of variable name.
227 \-a
228 all U-Boot environment, when 'name' is absent.
229 \-e
230 print UEFI variables, all by default if 'name' is not provided.
231 \-guid guid
232 print only the UEFI variables matching this GUID (any by default)
233 with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
234 \-n
235 suppress dumping variable's value for UEFI.
236
237Run
238~~~
239
240The *env run* command runs commands in an environment variable.
241
242 var
243 name of the variable.
244
245Save
246~~~~
247
248The *env save* command saves the U-Boot environment in persistent storage.
249
250Select
251~~~~~~
252
253The *env select* command selects an U-Boot environment target, it is useful to
254overid the default location when several U-Boot environment backend are
255availables.
256
257 target
258 name of the U-Boot environment backend to select: EEPROM, EXT4, FAT,
259 Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI.
260
261
262Set
263~~~
264
265The *env set* command sets or delete (when 'value' or '-i' are absent)
266U-Boot variable in environment or UEFI variables (when -e is specified).
267
268 name
269 variable name to modify.
270 value
271 when present, set the environment variable 'name' to 'value'
272 when absent, delete the environment variable 'name'.
273 \-f
274 forcibly, overwrite read-only/write-once U-Boot variables.
275 \-e
276 update UEFI variables.
277 \-nv
278 set non-volatile attribute (UEFI).
279 \-bs
280 set boot-service attribute (UEFI).
281 \-rt
282 set runtime attribute (UEFI).
283 \-at
284 set time-based authentication attribute (UEFI).
285 \-a
286 append-write (UEFI).
287 \-i addr:size
288 use <addr,size> as variable's value (UEFI).
289 \-v
290 verbose message (UEFI).
291
292Example
293-------
294
295Print the U-Boot environment variables::
296
297 => env print -a
298 => env print bootcmd stdout
299
300Update environment variable in memory::
301
302 => env set bootcmd "run distro_bootcmd"
303 => env set stdout "serial,vidconsole"
304
305Delete environment variable in memory::
306
307 => env delete bootcmd
308 => env set bootcmd
309
310Reset environment variable to default value, in memory::
311
312 => env default bootcmd
313 => env default ipaddr serverip
314 => env default -a
315
316Save current environment in persistent storage::
317
318 => env save
319
320Restore the default environment in persistent storage::
321
322 => env erase
323
324Create a text snapshot/backup of the current settings in RAM
325(${filesize} can be use to save the snapshot in file)::
326
327 => env export -t ${backup_addr}
328
329Re-import this snapshot, deleting all other settings::
330
331 => env import -d -t ${backup_addr}
332
333Save environment if default enviromnent is used and persistent storage is
334selected::
335
336 => if env info -p -d -q; then env save; fi
337
338Configuration
339-------------
340
341The env command is always available but some sub-commands depend on
342configuration options:
343
344ask
345 CONFIG_CMD_ASKENV
346
347callback
348 CONFIG_CMD_ENV_CALLBACK
349
350edit
351 CONFIG_CMD_EDITENV
352
353exists
354 CONFIG_CMD_ENV_EXISTS
355
356erase
357 CONFIG_CMD_ERASEENV
358
359export
360 CONFIG_CMD_EXPORTENV
361
362flags
363 CONFIG_CMD_ENV_FLAGS
364
365grep
366 CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option
367
368import
369 CONFIG_CMD_IMPORTENV
370
371info
372 CONFIG_CMD_NVEDIT_INFO
373
374load
375 CONFIG_CMD_NVEDIT_LOAD
376
377print
378 CONFIG_CMD_NVEDIT_EFI for UEFI variables support ('-e' option),
379 additionally CONFIG_HEXDUMP to display content of UEFI variables
380
381run
382 CONFIG_CMD_RUN
383
384save
385 CONFIG_CMD_SAVEENV
386
387select
388 CONFIG_CMD_NVEDIT_SELECT
389
390set
391 CONFIG_CMD_NVEDIT_EFI for UEFI variables support ('-e' option)