~funderscore blog cgit wiki get in touch
aboutsummaryrefslogtreecommitdiff
blob: 1bebfa4e710b13d9adee4ab1427cad9d7c12248c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
.. SPDX-License-Identifier: GPL-2.0-or-later:

env command
===========

Synopsis
--------

::

	env ask name [message] [size]
	env callbacks
	env default [-f] (-a | var [...])
	env delete [-f] var [...]
	env edit name
	env exists name
	env export [-t | -b | -c] [-s size] addr [var ...]
	env flags
	env grep [-e] [-n | -v | -b] string [...]
	env import [-d] [-t [-r] | -b | -c] addr [size] [var ...]
	env info [-d] [-p] [-q]
	env print [-a | name ...]
	env print -e [-guid guid] [-n] [name ...]
	env run var [...]
	env save
	env erase
	env load
	env select [target]
	env set [-f] name [value]
	env set -e [-nv][-bs][-rt][-at][-a][-i addr:size][-v] name [value]

Description
-----------

The *env* commands is used to handle the U-Boot (:doc:`../environment`) or
the UEFI variables.

The next commands are kept as alias and for compatibility:

+ *editenv* = *env edit*
+ *grepenv* = *env grep*
+ *setenv* = *env set*
+ *askenv* = *env ask*
+ *run* = *env run*

Ask
~~~

The *env ask* command asks for the new value of an environment variable
(alias :doc:`askenv`).

    name
        name of the environment variable.

    message
        message to be displayed while the command waits for the value to be
        entered from stdin. If no message is specified, a default message
        "Please enter name:" will be displayed.

    size
        maximum number of characters that will be stored in the environment
        variable name. This is in decimal number format (unlike in
        other commands where size values are hexa-decimal). The default
        value of size is 1023 (CONFIG_SYS_CBSIZE - 1).

Callbacks
~~~~~~~~~

The *env callbacks* command prints callbacks and their associated variables.

Default
~~~~~~~

The *env default* command resets the selected variables in the U-Boot
environment to their default values.

    var
        list of variable name.
    \-a
        all U-Boot environment.
    \-f
        forcibly, overwrite read-only/write-once variables.

Delete
~~~~~~

The *env delete* command deletes the selected variables from the U-Boot
environment.

    var
        name of the variable to delete.
    \-f
        forcibly, overwrite read-only/write-once variables.

Edit
~~~~

The *env edit* command edits an environment variable.

    name
        name of the variable.

Exists
~~~~~~

The *env exists* command tests for existence of variable.

    name
        name of the variable.

Export
~~~~~~

The *env export* command exports the U-Boot environment in memory; on success,
the variable $filesize will be set.

    addr
        memory address where environment gets stored.
    var
        list of variable names that get included into the export.
        Without arguments, the whole environment gets exported.
    \-b
        export as binary format (name=value pairs separated by
        list end marked by double "\0\0").
    \-t
        export as text format; if size is given, data will be
        padded with '\0' bytes; if not, one terminating '\0'
        will be added.
    \-c
        Export as checksum protected environment format as used by
        'env save' command.
    \-s size
        size of output buffer.

Flags
~~~~~

The *env flags* command prints variables that have non-default flags.

Grep
~~~~

The *env grep* command searches environment, list environment name=value pairs
matching the requested 'string'.

    string
        string to search in U-Boot environment.
    \-e
        enable regular expressions.
    \-n
        search string in variable names.
    \-v
        search string in vairable values.
    \-b
        search both names and values (default).

Import
~~~~~~

The *env import* command imports environment from memory.

    addr
        memory address to read from.
    size
        length of input data; if missing, proper '\0' termination is mandatory
        if var is set and size should be missing (i.e. '\0' termination),
        set size to '-'.
    var
        List of the names of the only variables that get imported from
        the environment at address 'addr'. Without arguments, the whole
        environment gets imported.
    \-d
        delete existing environment before importing if no var is passed;
        if vars are passed, if one var is in the current environment but not
        in the environment at addr, delete var from current environment;
        otherwise overwrite / append to existing definitions.
    \-t
        assume text format; either "size" must be given or the text data must
        be '\0' terminated.
    \-r
        handle CRLF like LF, that means exported variables with a content which
        ends with \r won't get imported. Used to import text files created with
        editors which are using CRLF for line endings.
        Only effective in addition to -t.
    \-b
        assume binary format ('\0' separated, "\0\0" terminated).
    \-c
        assume checksum protected environment format.

