source.rst 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de>
  3. source command
  4. ==============
  5. Synopsis
  6. --------
  7. ::
  8. source [<addr>][:[<image>]|#[<config>]]
  9. Description
  10. -----------
  11. The *source* command is used to execute a script file from memory.
  12. Two formats for script files exist:
  13. * legacy U-Boot image format
  14. * Flat Image Tree (FIT)
  15. The benefit of the FIT images is that they can be signed and verifed as
  16. described in :doc:`../fit/signature`.
  17. Both formats can be created with the mkimage tool.
  18. addr
  19. location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR.
  20. image
  21. name of an image in a FIT file
  22. config
  23. name of a configuration in a FIT file. A hash sign following white space
  24. starts a comment. Hence, if no *addr* is specified, the hash sign has to be
  25. escaped with a backslash or the argument must be quoted.
  26. If both *image* and *config* are omitted, the default configuration is used, or
  27. if no configuration is defined, the default image.
  28. Examples
  29. --------
  30. FIT image
  31. '''''''''
  32. For creating a FIT image an image tree source file (\*.its) is needed. Here is
  33. an example (source.its).
  34. .. code-block::
  35. /dts-v1/;
  36. / {
  37. description = "FIT image to test the source command";
  38. #address-cells = <1>;
  39. images {
  40. default = "script-1";
  41. script-1 {
  42. data = "echo 1";
  43. type = "script";
  44. compression = "none";
  45. };
  46. script-2 {
  47. data = "echo 2";
  48. type = "script";
  49. compression = "none";
  50. };
  51. };
  52. configurations {
  53. default = "conf-2";
  54. conf-1 {
  55. script = "script-1";
  56. };
  57. conf-2 {
  58. script = "script-2";
  59. };
  60. };
  61. };
  62. The FIT image file (boot.itb) is created with:
  63. .. code-block:: bash
  64. mkimage -f source.its boot.itb
  65. In U-Boot the script can be loaded and execute like this
  66. .. code-block::
  67. => load host 0:1 $loadaddr boot.itb
  68. 1552 bytes read in 0 ms
  69. => source $loadaddr#conf-1
  70. ## Executing script at 00000000
  71. 1
  72. => source $loadaddr#conf-2
  73. ## Executing script at 00000000
  74. 2
  75. => source $loadaddr:script-1
  76. ## Executing script at 00000000
  77. 1
  78. => source $loadaddr:script-2
  79. ## Executing script at 00000000
  80. 2
  81. => source $loadaddr
  82. ## Executing script at 00000000
  83. 2
  84. => source \#conf-1
  85. ## Executing script at 00000000
  86. 1
  87. => source '#conf-1'
  88. ## Executing script at 00000000
  89. 1
  90. => source ':script-1'
  91. ## Executing script at 00000000
  92. 1
  93. => source
  94. ## Executing script at 00000000
  95. 2
  96. =>
  97. Instead of specifying command line instructions directly in the *data* property
  98. of the image tree source file another file can be included. Here is a minimal
  99. example which encapsulates the file boot.txt:
  100. .. code-block::
  101. /dts-v1/;
  102. / {
  103. description = "";
  104. images {
  105. script {
  106. data = /incbin/("./boot.txt");
  107. type = "script";
  108. };
  109. };
  110. };
  111. Legacy U-Boot image
  112. '''''''''''''''''''
  113. A script file using the legacy U-Boot image file format can be created based on
  114. a text file. Let's use this example text file (boot.txt):
  115. .. code-block:: bash
  116. echo Hello from a script
  117. echo -------------------
  118. The boot scripts (boot.scr) is created with:
  119. .. code-block:: bash
  120. mkimage -T script -n 'Test script' -d boot.txt boot.scr
  121. The script can be execute in U-Boot like this:
  122. .. code-block::
  123. => load host 0:1 $loadaddr boot.scr
  124. 122 bytes read in 0 ms
  125. => source $loadaddr
  126. ## Executing script at 00000000
  127. Hello from a script
  128. -------------------
  129. => source
  130. ## Executing script at 00000000
  131. Hello from a script
  132. -------------------
  133. =>
  134. Configuration
  135. -------------
  136. The source command is only available if CONFIG_CMD_SOURCE=y.
  137. The FIT image file format requires CONFIG_FIT=y.#
  138. The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
  139. On hardened systems support for the legacy U-Boot image format should be
  140. disabled as these images cannot be signed and verified.
  141. Return value
  142. ------------
  143. If the scripts is executed successfully, the return value $? is 0 (true).
  144. Otherwise it is 1 (false).