| Message ID | 20230114115151.59487-1-heinrich.schuchardt@canonical.com |
|---|---|
| State | Superseded |
| Delegated to: | Heinrich Schuchardt |
| Headers | show |
| Series | [1/1] doc: man-page for source command | expand |
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: 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 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. > +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. > + 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. > + }; > + }; > + > +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 --Sean > + 2 > + => source > + ## Executing script at 00000000 > + 2 > + => > + > +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
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. 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 >
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. > >> >> --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 >>
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 >>> >
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 + +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"; + 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"; + }; + }; + }; + +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 + 2 + => source + ## Executing script at 00000000 + 2 + => + +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
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