On 1/14/23 12:41, Heinrich Schuchardt wrote:
On 1/14/23 18:07, Sean Anderson wrote:
On 1/14/23 06:51, Heinrich Schuchardt wrote:
Provide a man-page for the source command.
Signed-off-by: Heinrich Schuchardt <[email protected]>
---
doc/usage/cmd/source.rst | 154 +++++++++++++++++++++++++++++++++++++++
doc/usage/index.rst | 1 +
2 files changed, 155 insertions(+)
create mode 100644 doc/usage/cmd/source.rst
diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst
new file mode 100644
index 0000000000..9622f1d5a8
--- /dev/null
+++ b/doc/usage/cmd/source.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022, Heinrich Schuchardt <[email protected]>
+
+source command
+==============
+
+Synopsis
+--------
+
+::
+
+ source [<addr>][:[<image>]|#[<config>]]
+
+Description
+-----------
+
+The *source* command is used to execute a script file from memory.
+
+Two formats for script files exist:
+
+* legacy U-Boot image format
+* Flat Image Tree (FIT)
+
+Both formats can be created with the mkimage tool.
+
+addr
+ location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR.
+
+image
+ name of an image in a FIT file
+
+config
+ name of a configuration in a FIT file
We need a note here about how these are optional:
Thank you for reviewing.
image
name of an image in a FIT file. May be omitted to pick the default image.
config
name of a configuration in a FIT file. May be omitted to pick the default
config. If addr is not specified, the # must be escaped or quoted to
prevent
it from being interpreted as a comment.
And probably a general note about priorities:
- If : is specified, then *source* will choose an image.
- If # is specified, then *source* will choose an image based on a
configuration.
- If neither : nor # is specified, then *source* will try to choose the image
in the
default configuration. If no configurations are present, then it will pick
the default
image.
And a note about secure boot:
If you are using verified boot, signing keys are required based on the
We nowhere describe what we mean by "verified boot". EFI secure boot is also a
type of verified boot but it does not rely on anything in U-Boot's device-tree.
"U-Boot verified boot"? This is what the uImage stuff calls it.
It think it would be enough to add the reference:
doc/uImage.FIT/signature.txt describes how FIT images including scripts can be
signed and verified.
All text documents in doc/uImage should be converted to restructured text and
added to the HTML documentation.
I agree.
value of the "required"
property in the key's node in U-Boot's device tree. If the value of this property is
"image",
then scripts will always be verified. However, if the value of this node is
"conf", then scripts
will only be verified when a # is specified, as this forces the image to be
determined based on
a configuration. For more information, refer to doc/uImage.FIT/signature.txt.
Additionally, as
is typical, legacy images must be disabled for verified boot, as they do not
support signing.
This is easy to misread.
CONFIG_LEGACY_IMAGE_FORMAT=y does not stop the verification of anything.
Probably you mean:
CONFIG_LEGACY_IMAGE_FORMAT should be disabled a hardened systems as legacy
images cannot be signed.
That works too.
+Examples
+--------
+
+For creating a FIT image an image tree source file (\*.its) is needed. Here is
+an example (source.its).
+
+.. code-block::
+
+ /dts-v1/;
+
+ / {
+ description = "FIT image to test the source command";
+ #address-cells = <1>;
+
+ images {
+ default = "script-1";
+
+ script-1 {
+ data = "echo 1";
We should use /incbin/ here, since that is more typical.
We should mention /incbin/ below. Here I want an example that is trivial to
understand.
+ type = "script";
+ compression = "none";
+ };
+
+ script-2 {
+ data = "echo 2";
+ type = "script";
+ compression = "none";
+ };
+ };
+
+ configurations {
+ default = "conf-2";
+
+ conf-1 {
+ script = "script-1";
+ };
+
+ conf-2 {
+ script = "script-2";
+ };
And omit the second script/config.
I want to be able to demonstrate what #config is used for.
This is not possible without a second config.
We should mention that the configurations node is optional.
+ };
+ };
+
+The FIT image file (boot.itb) is created with:
+
+.. code-block:: bash
+
+ mkimage -f source.its boot.itb
+
+In U-Boot the script can be loaded and execute like this
+
+.. code-block::
+
+ => load host 0:1 $loadaddr boot.itb
+ 1552 bytes read in 0 ms
+ => source $loadaddr#conf-1
+ ## Executing script at 00000000
+ 1
+ => source $loadaddr#conf-2
+ ## Executing script at 00000000
+ 2
+ => source $loadaddr:script1
+ ## Executing script at 00000000
+ Can't find 'script1' FIT subimage
+ => source $loadaddr:script-1
+ ## Executing script at 00000000
+ 1
+ => source $loadaddr:script-2
+ ## Executing script at 00000000
+ 2
+ => source $loadaddr
+ ## Executing script at 00000000
$loadaddr can be omitted, as it is the default
That is why there is the line below.
I mean for all examples. It's important to show : and $ without and addr (or
name), since
it might not be obvious that it's possible to a casual reader.
--Sean
+ 2
+ => source
+ ## Executing script at 00000000
+ 2
+ =>
Here we can mention:
Instead of specifying command line instructions directly in the data property
of the image tree source file another file can be included::
data = /incbin/("./boot.txt");
The configurations node is optional. Here is a minimal example which
encapsulates text the file boot.txt as a FIT script file::
/dts-v1/;
/ {
description = "";
images {
script {
data = /incbin/("./boot.txt");
type = "script";
};
};
};
Best regards
Heinrich
+
+A legacy boot script can be created starting with a text file.
+Here is an example file (boot.txt):
+
+.. code-block:: bash
+
+ echo Hello from a script
+ echo -------------------
+
+The boot scripts (boot.scr) is created with:
+
+.. code-block:: bash
+
+ mkimage -T script -n 'Test script' -d boot.txt boot.scr
+
+The script can be execute in U-boot like this:
+
+.. code-block::
+
+ => load host 0:1 $loadaddr boot.scr
+ 122 bytes read in 0 ms
+ => source $loadaddr
+ ## Executing script at 00000000
+ Hello from a script
+ -------------------
+ => source
+ ## Executing script at 00000000
+ Hello from a script
+ -------------------
+ =>
+
+Configuration
+-------------
+
+The source command is only available if CONFIG_CMD_SOURCE=y.
+The FIT image file format requires CONFIG_FIT=y.#
+The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
+
+Return value
+------------
+
+If the scripts is executed successfully, the return value $? is 0 (true).
+Otherwise it is 1 (false).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index bbd40a6e18..14457aba69 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -74,6 +74,7 @@ Shell commands
cmd/setexpr
cmd/size
cmd/sound
+ cmd/source
cmd/temperature
cmd/tftpput
cmd/true
