[U-Boot,12/13] binman: Add documentation for the symbol feature

Message ID 20171114015506.25673-13-sjg@chromium.org
State New
Delegated to: Simon Glass
Headers show
Series
  • binman: Support run-time access to binman image positions
Related show

Commit Message

Simon Glass Nov. 14, 2017, 1:55 a.m.
Add this feature to the README.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 tools/binman/README | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

Comments

Lukasz Majewski Nov. 14, 2017, 9:35 a.m. | #1
Hi Simon,

> Add this feature to the README.
> 
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
> 
>  tools/binman/README | 32 +++++++++++++++++++++++++++++++-
>  1 file changed, 31 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/binman/README b/tools/binman/README
> index 4ef76c8f089..08c3e56bdef 100644
> --- a/tools/binman/README
> +++ b/tools/binman/README
> @@ -439,6 +439,8 @@ contents of an entry in some way. For example, it
> would be possible to create an entry containing a hash of the
> contents of some other entries. At this stage the position and size
> of entries should not be adjusted. 
> +6. WriteEntryInfo()
> +
>  7. BuildImage() - builds the image and writes it to a file. This is
> the final step.
>  
> @@ -471,6 +473,33 @@ the 'warning' line in scripts/Makefile.lib to
> see what it has found: # u_boot_dtsi_options_debug =
> $(u_boot_dtsi_options_raw) 
>  
> +Access to binman entry positions at run time
> +--------------------------------------------
> +
> +Binman assembles images and determines where each entry is placed in
> the image. +This information may be useful to U-Boot at run time. For
> example, in SPL it +is useful to be able to find the location of
> U-Boot so that it can be executed +when SPL is finished.
> +
> +Binman allows you to declare symbols in the SPL image which are
> filled in +with their correct values during the build. For example:
> +
> +    binman_sym_declare(ulong, u_boot_any, pos);
> +
> +declares a ulong value which will be assigned to the position of any
> U-Boot +image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is
> present in the image. +You can access this value with something like:
> +
> +    ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
> +
> +Thus u_boot_pos will be set to the position of U-Boot in memory,
> assuming that +the whole image has been loaded, or is available in
> flash. You can then jump to +that address to start U-Boot.
> +
> +At present this feature is only supported in SPL. In principle it is
> possible +to fill in such symbols in U-Boot proper, as well.
> +
> +
>  Code coverage
>  -------------
>  
> @@ -543,7 +572,8 @@ To do
>  
>  Some ideas:
>  - Fill out the device tree to include the final position and size of
> each
> -  entry (since the input file may not always specify these)
> +  entry (since the input file may not always specify these). See also
> +  'Access to binman entry positions at run time' above
>  - Use of-platdata to make the information available to code that is
> unable to use device tree (such as a very small SPL image)
>  - Write an image map to a text file

Great feature - thanks Simon.

Reviewed-by: Lukasz Majewski <lukma@denx.de>


Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd@denx.de

Patch

diff --git a/tools/binman/README b/tools/binman/README
index 4ef76c8f089..08c3e56bdef 100644
--- a/tools/binman/README
+++ b/tools/binman/README
@@ -439,6 +439,8 @@  contents of an entry in some way. For example, it would be possible to create
 an entry containing a hash of the contents of some other entries. At this
 stage the position and size of entries should not be adjusted.
 
+6. WriteEntryInfo()
+
 7. BuildImage() - builds the image and writes it to a file. This is the final
 step.
 
@@ -471,6 +473,33 @@  the 'warning' line in scripts/Makefile.lib to see what it has found:
    # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
 
 
+Access to binman entry positions at run time
+--------------------------------------------
+
+Binman assembles images and determines where each entry is placed in the image.
+This information may be useful to U-Boot at run time. For example, in SPL it
+is useful to be able to find the location of U-Boot so that it can be executed
+when SPL is finished.
+
+Binman allows you to declare symbols in the SPL image which are filled in
+with their correct values during the build. For example:
+
+    binman_sym_declare(ulong, u_boot_any, pos);
+
+declares a ulong value which will be assigned to the position of any U-Boot
+image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
+You can access this value with something like:
+
+    ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
+
+Thus u_boot_pos will be set to the position of U-Boot in memory, assuming that
+the whole image has been loaded, or is available in flash. You can then jump to
+that address to start U-Boot.
+
+At present this feature is only supported in SPL. In principle it is possible
+to fill in such symbols in U-Boot proper, as well.
+
+
 Code coverage
 -------------
 
@@ -543,7 +572,8 @@  To do
 
 Some ideas:
 - Fill out the device tree to include the final position and size of each
-  entry (since the input file may not always specify these)
+  entry (since the input file may not always specify these). See also
+  'Access to binman entry positions at run time' above
 - Use of-platdata to make the information available to code that is unable
   to use device tree (such as a very small SPL image)
 - Write an image map to a text file