On 1/14/23 18:50, Sean Anderson wrote:
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 heinrich.schuchardt@canonical.com
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 xypron.glpk@gmx.de
+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.
We can add more examples:
=> source #conf-1 ## Executing script at 00000000 1 => source '#conf-1' ## Executing script at 00000000 1 => source :script-1 ## Executing script at 00000000 1
Best regards
Heinrich
--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