[PATCH 1/1] doc: man-page for source command
Heinrich Schuchardt
heinrich.schuchardt at canonical.com
Sat Jan 14 18:41:34 CET 2023
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 at 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 at 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.
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.
> 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.
>
>> +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.
>
> --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
>
More information about the U-Boot
mailing list