1.. SPDX-License-Identifier: GPL-2.0+
2
3Command-line Parsing
4====================
5
6The command line is available in U-Boot proper, enabled by CONFIG_CMDLINE which
7is on by default. It is not enabled in SPL.
8
9There are two different command-line parsers available with U-Boot:
10the old "simple" one, and the much more powerful "hush" shell:
11
12Simple command-line parser
13--------------------------
14
15This takes very little code space and offers only basic features:
16
17- supports environment variables (through setenv / saveenv commands)
18- several commands on one line, separated by ';'
19- variable substitution using "... ${name} ..." syntax
20- special characters ('$', ';') can be escaped by prefixing with '\',
21  for example::
22
23    setenv bootcmd bootm \${address}
24
25- You can also escape text by enclosing in single apostrophes, for example::
26
27    setenv addip 'setenv bootargs $bootargs ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname::off'
28
29Hush shell
30----------
31
32This is similar to Bourne shell, with control structures like:
33
34- `if`... `then` ... `else`... `fi`
35- `for`... `do` ... `done`
36- `while` ... `do` ... `done`
37- `until` ... `do` ... `done`
38
39Hush supports environment ("global") variables (through setenv / saveenv
40commands) and local shell variables (through standard shell syntax
41`name=value`); only environment variables can be used with the "run" command
42
43The Hush shell is enabled with `CONFIG_HUSH_PARSER`.
44
45General rules
46-------------
47
48#. If a command line (or an environment variable executed by a "run"
49   command) contains several commands separated by semicolon, and
50   one of these commands fails, then the remaining commands will be
51   executed anyway.
52
53#. If you execute several variables with one call to run (i. e.
54   calling run with a list of variables as arguments), any failing
55   command will cause "run" to terminate, i. e. the remaining
56   variables are not executed.
57
58Representing numbers
59--------------------
60
61Most U-Boot commands use hexadecimal (hex) as the default base, for convenient
62use of addresses, for example::
63
64  => md 1000 6
65  00001000: 2c786f62 00697073 03000000 0c000000  box,spi.........
66  00001010: 67020000 00000000                    ...g....
67
68There is no need to add a `0x` prefix to the arguments and the output is shown
69in hex also, without any prefixes. This helps to avoid clutter.
70
71Some commands use decimal where it is more natural::
72
73  => i2c dev 0
74  Setting bus to 0
75  => i2c speed
76  Current bus speed=400000
77  => i2c speed 100000
78  Setting bus speed to 100000 Hz
79
80In some cases the default is decimal but it is possible to use octal if that is
81useful::
82
83  pmic dev pmic@41
84  dev: 1 @ pmic@41
85  => pmic write 2 0177
86  => pmic read 2
87  0x02: 0x00007f
88
89It is possible to use a `0x` prefix to use a hex value if that is more
90convenient::
91
92  => i2c speed 0x30000
93  Setting bus speed to 196608 Hz
94