Command-line Parsing

The command line is available in U-Boot proper, enabled by CONFIG_CMDLINE which is on by default. It is not enabled in SPL.

There are two different command-line parsers available with U-Boot: the old “simple” one, and the much more powerful “hush” shell:

Simple command-line parser

This takes very little code space and offers only basic features:

  • supports environment variables (through env command)

  • several commands on one line, separated by ‘;’

  • variable substitution using “… ${name} …” syntax

  • special characters (‘$’, ‘;’) can be escaped by prefixing with ‘', for example:

    setenv bootcmd bootm \${address}

  • You can also escape text by enclosing in single apostrophes, for example:

    setenv addip 'setenv bootargs $bootargs ip=$ipaddr:$serverip:$gatewayip:$netmask:$hostname::off'

Hush shell

This is similar to Bourne shell, with control structures like:

  • if… then … else… fi

  • for… do … done

  • while … do … done

  • until … do … done

Hush supports environment (“global”) variables (through setenv / saveenv commands) and local shell variables (through standard shell syntax name=value); only environment variables can be used with the “run” command

The Hush shell is enabled with CONFIG_HUSH_PARSER.

General rules

  1. If a command line (or an environment variable executed by a “run” command) contains several commands separated by semicolon, and one of these commands fails, then the remaining commands will be executed anyway.

  2. If you execute several variables with one call to run (i. e. calling run with a list of variables as arguments), any failing command will cause “run” to terminate, i. e. the remaining variables are not executed.

  3. The variable $? will be set as the return value of any command. The possible values are 0 on success or 1 on any error e. g. invalid syntax or failure of the command. Any exceptions to this are documented by the specific command, e.g. the for command sets $? based on the last command run within the loop.

Representing numbers

Most U-Boot commands use hexadecimal (hex) as the default base, for convenient use of addresses, for example:

=> md 1000 6
00001000: 2c786f62 00697073 03000000 0c000000  box,spi.........
00001010: 67020000 00000000                    ...g....

There is no need to add a 0x prefix to the arguments and the output is shown in hex also, without any prefixes. This helps to avoid clutter.

Some commands use decimal where it is more natural:

=> i2c dev 0
Setting bus to 0
=> i2c speed
Current bus speed=400000
=> i2c speed 100000
Setting bus speed to 100000 Hz

In some cases the default is decimal but it is possible to use octal if that is useful:

pmic dev pmic@41
dev: 1 @ pmic@41
=> pmic write 2 0177
=> pmic read 2
0x02: 0x00007f

It is possible to use a 0x prefix to use a hex value if that is more convenient:

=> i2c speed 0x30000
Setting bus speed to 196608 Hz

Command-line editing

U-Boot supports command-line editing when CONFIG_CMDLINE_EDITING is enabled. This provides an Emacs-like interface for editing commands before they are executed. The following key bindings are available:

Cursor movement

  • Left arrow or Ctrl+B: Move cursor left one character

  • Right arrow or Ctrl+F: Move cursor right one character

  • Ctrl+Left or Alt+B: Move cursor left one word

  • Ctrl+Right or Alt+F: Move cursor right one word

  • Home or Ctrl+A: Move to beginning of line

  • End or Ctrl+E: Move to end of line

Character deletion

  • Backspace or Ctrl+H: Delete character before cursor

  • Delete or Ctrl+D: Delete character at cursor

  • Ctrl+K: Kill (delete) from cursor to end of line

  • Ctrl+W: Kill word before cursor

  • Ctrl+U: Kill entire line

  • Ctrl+X: Kill entire line (same as Ctrl+U)

History

  • Up arrow or Ctrl+P: Previous command in history

  • Down arrow or Ctrl+N: Next command in history

Undo, redo, and yank

When CONFIG_CMDLINE_UNDO is enabled, the following features are available:

  • Ctrl+Z: Undo the last edit operation

  • Ctrl+Shift+Z: Redo the last undone operation

  • Ctrl+Y: Yank (paste) previously killed text

Text killed by Ctrl+K, Ctrl+W, Ctrl+U, or Ctrl+X is saved to a yank buffer and can be pasted with Ctrl+Y.

The number of undo/redo levels can be configured with CONFIG_CMDLINE_UNDO_COUNT (default 1, maximum 64). Each level saves the complete buffer state, so higher values use more memory. Note that any new edit clears the redo history.

Other

  • Tab: Command and argument completion (if CONFIG_AUTO_COMPLETE is enabled)

  • Ctrl+C: Cancel current input

  • Enter: Execute command

Multiline editing

In multiline mode (used by expo text editors), some keys have modified behaviour:

  • Home/End: Move to start/end of current line (not entire buffer)

  • Ctrl+K: Kill to end of current line (not entire buffer)

  • Ctrl+P/N or Up/Down: Navigate between lines

  • Enter: Insert newline (instead of executing)