Merge tag 'doc-2021-04-rc1-2' of https://gitlab.denx.de/u-boot/custodians/u-boot-efi

Pull request for documentation tag doc-2021-04-rc1 (2)

* Man-pages for sbi, exit, for, echo, loady, true, false, conitrace
* Adjust suppression of newline in echo command.
* Provide unit test for echo command.

15 files changed, 501 insertions, 41 deletions

diff --git a/MAINTAINERS b/MAINTAINERS
index a7a62dff81..e7a6dd9ce2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -951,6 +951,7 @@ S:	Maintained
 T:	git https://gitlab.denx.de/u-boot/custodians/u-boot-riscv.git
 F:	arch/riscv/
 F:	cmd/riscv/
+F:	doc/usage/sbi.rst
 F:	drivers/timer/andes_plmt_timer.c
 F:	drivers/timer/sifive_clint_timer.c
 F:	tools/prelink-riscv.c
diff --git a/cmd/echo.c b/cmd/echo.c
index d02a4cfd58..fda844ee9d 100644
--- a/cmd/echo.c
+++ b/cmd/echo.c
@@ -10,47 +10,34 @@
 static int do_echo(struct cmd_tbl *cmdtp, int flag, int argc,
 		   char *const argv[])
 {
-	int i;
-	int putnl = 1;
-
-	for (i = 1; i < argc; i++) {
-		char *p = argv[i];
-		char *nls; /* new-line suppression */
+	int i = 1;
+	bool space = false;
+	bool newline = true;
+
+	if (argc > 1) {
+		if (!strcmp(argv[1], "-n")) {
+			newline = false;
+			++i;
+		}
+	}
 
-		if (i > 1)
+	for (; i < argc; ++i) {
+		if (space) {
 			putc(' ');
-
-		nls = strstr(p, "\\c");
-		if (nls) {
-			char *prenls = p;
-
-			putnl = 0;
-			/*
-			 * be paranoid and guess that someone might
-			 * say \c more than once
-			 */
-			while (nls) {
-				*nls = '\0';
-				puts(prenls);
-				*nls = '\\';
-				prenls = nls + 2;
-				nls = strstr(prenls, "\\c");
-			}
-			puts(prenls);
-		} else {
-			puts(p);
 		}
+		puts(argv[i]);
+		space = true;
 	}
 
-	if (putnl)
+	if (newline)
 		putc('\n');
 
 	return 0;
 }
 
 U_BOOT_CMD(
-	echo,	CONFIG_SYS_MAXARGS,	1,	do_echo,
+	echo, CONFIG_SYS_MAXARGS, 1, do_echo,
 	"echo args to console",
-	"[args..]\n"
-	"    - echo args to console; \\c suppresses newline"
+	"[-n] [args..]\n"
+	"    - echo args to console; -n suppresses newline"
 );
diff --git a/cmd/load.c b/cmd/load.c
index c6a7cc4651..f252c74894 100644
--- a/cmd/load.c
+++ b/cmd/load.c
@@ -1065,25 +1065,25 @@ U_BOOT_CMD(
 U_BOOT_CMD(
 	loadb, 3, 0,	do_load_serial_bin,
 	"load binary file over serial line (kermit mode)",
-	"[ off ] [ baud ]\n"
+	"[ addr [ baud ] ]\n"
 	"    - load binary file over serial line"
-	" with offset 'off' and baudrate 'baud'"
+	" at address 'addr' with baudrate 'baud'"
 );
 
 U_BOOT_CMD(
 	loadx, 3, 0,	do_load_serial_bin,
 	"load binary file over serial line (xmodem mode)",
-	"[ off ] [ baud ]\n"
+	"[ addr [ baud ] ]\n"
 	"    - load binary file over serial line"
-	" with offset 'off' and baudrate 'baud'"
+	" at address 'addr' with baudrate 'baud'"
 );
 
 U_BOOT_CMD(
 	loady, 3, 0,	do_load_serial_bin,
 	"load binary file over serial line (ymodem mode)",
-	"[ off ] [ baud ]\n"
+	"[ addr [ baud ] ]\n"
 	"    - load binary file over serial line"
-	" with offset 'off' and baudrate 'baud'"
+	" at address 'addr' with baudrate 'baud'"
 );
 
 #endif	/* CONFIG_CMD_LOADB */
diff --git a/doc/usage/conitrace.rst b/doc/usage/conitrace.rst
new file mode 100644
index 0000000000..d9916c865e
--- /dev/null
+++ b/doc/usage/conitrace.rst
@@ -0,0 +1,54 @@
+conitrace command
+=================
+
+Synopsis
+--------
+
+::
+
+    conitrace
+
+Description
+-----------
+
+The conitrace command is used to test the correct function of the console input
+driver. It is especially valuable for checking the support for special keys like
+<F1> or <POS1>.
+
+To display escape sequences on a single line the output only advances to the
+next line after detecting a pause of a few milliseconds.
+
+The output is hexadecimal.
+
+Examples
+--------
+
+Entering keys <B><SHIFT-B><CTRL-B><X>
+
+::
+
+    => conitrace
+    Waiting for your input
+    To terminate type 'x'
+    62
+    42
+    02
+    =>
+
+Entering keys <F1><POS1><DEL><BACKSPACE><X>
+
+::
+
+    => conitrace
+    Waiting for your input
+    To terminate type 'x'
+    1b 4f 50
+    1b 5b 48
+    1b 5b 33 7e
+    7f
+    =>
+
+Configuration
+-------------
+
+The conitrace command is only available if CONFIG_CMD_CONITRACE=y.
diff --git a/doc/usage/echo.rst b/doc/usage/echo.rst
new file mode 100644
index 0000000000..861abdfd1e
--- /dev/null
+++ b/doc/usage/echo.rst
@@ -0,0 +1,65 @@
+echo command
+============
+
+Synopsis
+--------
+
+::
+
+    echo [-n] [args ...]
+
+Description
+-----------
+
+The echo command prints its arguments to the console separated by spaces.
+
+-n
+    Do not print a line feed after the last argument.
+
+args
+    Arguments to be printed. The arguments are evaluated before being passed to
+    the command.
+
+Examples
+--------
+
+Strings are parsed before the arguments are passed to the echo command:
+
+::
+
+    => echo "a" 'b' c
+    a b c
+    =>
+
+Observe how variables included in strings are handled:
+
+::
+
+    => setenv var X; echo "a)" ${var} 'b)' '${var}' c) ${var}
+    a) X b) ${var} c) X
+    =>
+
+
+-n suppresses the line feed:
+
+::
+
+    => echo -n 1 2 3; echo a b c
+    1 2 3a b c
+    => echo -n 1 2 3
+    1 2 3=>
+
+A more complex example:
+
+::
+
+    => for i in a b c; do for j in 1 2 3; do echo -n "${i}${j}, "; done; echo; done;
+    a1, a2, a3,
+    b1, b2, b3,
+    c1, c2, c3,
+    =>
+
+Return value
+------------
+
+The return value $? is always set to 0 (true).
diff --git a/doc/usage/exit.rst b/doc/usage/exit.rst
new file mode 100644
index 0000000000..769223c477
--- /dev/null
+++ b/doc/usage/exit.rst
@@ -0,0 +1,40 @@
+exit command
+============
+
+Synopsis
+--------
+
+::
+
+    exit
+
+Description
+-----------
+
+The exit command terminates a script started via the run or source command.
+If scripts are nested, only the innermost script is left.
+
+::
+
+    => setenv inner 'echo entry inner; exit; echo inner done'
+    => setenv outer 'echo entry outer; run inner; echo outer done'
+    => run outer
+    entry outer
+    entry inner
+    outer done
+    =>
+
+When executed outside a script a warning is written. Following commands are not
+executed.
+
+::
+
+    => echo first; exit; echo last
+    first
+    exit not allowed from main input shell.
+    =>
+
+Return value
+------------
+
+$? is always set to 0 (true).
diff --git a/doc/usage/false.rst b/doc/usage/false.rst
new file mode 100644
index 0000000000..a17fe86021
--- /dev/null
+++ b/doc/usage/false.rst
@@ -0,0 +1,28 @@
+false command
+=============
+
+Synopsis
+--------
+
+::
+
+    false
+
+Description
+-----------
+
+The false command sets the return value $? to 1 (false).
+
+Example
+-------
+
+::
+
+    => false; echo $?
+    1
+    =>
+
+Configuration
+-------------
+
+The false command is only available if CONFIG_HUSH_PARSER=y.
diff --git a/doc/usage/for.rst b/doc/usage/for.rst
new file mode 100644
index 0000000000..f9e504979c
--- /dev/null
+++ b/doc/usage/for.rst
@@ -0,0 +1,65 @@
+for command
+===========
+
+Synopis
+-------
+
+::
+
+    for <variable> in <items>; do <commands>; done
+
+Description
+-----------
+
+The for command is used to loop over a list of values and execute a series of
+commands for each of these.
+
+The counter variable of the loop is a shell variable. Please, keep in mind that
+an environment variable takes precedence over a shell variable of the same name.
+
+variable
+    name of the counter variable
+
+items
+    space separated item list
+
+commands
+    commands to execute
+
+Example
+-------
+
+::
+
+    => setenv c
+    => for c in 1 2 3; do echo item ${c}; done
+    item 1
+    item 2
+    item 3
+    => echo ${c}
+    3
+    => setenv c x
+    => for c in 1 2 3; do echo item ${c}; done
+    item x
+    item x
+    item x
+    =>
+
+The first line ensures that there is no environment variable *c*. Hence in the
+first loop the shell variable *c* is printed.
+
+After defining an environment variable of name *c* it takes precedence over the
+shell variable and the environment variable is printed.
+
+Return value
+------------
+
+The return value $? after the done statement is the return value of the last
+statement executed in the loop.
+
+::
+
+    => for i in true false; do ${i}; done; echo $?
+    1
+    => for i in false true; do ${i}; done; echo $?
+    0
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 6def250766..f75bd08237 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -17,5 +17,13 @@ Shell commands
    bootefi
    bootmenu
    button
