From 7a4ff7c41bab8b43767eacc0b30ca1573ab6acb1 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 24 Jul 2021 09:03:36 -0600 Subject: doc: Convert command-line info to rST Take this part of the README and put it into rST format. Signed-off-by: Simon Glass --- doc/usage/cmdline.rst | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/usage/index.rst | 1 + 2 files changed, 57 insertions(+) create mode 100644 doc/usage/cmdline.rst (limited to 'doc/usage') diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst new file mode 100644 index 00000000000..b3dbdb8b230 --- /dev/null +++ b/doc/usage/cmdline.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +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 setenv / saveenv commands) +- 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 +------------- + +#. 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. + +#. 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. diff --git a/doc/usage/index.rst b/doc/usage/index.rst index 719b2c90b9d..356f2a56181 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -9,6 +9,7 @@ Use U-Boot fit netconsole partitions + cmdline Shell commands -------------- -- cgit v1.3.1 From 5f4b356121fdb520e4c9bb4fe3483c1a5f93439c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 24 Jul 2021 09:03:37 -0600 Subject: doc: Add a note about number representation Mention the default base of U-Boot in the command-line section. Add examples for decimal and octal. Signed-off-by: Simon Glass --- doc/usage/cmdline.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'doc/usage') diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst index b3dbdb8b230..2d5127c9554 100644 --- a/doc/usage/cmdline.rst +++ b/doc/usage/cmdline.rst @@ -54,3 +54,34 @@ General rules 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. + +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 -- cgit v1.3.1 From e6951139c0544116330b12e287fe45e30bbab11c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sat, 24 Jul 2021 09:03:38 -0600 Subject: lib: Allow using 0x when a decimal value is requested U-Boot mostly uses hex for value input, largely because addresses are much easier to understand in hex. But in some cases a decimal value is requested, such as where the value is small or hex does not make sense in the context. In these cases it is sometimes useful to be able to provide a hex value in any case, if only to resolve any ambiguity. Add this functionality, for increased flexibility. Signed-off-by: Simon Glass --- doc/usage/cmdline.rst | 6 ++++++ include/vsprintf.h | 16 ++++++++++++---- lib/strto.c | 28 +++++++++++++++++----------- test/str_ut.c | 4 ++-- 4 files changed, 37 insertions(+), 17 deletions(-) (limited to 'doc/usage') diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst index 2d5127c9554..88f18c974c8 100644 --- a/doc/usage/cmdline.rst +++ b/doc/usage/cmdline.rst @@ -85,3 +85,9 @@ useful:: => 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 diff --git a/include/vsprintf.h b/include/vsprintf.h index debf977401a..83d187e53d4 100644 --- a/include/vsprintf.h +++ b/include/vsprintf.h @@ -22,8 +22,12 @@ * the end these are ignored. In the worst case, if all characters are invalid, * 0 is returned * - * If @base is 0, octal or hex prefixes are supported (e.g. 0777, 0x123) to - * select a particular base. By default decimal is used. + * A hex prefix is supported (e.g. 0x123) regardless of the value of @base. + * If found, the base is set to hex (16). + * + * If @base is 0: + * - an octal '0' prefix (e.g. 0777) sets the base to octal (8). + * - otherwise the base defaults to decimal (10). */ ulong simple_strtoul(const char *cp, char **endp, unsigned int base); @@ -71,8 +75,12 @@ unsigned long dectoul(const char *cp, char **endp); * * echo will append a newline to the tail. * - * If @base is 0, octal or hex prefixes are supported (e.g. 0777, 0x123) to - * select a particular base. By default decimal is used. + * A hex prefix is supported (e.g. 0x123) regardless of the value of @base. + * If found, the base is set to hex (16). + * + * If @base is 0: + * - an octal '0' prefix (e.g. 0777) sets the base to octal (8). + * - otherwise the base defaults to decimal (10). * * Copied this function from Linux 2.6.38 commit ID: * 521cb40b0c44418a4fd36dc633f575813d59a43d diff --git a/lib/strto.c b/lib/strto.c index b056b205c85..7bba1e3e549 100644 --- a/lib/strto.c +++ b/lib/strto.c @@ -14,19 +14,25 @@ #include /* from lib/kstrtox.c */ -static const char *_parse_integer_fixup_radix(const char *s, unsigned int *base) +static const char *_parse_integer_fixup_radix(const char *s, uint *basep) { - if (*base == 0) { - if (s[0] == '0') { - if (tolower(s[1]) == 'x') - *base = 16; - else - *base = 8; - } else - *base = 10; + /* Look for a 0x prefix */ + if (s[0] == '0') { + int ch = tolower(s[1]); + + if (ch == 'x') { + *basep = 16; + s += 2; + } else if (!*basep) { + /* Only select octal if we don't have a base */ + *basep = 8; + } } - if (*base == 16 && s[0] == '0' && tolower(s[1]) == 'x') - s += 2; + + /* Use decimal by default */ + if (!*basep) + *basep = 10; + return s; } diff --git a/test/str_ut.c b/test/str_ut.c index 0d1bf398099..d2840d51524 100644 --- a/test/str_ut.c +++ b/test/str_ut.c @@ -89,7 +89,7 @@ static int str_simple_strtoul(struct unit_test_state *uts) ut_assertok(run_strtoul(uts, str2, 10, 1099, 4, upper)); ut_assertok(run_strtoul(uts, str2, 16, 0x1099ab, 6, upper)); ut_assertok(run_strtoul(uts, str3, 16, 0xb, 3, upper)); - ut_assertok(run_strtoul(uts, str3, 10, 0, 1, upper)); + ut_assertok(run_strtoul(uts, str3, 10, 0xb, 3, upper)); /* Octal */ ut_assertok(run_strtoul(uts, str6, 0, 63, 3, upper)); @@ -144,7 +144,7 @@ static int str_simple_strtoull(struct unit_test_state *uts) ut_assertok(run_strtoull(uts, str2, 10, 1099, 4, upper)); ut_assertok(run_strtoull(uts, str2, 16, 0x1099ab, 6, upper)); ut_assertok(run_strtoull(uts, str3, 16, 0xb, 3, upper)); - ut_assertok(run_strtoull(uts, str3, 10, 0, 1, upper)); + ut_assertok(run_strtoull(uts, str3, 10, 0xb, 3, upper)); /* Octal */ ut_assertok(run_strtoull(uts, str6, 0, 63, 3, upper)); -- cgit v1.3.1