doc/usage/cmdline.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Command-line Parsing
   4 ====================
   5
   6 The command line is available in U-Boot proper, enabled by CONFIG_CMDLINE which
   7 is on by default. It is not enabled in SPL.
   8
   9 There are two different command-line parsers available with U-Boot:
  10 the old "simple" one, and the much more powerful "hush" shell:
  11
  12 Simple command-line parser
  13 --------------------------
  14
  15 This 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
  29 Hush shell
  30 ----------
  31
  32 This 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
  39 Hush supports environment ("global") variables (through setenv / saveenv
  40 commands) and local shell variables (through standard shell syntax
  41 `name=value`); only environment variables can be used with the "run" command
  42
  43 The Hush shell is enabled with `CONFIG_HUSH_PARSER`.
  44
  45 General 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
  58 Representing numbers
  59 --------------------
  60
  61 Most U-Boot commands use hexadecimal (hex) as the default base, for convenient
  62 use of addresses, for example::
  63
  64   => md 1000 6
  65   00001000: 2c786f62 00697073 03000000 0c000000  box,spi.........
  66   00001010: 67020000 00000000                    ...g....
  67
  68 There is no need to add a `0x` prefix to the arguments and the output is shown
  69 in hex also, without any prefixes. This helps to avoid clutter.
  70
  71 Some 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
  80 In some cases the default is decimal but it is possible to use octal if that is
  81 useful::
  82
  83   pmic dev pmic@41
  84   dev: 1 @ pmic@41
  85   => pmic write 2 0177
  86   => pmic read 2
  87   0x02: 0x00007f
  88
  89 It is possible to use a `0x` prefix to use a hex value if that is more
  90 convenient::
  91
  92   => i2c speed 0x30000
  93   Setting bus speed to 196608 Hz