+   conitrace
+   echo
+   exit
+   false
+   for
+   loady
    mbr
    pstore
+   sbi
+   true
diff --git a/doc/usage/loady.rst b/doc/usage/loady.rst
new file mode 100644
index 0000000000..2819cc72ae
--- /dev/null
+++ b/doc/usage/loady.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+loady command
+=============
+
+Synopsis
+--------
+
+::
+
+    loady [addr [baud]]
+
+Description
+-----------
+
+The loady command is used to transfer a file to the device via the serial line
+using the YMODEM protocol.
+
+The number of transferred bytes is saved in environment variable filesize.
+
+addr
+    load address, defaults to environment variable loadaddr or if loadaddr is
+    not set to configuration variable CONFIG_SYS_LOAD_ADDR
+
+baud
+    baud rate for the ymodem transmission. After the transmission the baud
+    rate is reset to the original value.
+
+Example
+-------
+
+In the example below the terminal emulation program picocom was used to
+transfer a file to the device.
+
+After entering the loady command the key sequence <CTRL-A><CTRL-S> is used to
+let picocom prompt for the file name. Picocom invokes the program sz for the
+file transfer.
+
+::
+
+    => loady 80064000 115200
+    ## Ready for binary (ymodem) download to 0x80064000 at 115200 bps...
+    C
+    *** file: BOOTRISCV64.EFI
+    $ sz -b -vv BOOTRISCV64.EFI
+    Sending: BOOTRISCV64.EFI
+    Bytes Sent: 398976   BPS:7883
+    Sending:
+    Ymodem sectors/kbytes sent:   0/ 0k
+    Transfer complete
+
+    *** exit status: 0 ***
+    /1(CAN) packets, 4 retries
+    ## Total Size      = 0x0006165f = 398943 Bytes
+    => echo ${filesize}
+    6165f
+    =>
+
+Configuration
+-------------
+
+The command is only available if CONFIG_CMD_LOADB=y.
+
+Return value
+------------
+
+The return value $? is always 0 (true).
diff --git a/doc/usage/sbi.rst b/doc/usage/sbi.rst
new file mode 100644
index 0000000000..96d8861057
--- /dev/null
+++ b/doc/usage/sbi.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+sbi command
+===========
+
+Synopsis
+--------
+
+::
+
+    sbi
+
+Description
+-----------
+
+The sbi command is used to display information about the SBI (Supervisor Binary
+Interface) implementation on RISC-V systems.
+
+The output may look like:
+
+::
+
+    => sbi
+    SBI 0.2
+    OpenSBI
+    Extensions:
+      sbi_set_timer
+      sbi_console_putchar
+      sbi_console_getchar
+      sbi_clear_ipi
+      sbi_send_ipi
+      sbi_remote_fence_i
+      sbi_remote_sfence_vma
+      sbi_remote_sfence_vma_asid
+      sbi_shutdown
+      SBI Base Functionality
+      Timer Extension
+      IPI Extension
+      RFENCE Extension
+      Hart State Management Extension
+
+The first line indicates the version of the RISC-V SBI specification.
+The second line indicates the implementation.
+The further lines enumerate the implemented extensions.
+
+Configuration
+-------------
+
+To use the sbi command you must specify CONFIG_CMD_SBI=y.
diff --git a/doc/usage/true.rst b/doc/usage/true.rst
new file mode 100644
index 0000000000..f9ef71b2d1
--- /dev/null
+++ b/doc/usage/true.rst
@@ -0,0 +1,28 @@
+true command
+============
+
+Synopsis
+--------
+
+::
+
+    true
+
+Description
+-----------
+
+The true command sets the return value $? to 0 (true).
+
+Example
+-------
+
+::
+
+    => true; echo $?
+    0
+    =>
+
+Configuration
+-------------
+
+The true command is only available if CONFIG_HUSH_PARSER=y.
diff --git a/include/asm-generic/global_data.h b/include/asm-generic/global_data.h
index 19f70393b4..b6f707e97e 100644
--- a/include/asm-generic/global_data.h
+++ b/include/asm-generic/global_data.h
@@ -198,13 +198,21 @@ struct global_data {
 	 */
 	struct udevice *dm_root_f;
 	/**
-	 * @uclass_root: head of core tree
+	 * @uclass_root_s:
+	 * head of core tree when uclasses are not in read-only memory.
+	 *
+	 * When uclasses are in read-only memory, @uclass_root_s is not used and
+	 * @uclass_root points to the root node generated by dtoc.
 	 */
 	struct list_head uclass_root_s;
 	/**
-	 * @uclass_root: pointer to head of core tree, if uclasses are in
-	 * read-only memory and cannot be adjusted to use @uclass_root as a
-	 * list head.
+	 * @uclass_root:
+	 * pointer to head of core tree, if uclasses are in read-only memory and
+	 * cannot be adjusted to use @uclass_root as a list head.
+	 *
+	 * When not in read-only memory, @uclass_root_s is used to hold the
+	 * uclass root, and @uclass_root points to the address of
+	 * @uclass_root_s.
 	 */
 	struct list_head *uclass_root;
 # if CONFIG_IS_ENABLED(OF_PLATDATA)
diff --git a/test/cmd/Makefile b/test/cmd/Makefile
index 758bc14273..5451e9ea90 100644
--- a/test/cmd/Makefile
+++ b/test/cmd/Makefile
@@ -2,6 +2,9 @@
 #
 # Copyright (c) 2013 Google, Inc
 
+ifdef CONFIG_HUSH_PARSER
+obj-$(CONFIG_CONSOLE_RECORD) += test_echo.o
+endif
 obj-y += mem.o
 obj-$(CONFIG_CMD_MEM_SEARCH) += mem_search.o
 obj-$(CONFIG_CMD_PWM) += pwm.o
diff --git a/test/cmd/test_echo.c b/test/cmd/test_echo.c
new file mode 100644
index 0000000000..4183cf75bb
--- /dev/null
+++ b/test/cmd/test_echo.c
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: GPL-2.0+
+/*
+ * Tests for echo command
+ *
+ * Copyright 2020, Heinrich Schuchadt <xypron.glpk@gmx.de>
+ */
+
+#include <common.h>
+#include <command.h>
+#include <display_options.h>
+#include <test/lib.h>
+#include <test/test.h>
+#include <test/ut.h>
+
+DECLARE_GLOBAL_DATA_PTR;
+
+struct test_data {
+	char *cmd;
+	char *expected;
+};
+
+static struct test_data echo_data[] = {
+	{"echo 1 2 3",
+	 "1 2 3"},
+	/* Test new line handling */
+	{"echo -n 1 2 3; echo a b c",
+	 "1 2 3a b c"},
+	/*
+	 * Test handling of environment variables.
+	 *
+	 * j, q, x are among the least frequent letters in English.
+	 * Hence no collision for the variable name jQx is expected.
+	 */
+	{"setenv jQx X; echo \"a)\" ${jQx} 'b)' '${jQx}' c) ${jQx}; setenv jQx",
+	 "a) X b) ${jQx} c) X"},
+	/* Test handling of shell variables. */
+	{"setenv jQx; for jQx in 1 2 3; do echo -n \"${jQx}, \"; done; echo;",
+	 "1, 2, 3, "},
+};
+
+static int lib_test_hush_echo(struct unit_test_state *uts)
+{
+	int i;
+
+	for (i = 0; i < ARRAY_SIZE(echo_data); ++i) {
+		console_record_reset_enable();
+		ut_assertok(run_command(echo_data[i].cmd, 0));
+		gd->flags &= ~GD_FLG_RECORD;
+		console_record_readline(uts->actual_str,
+					sizeof(uts->actual_str));
+		ut_asserteq_str(echo_data[i].expected, uts->actual_str);
+		ut_assertok(ut_check_console_end(uts));
+	}
+	return 0;
+}
+
+LIB_TEST(lib_test_hush_echo, 0);