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