[PATCH] Documentation: user: barebox: make barebox chainloading clearer

[PATCH] Documentation: user: barebox: make barebox chainloading clearer

[Ahmad Fatoum]

barebox images are designed to be chainloadable and can be loaded as if
they were a kernel by other bootloaders. The documentation lists
examples for two ways to achieve this with U-Boot preinstalled on the
board. They are not as clear as they could be as the resulting uImage
is called image in the mkimage line, but barebox.bin later on. This is
unfortunate as the build results in a barebox.bin already, which
corresponds to barebox proper in PBL setups. Rename it to barebox.uImage
instead and while at it note that booti isn't applicable to arm32.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/barebox.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst
index c95adb78bb83..80f0f96a98de 100644
--- a/Documentation/user/barebox.rst
+++ b/Documentation/user/barebox.rst
@@ -212,7 +212,8 @@ like a Linux kernel that is passed an external device tree. For example:
 
   U-Boot: tftp $kernel_addr barebox-dt-2nd.img
   U-Boot: tftp $fdt_addr my-board.dtb
-  U-Boot: booti $kernel_addr - $fdt_addr
+  U-Boot: bootm $kernel_addr - $fdt_addr # On 32-bit ARM
+  U-Boot: booti $kernel_addr - $fdt_addr # for other platforms
 
 For non-DT enabled-bootloaders or other architectures, often the normal barebox
 binaries can also be used as they are designed to be startable second stage
@@ -224,7 +225,7 @@ converted to uImage format using the mkimage tool provided with U-Boot:
 .. code-block:: console
 
   sh: mkimage -n barebox -A arm -T kernel -C none -a 0x80000000 -d \
-      build/images/barebox-freescale-imx53-loco.img image
+      build/images/barebox-freescale-imx53-loco.img barebox.uImage
 
 U-Boot expects the start address of the binary to be given in the image using the
 ``-a`` option. The address depends on the board and must be an address which isn't
@@ -233,7 +234,7 @@ image for that board. The image can then be started with ``bootm``:
 
 .. code-block:: console
 
-  U-Boot: tftp $load_addr barebox.bin
+  U-Boot: tftp $load_addr barebox.uImage
   U-Boot: bootm $load_addr
 
 With barebox already running on your board, this can be used to chainload
-- 
2.39.2

Re: [PATCH] Documentation: user: barebox: make barebox chainloading clearer

[Sascha Hauer]

On Wed, Nov 29, 2023 at 12:52:55PM +0100, Ahmad Fatoum wrote:
> barebox images are designed to be chainloadable and can be loaded as if
> they were a kernel by other bootloaders. The documentation lists
> examples for two ways to achieve this with U-Boot preinstalled on the
> board. They are not as clear as they could be as the resulting uImage
> is called image in the mkimage line, but barebox.bin later on. This is
> unfortunate as the build results in a barebox.bin already, which
> corresponds to barebox proper in PBL setups. Rename it to barebox.uImage
> instead and while at it note that booti isn't applicable to arm32.
> 
> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> ---
>  Documentation/user/barebox.rst | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)

Applied, thanks

Sascha

> 
> diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst
> index c95adb78bb83..80f0f96a98de 100644
> --- a/Documentation/user/barebox.rst
> +++ b/Documentation/user/barebox.rst
> @@ -212,7 +212,8 @@ like a Linux kernel that is passed an external device tree. For example:
>  
>    U-Boot: tftp $kernel_addr barebox-dt-2nd.img
>    U-Boot: tftp $fdt_addr my-board.dtb
> -  U-Boot: booti $kernel_addr - $fdt_addr
> +  U-Boot: bootm $kernel_addr - $fdt_addr # On 32-bit ARM
> +  U-Boot: booti $kernel_addr - $fdt_addr # for other platforms
>  
>  For non-DT enabled-bootloaders or other architectures, often the normal barebox
>  binaries can also be used as they are designed to be startable second stage
> @@ -224,7 +225,7 @@ converted to uImage format using the mkimage tool provided with U-Boot:
>  .. code-block:: console
>  
>    sh: mkimage -n barebox -A arm -T kernel -C none -a 0x80000000 -d \
> -      build/images/barebox-freescale-imx53-loco.img image
> +      build/images/barebox-freescale-imx53-loco.img barebox.uImage
>  
>  U-Boot expects the start address of the binary to be given in the image using the
>  ``-a`` option. The address depends on the board and must be an address which isn't
> @@ -233,7 +234,7 @@ image for that board. The image can then be started with ``bootm``:
>  
>  .. code-block:: console
>  
> -  U-Boot: tftp $load_addr barebox.bin
> +  U-Boot: tftp $load_addr barebox.uImage
>    U-Boot: bootm $load_addr
>  
>  With barebox already running on your board, this can be used to chainload
> -- 
> 2.39.2
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |