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.

9 files changed, 404 insertions, 0 deletions

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.