[PATCH 1/1] doc: man-page for source command
Sean Anderson
seanga2 at gmail.com
Sat Jan 14 18:50:23 CET 2023
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 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.
"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
>>
More information about the U-Boot
mailing list