Info
~~~~

The *env info* command displays (without argument) or evaluates the U-Boot
environment information.

    \-d
        evaluate if the default environment is used.
    \-p
        evaluate if environment can be persisted.
    \-q
        quiet output,  use only for command result, by example with
        'test' command.

Print
~~~~~

The *env print* command prints the selected variables in U-Boot environment or
in UEFI variables.

    name
        list of variable name.
    \-a
        all U-Boot environment, when 'name' is absent.
    \-e
        print UEFI variables, all by default when 'name'.
    \-guid guid
        print only the UEFI variables matching this GUID (any by default)
        with guid format = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
    \-n
         suppress dumping variable's value for UEFI.

Run
~~~

The *env run* command runs commands in an environment variable.

    var
        name of the variable.

Save
~~~~

The *env save* command saves the U-Boot environment in persistent storage.

Erase
~~~~~

The *env erase* command erases the U-Boot environment.

Load
~~~~

The *env load* command loads the U-Boot environment from persistent storage.

Select
~~~~~~

The *env select* command selects an U-Boot environment target, it is useful to
overid the default location when several U-Boot environment backend are
availables.

    target
        name of the U-Boot environment backend to select: EEPROM, EXT4, FAT,
        Flash, MMC, NAND, nowhere, NVRAM, OneNAND, Remote, SATA, SPIFlash, UBI.


Set
~~~

The *env set* command sets or delete (when 'value' or '-i' are absent)
U-Boot variable in environment or UEFI variables (when -e is specified).

    name
        variable name to modify.
    value
        when present, set the environment variable 'name' to 'value'
        when absent, delete the environment variable 'name'.
    \-f
        forcibly, overwrite read-only/write-once U-Boot variables.
    \-e
        update UEFI variables.
    \-nv
        set non-volatile attribute (UEFI).
    \-bs
        set boot-service attribute (UEFI).
    \-rt
        set runtime attribute (UEFI).
    \-at
        set time-based authentication attribute (UEFI).
    \-a
        append-write (UEFI).
    \-i addr:size
        use <addr,size> as variable's value (UEFI).
    \-v
        verbose message (UEFI).

Example
-------

Print the U-Boot environment variables::

    => env print -a
    => env print bootcmd stdout

Update environment variable in memory::

    => env set bootcmd "run distro_bootcmd"
    => env set stdout "serial,vidconsole"

Delete environment variable in memory::

    => env delete bootcmd
    => env set bootcmd

Reset environment variable to default value, in memory::

    => env default bootcmd
    => env default -a

Save current environment in persistent storage::

    => env save

Restore the default environment in persistent storage::

    => env erase

Create a text snapshot/backup of the current settings in RAM
(${filesize} can be use to save the snapshot in file)::

    => env export -t ${backup_addr}

Re-import this snapshot, deleting all other settings::

    => env import -d -t ${backup_addr}

Save environment if default enviromnent is used and persistent storage is
selected::

    => if env info -p -d -q; then env save; fi

Configuration
-------------

The env command is always available but some sub-commands depend on
configuration options:

ask
    CONFIG_CMD_ASKENV

callback
    CONFIG_CMD_ENV_CALLBACK

edit
    CONFIG_CMD_EDITENV

exists
    CONFIG_CMD_ENV_EXISTS

flsgs
    CONFIG_CMD_ENV_FLAGS

erase
    CONFIG_CMD_ERASEENV

export
    CONFIG_CMD_EXPORTENV

grep
    CONFIG_CMD_GREPENV, CONFIG_REGEX for '-e' option

import
    CONFIG_CMD_IMPORTENV

info
    CONFIG_CMD_NVEDIT_INFO

load
    CONFIG_CMD_NVEDIT_LOAD

run
    CONFIG_CMD_RUN

save
    CONFIG_CMD_SAVEENV

select
    CONFIG_CMD_NVEDIT_SELECT

set, print
    CONFIG_CMD_NVEDIT_EFI for '-e' option