[U-Boot-Users] RFC: new bootm syntax

[U-Boot-Users] RFC: new bootm syntax

[Bartlomiej Sieka]

Hello,

As part of adding support for the new uImage format, bootm command will
be reworked quite a bit. Below is a note that summarizes bootm usage
scenarios (present and planned), and defines extensions to bootm
arguments' syntax. The note, or its portions, can be later on added to
the tree as documentation.

Comments and remarks will be much appreciated.

TIA,
Bartlomiej

P.S. Syntax examples given are based on example .its files posted to the
list by Marian Balakowicz on Wed, 19 Dec 2007 15:11:40 +0100 under
"[U-Boot-Users] RFC: New uImage format bindings".



New syntax for bootm
====================

As part of adding support for new uImage format, bootm command (and other
commands as well) will have to understand new syntax of the arguments.
This is necessary in order to specify objects contained in the new
uImage, on which bootm has to operate. This note attempts to first
summarize both current and future bootm usage scenarios, and then
introduces new argument syntax.


bootm usage scenarios
---------------------

The following are the types of arguments to bootm:

A address of old style single image
B address of old style multi image (with two or three components)
C address of new uImage
D new uImage sub-image specification
E new uImage configuration specification
F address in memory

Below is a summary of bootm usage scenarios, focused on booting a PowerPC
Linux kernel. Some of the scenarios exist and are supported already, some
will be extended/added along with the new uImage format. The purpose of
the following list is to document a complete list of supported bootm
usages.

Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old
way, i.e., without passing the Flattened Device Tree (FDT), and new way,
where the kernel is passed a pointer to the FDT. The boot method is
indicated for each scenario.


1.  bootm               boot default image, equivalent to cases 2,3,8

Old uImage:
2.  bootm A             single image, kernel/standalone
3.  bootm B             multi image, kernel+initrd[+fdt]
4.  bootm B -           multi image, kernel[+fdt]
5.  bootm A F           single image, kernel+initrd/standalone+load_addr
6.  bootm A F F         single image, kernel+initrd+fdt
7.  bootm A - F         single image, kernel+fdt

New uImage:
8.  bootm C             default configuration
9.  bootm D             kernel/standalone
10. bootm E             specific configuration
11. bootm D D|F         kernel+initrd/standalone+load_addr
12. bootm D D|F D|F     kernel+initrd+fdt
13. bootm D  -  D|F     kernel+fdt


Additional remarks:

Ad. 1. This is equivalent to cases 2,3,8, depending on what the default
load address points to.
- boot method: see cases 2,3,8

Ad. 2. If A is a kernel image, it is booted. If A is a standalone
application image, it is loaded to the load address specified in the
image, and started.
- boot method: non-FDT

Ad. 3. First and second components of B are assumed to be the kernel and
the initrd, respectively. The kernel is booted with initrd.
- boot method: depends on the number of components in B, and on whether
   U-Boot is compiled with OF support:

                     |          2 components |          3 components |
                     |      (kernel, initrd) | (kernel, initrd, fdt) |
---------------------------------------------------------------------
#ifdef CONFIG_OF_*  |               non-FDT |                   FDT |
#ifndef CONFIG_OF_* |               non-FDT |               non-FDT |

Ad. 4. Similar to case 3, but the kernel is booted without initrd.
Second component of the multi image is irrelevant (it can be a dummy,
1-byte file). Note: currently, U-Boot compiled without OF support does
not handle this case properly, this shall be fixed along with adding
support for new uImage.
- boot method: see case 3

Ad. 5. If A is a kernel image, then F is assumed to be an initrd address,
and the kernel is booted with the initrd. If A is a standalone
application image, F is assumed to be an address in memory that overrides
load address specified in the image. Application is loaded to F and
started.
- boot method: non-FDT

Ad. 6. A is assumed to be a kernel image. Arguments second and third are
assumed to be addresses in memory of initrd and FDT, respectively.
Kernel is booted with initrd.
- boot method: FDT

Ad. 7. A is assumed to be a kernel image and F is assumed to be FDT
address in memory. Kernel is booted without initrd.
- boot method: FDT

Ad. 8. C is assumed to contain a default configuration, which is booted.
- boot method: FDT or non-FDT, depending on whether the default
   configuration defines FDT

Ad. 9. Equivalent to case 2, with the only difference being that the
kernel/standalone application is given as a sub-image specification.
- boot method: non-FDT

Ad. 10. Boot configuration specified in E.
- boot method: FDT or non-FDT, depending on whether the configuration
   given defines FDT

Ad. 11. Equivalent to case 5. If the first argument is a kernel image,
then the second one is assumed to define an initrd (either as a new
uImage sub-image specification, or as a memory address), and the kernel
is booted with the initrd. If the first argument is a standalone
application, then the second argument should be an address in memory that
overrides load address specified in the sub-image. Application is loaded
to this new address and started.
- boot method: non-FDT

Ad. 12. Equivalent to case 6. D is assumed to define a kernel image.
Arguments second and third are assumed to define initrd and FDT,
respectively. Both initrd and FDT can be defined as either new uImage
sub-image specification, or address in memory.  Kernel is booted with
initrd.
- boot method: FDT

Ad. 13. Equivalent to case 7. D is assumed to define a kernel image, and
the third argument is assumed to define FDT (either as a new uImage
sub-image specification, or as an address in memory).
- boot method: FDT


New argument syntax
-------------------

New uImage support introduces two new forms for bootm arguments, with the
following syntax:

- D new uImage sub-image specification
<addr>:<sub-image unit_name>

- E new uImage configuration specification
<addr>#<configuration unit_name>


Examples:

- boot kernel "kernel at 1" stored in a new uImage located at 200000:
bootm 200000:kernel at 1

- boot configuration "cfg at 1" from a new uImage located at 200000:
bootm 200000#cfg at 1

- boot "kernel at 1" from a new uImage at 200000 with initrd "ramdisk at 2"
   found in some other new uImage stored at address 800000:
bootm 200000:kernel at 1 800000:ramdisk at 2

- boot "kernel at 2" from a new uImage at 200000, with initrd "ramdisk at 1"
   and FDT "fdt at 1", both stored in some other new uImage located at
   800000:
bootm 200000:kernel at 1 800000:ramdisk at 1 800000:fdt at 1

- boot kernel "kernel at 2" with initrd "ramdisk at 2", both stored in a new
   uImage at address 200000, with a raw FDT blob stored at address 600000:
bootm 200000:kernel at 2 200000:ramdisk at 2 600000

- boot kernel "kernel at 2" from new uImage at 200000 with FDT "fdt at 1" from
   the same new uImage:
bootm 200000:kernel at 2 - 200000:fdt at 1

[U-Boot-Users] RFC: new bootm syntax

[Wolfgang Denk]

Dear Bartek,

in message <477CB301.8070207@semihalf.com> you wrote:
> 
> A address of old style single image
> B address of old style multi image (with two or three components)
> C address of new uImage
> D new uImage sub-image specification
> E new uImage configuration specification
> F address in memory

What is "address in memory" ? All A...E before are "addresses in
memory", too.

> 1.  bootm               boot default image, equivalent to cases 2,3,8

equivalent to cases 2, 3, 8, 9, amd 10.

There is no such thing as a "default image". bootm without arguments
(like "iminfo") simply uses the last image address set, for example,
by a load command (like tftp).

> Old uImage:
> 2.  bootm A             single image, kernel/standalone

OS image. Maybe Linux Kernel, maybe another OS image (whatever that
may contain).

Not a standalone image. Standalone images  are  supposed  to  be  run
using the "go" command.

> 3.  bootm B             multi image, kernel+initrd[+fdt]

OK.

> 4.  bootm B -           multi image, kernel[+fdt]

OK.

> 5.  bootm A F           single image, kernel+initrd/standalone+load_addr

No, not a single image. These are *two* images: a Linux kernel image
at address A and a ramdisk image at address F.

What do you mean by "+load_addr" ? Looks bogus to me.

> 6.  bootm A F F         single image, kernel+initrd+fdt

No, not a single image. These are *two* images plus a FDT blob.

> 7.  bootm A - F         single image, kernel+fdt

ok.

> New uImage:
> 8.  bootm C             default configuration
> 9.  bootm D             kernel/standalone
> 10. bootm E             specific configuration
> 11. bootm D D|F         kernel+initrd/standalone+load_addr
> 12. bootm D D|F D|F     kernel+initrd+fdt
> 13. bootm D  -  D|F     kernel+fdt

This makes no sense to me. The whole purpose of the new image  format
is  to  make  the image self-describing; I don't see how 8, 9, or 10
would be different. 


> Ad. 1. This is equivalent to cases 2,3,8, depending on what the default
> load address points to.
> - boot method: see cases 2,3,8

See above - it's also identical to cases 9 and 10.

> Ad. 2. If A is a kernel image, it is booted. If A is a standalone
> application image, it is loaded to the load address specified in the
> image, and started.

Note: the officially documented method to start a standalone program
is "go".

> Ad. 3. First and second components of B are assumed to be the kernel and
> the initrd, respectively. The kernel is booted with initrd.

kernel and ramdisk images, to be exact (i. e. with 64 byte U-Boot
header).

Note: U-Boot should be able to pass ramdisk addresses as  is,  i.  e.
without  copy  operation, to the Linux kernel. The kernel.org version
of some architectures (like ARM) does not  support  this  (yet),  but
U-Boot shall continue to support this.

> Ad. 5. If A is a kernel image, then F is assumed to be an initrd address,
> and the kernel is booted with the initrd. If A is a standalone
> application image, F is assumed to be an address in memory that overrides
> load address specified in the image. Application is loaded to F and
> started.

Note: AFAICT the standalone case is not documented.

> Ad. 6. A is assumed to be a kernel image. Arguments second and third are
> assumed to be addresses in memory of initrd and FDT, respectively.
> Kernel is booted with initrd.
> - boot method: FDT

Again, it's kernel and ramdisk images.

> Ad. 8. C is assumed to contain a default configuration, which is booted.
> - boot method: FDT or non-FDT, depending on whether the default
>    configuration defines FDT

The classification is not clear to me. I think I understand what  you
mean,  but  without  actually  using the example notations below it's
completely unclear what the differences between 8, 9 and 10 might be.

C is an image, and it shall be booted, depending on what it contains. 

> Ad. 9. Equivalent to case 2, with the only difference being that the
> kernel/standalone application is given as a sub-image specification.
> - boot method: non-FDT

All this becomes overly complicated....

> - boot kernel "kernel at 1" stored in a new uImage located at 200000:
> bootm 200000:kernel at 1
> 
> - boot configuration "cfg at 1" from a new uImage located at 200000:
> bootm 200000#cfg at 1

> - boot "kernel at 1" from a new uImage at 200000 with initrd "ramdisk at 2"
>    found in some other new uImage stored at address 800000:
> bootm 200000:kernel at 1 800000:ramdisk at 2
> 
> - boot "kernel at 2" from a new uImage at 200000, with initrd "ramdisk at 1"
>    and FDT "fdt at 1", both stored in some other new uImage located at
>    800000:
> bootm 200000:kernel at 1 800000:ramdisk at 1 800000:fdt at 1
> 
> - boot kernel "kernel at 2" with initrd "ramdisk at 2", both stored in a new
>    uImage at address 200000, with a raw FDT blob stored at address 600000:
> bootm 200000:kernel at 2 200000:ramdisk at 2 600000
> 
> - boot kernel "kernel at 2" from new uImage at 200000 with FDT "fdt at 1" from
>    the same new uImage:
> bootm 200000:kernel at 2 - 200000:fdt at 1

I think we should try to keep the syntax simple. Please avoid that we
have to specify the same address more than once. Please continue to
support the notation of the "current" image address, i. e. something
like

	bootm
or
	bootm 400000
or
	bootm 400000 800000

should continue to work, no matter if new or old style images are
being used.

Instead of

	bootm 200000:kernel at 2 - 200000:fdt at 1

we probably should be able to write

	bootm 200000:kernel at 2 - :fdt at 1

or (assuming that the image was just downloaded to 200000)

	bootm :kernel at 2 - :fdt at 1


Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
If the hours are long enough and the pay  is  short  enough,  someone
will say it's women's work.

[U-Boot-Users] RFC: new bootm syntax

[Bartlomiej Sieka]

Hello Wolfgang,

You wrote:
[...]
>> A address of old style single image B address of old style multi
>> image (with two or three components) C address of new uImage D new
>> uImage sub-image specification E new uImage configuration
>> specification F address in memory
> 
> What is "address in memory" ? All A...E before are "addresses in 
> memory", too.

Not true for D and E, but otherwise your comment is valid, the
classification might be confusing. F was meant to be an address in
memory, but not of type A, B, C. I'll probably drop the A-F
classification and use concrete syntax instead.

> 
>> 1.  bootm               boot default image, equivalent to cases
>> 2,3,8
> 
> equivalent to cases 2, 3, 8, 9, amd 10.
> 
> There is no such thing as a "default image". bootm without arguments 
> (like "iminfo") simply uses the last image address set, for example, 
> by a load command (like tftp).

"Default image" meant an image located at address set most recently by a
load command etc, or located at CFG_LOAD_ADDR. Better wording might be
"image at current image address", or something similar. I'll reword this.

> 
>> Old uImage: 2.  bootm A             single image, kernel/standalone
>> 
> 
> OS image. Maybe Linux Kernel, maybe another OS image (whatever that 
> may contain).
> 
> Not a standalone image. Standalone images  are  supposed  to  be  run
>  using the "go" command.

See below for questions on standalone apps.

> 
>> 3.  bootm B             multi image, kernel+initrd[+fdt]
> 
> OK.
> 
>> 4.  bootm B -           multi image, kernel[+fdt]
> 
> OK.
> 
>> 5.  bootm A F           single image,
>> kernel+initrd/standalone+load_addr
> 
> No, not a single image. These are *two* images: a Linux kernel image 
> at address A and a ramdisk image at address F.

A is a single image, as opposed to a mutli-file image.

> 
> What do you mean by "+load_addr" ? Looks bogus to me.

Let's consider the following example:

bootm 200000 10000

If the image at address 200000 is of type IH_TYPE_STANDALONE, then the
current code will use 10000 as the load address, no matter what is
specified in header->ih_load. Then the control will be passed to
header->ih_ep (entry point).

> 
>> 6.  bootm A F F         single image, kernel+initrd+fdt
> 
> No, not a single image. These are *two* images plus a FDT blob.
> 
>> 7.  bootm A - F         single image, kernel+fdt
> 
> ok.
> 
>> New uImage: 8.  bootm C             default configuration 9.  bootm
>> D             kernel/standalone 10. bootm E             specific
>> configuration 11. bootm D D|F
>> kernel+initrd/standalone+load_addr 12. bootm D D|F D|F
>> kernel+initrd+fdt 13. bootm D  -  D|F     kernel+fdt
> 
> This makes no sense to me. The whole purpose of the new image  format
>  is  to  make  the image self-describing; I don't see how 8, 9, or 10
>  would be different.

They are different syntactically:

8. bootm 400000
9. bootm 400000:kernel at 1
10. bootm 400000#cfg at 1

But this will become clearer when A-F notation is dropped.

[...]
>> Ad. 2. If A is a kernel image, it is booted. If A is a standalone 
>> application image, it is loaded to the load address specified in
>> the image, and started.
> 
> Note: the officially documented method to start a standalone program 
> is "go".

Well, there's quite a bit of support for standalone applications outside
of the "go" command. For example current image format has provisions for
it; from include/image.h:
dress of new uImage D new
 >> uImage sub-image specification E new uImag
/*
* Image Types
*
* "Standalone Programs" are directly runnable in the environment
* provided by U-Boot; it is expected that (if they behave
* well) you can continue to work in U-Boot after return from
* the Standalone Program.

Also, do_bootm (as indicated already) knows how to handle and run
standalone applications.

The question now is: what to do with support for standalone apps that is
outside of "go"? Should the code be changed to match the documentation?
I'll be more than happy to remove standalone apps support from both
bootm and old/new image format, as it does not logically belong there,
and unnecessarily complicates the code. What is your opinion on such a
change?

[...]
> I think we should try to keep the syntax simple. Please avoid that we
>  have to specify the same address more than once. Please continue to 
> support the notation of the "current" image address, i. e. something 
> like
> 
> bootm or bootm 400000 or bootm 400000 800000>
> 
> should continue to work, no matter if new or old style images are 
> being used.

Yes, "current" image address notation will be supported with the new
image format. Actually, supporting it is the rationale for having
default configuration in the image. This is needed to specify what
should happen when the image at the "current" address has for example
two kernels, etc.

> 
> Instead of
> 
> bootm 200000:kernel at 2 - 200000:fdt at 1
> 
> we probably should be able to write
> 
> bootm 200000:kernel at 2 - :fdt at 1

OK.

> 
> or (assuming that the image was just downloaded to 200000)
> 
> bootm :kernel at 2 - :fdt at 1

OK.

Thanks for your comments.

Regards,
Bartlomiej

[U-Boot-Users] RFC: new bootm syntax

[Wolfgang Denk]

Dear Bartek,

in message <47837703.6030206@semihalf.com> you wrote:
>
> > What do you mean by "+load_addr" ? Looks bogus to me.
> 
> Let's consider the following example:
> 
> bootm 200000 10000
> 
> If the image at address 200000 is of type IH_TYPE_STANDALONE, then the
> current code will use 10000 as the load address, no matter what is
> specified in header->ih_load. Then the control will be passed to
> header->ih_ep (entry point).

I see. Guess someone should update / extend the documentation...

Any volunteers?

> > This makes no sense to me. The whole purpose of the new image  format
> >  is  to  make  the image self-describing; I don't see how 8, 9, or 10
> >  would be different.
> 
> They are different syntactically:
> 
> 8. bootm 400000
> 9. bootm 400000:kernel at 1
> 10. bootm 400000#cfg at 1
> 
> But this will become clearer when A-F notation is dropped.

Yes, please.

> > Note: the officially documented method to start a standalone program 
> > is "go".
> 
> Well, there's quite a bit of support for standalone applications outside
> of the "go" command. For example current image format has provisions for

I know, but as mentioned above, this is not really documented (which
means a deficiency on the decoumentation).

> it; from include/image.h:
> dress of new uImage D new
>  >> uImage sub-image specification E new uImag
> /*
> * Image Types
> *
> * "Standalone Programs" are directly runnable in the environment
> * provided by U-Boot; it is expected that (if they behave
> * well) you can continue to work in U-Boot after return from
> * the Standalone Program.

I guess there was a problem with what you intended to quote?

> Also, do_bootm (as indicated already) knows how to handle and run
> standalone applications.

Yes, I remember.

> The question now is: what to do with support for standalone apps that is
> outside of "go"? Should the code be changed to match the documentation?

...or vice versa.

> I'll be more than happy to remove standalone apps support from both
> bootm and old/new image format, as it does not logically belong there,
> and unnecessarily complicates the code. What is your opinion on such a
> change?

If I remember correctly, the main reason to add it there was to  take
a  shortcut  instead of implementing a "gunzip" command, or something
like that.

IMO it could be removed there. I agree that it doesn;t logically
belong there.

What do others think?

Best regards,

Wolfgang Denk

-- 
Software Engineering:  Embedded and Realtime Systems,  Embedded Linux
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
When a woman marries again it is because she detested her first  hus-
band.  When  a  man  marries again, it is because he adored his first
wife.                                                  -- Oscar Wilde

[U-Boot-Users] RFC: new bootm syntax

[Bartlomiej Sieka]

Wolfgang Denk wrote:
[...]
>>> Note: the officially documented method to start a standalone program 
>>> is "go".
>> Well, there's quite a bit of support for standalone applications outside
>> of the "go" command. For example current image format has provisions for
> 
> I know, but as mentioned above, this is not really documented (which
> means a deficiency on the decoumentation).
> 
>> it; from include/image.h:
>> dress of new uImage D new
>>  >> uImage sub-image specification E new uImag
>> /*
>> * Image Types
>> *
>> * "Standalone Programs" are directly runnable in the environment
>> * provided by U-Boot; it is expected that (if they behave
>> * well) you can continue to work in U-Boot after return from
>> * the Standalone Program.
> 
> I guess there was a problem with what you intended to quote?

Yes, sorry. I meant:

"
Well, there's quite a bit of support for standalone applications outside
of the "go" command. For example current image format has provisions for
it; from include/image.h:

/*
* Image Types
*
* "Standalone Programs" are directly runnable in the environment
* provided by U-Boot; it is expected that (if they behave
* well) you can continue to work in U-Boot after return from
* the Standalone Program.
"

Regards,
Bartlomiej

[U-Boot-Users] RFC: new bootm syntax v2

[Bartlomiej Sieka]

Bartlomiej Sieka wrote:
[...]
> As part of adding support for the new uImage format, bootm command will
> be reworked quite a bit. Below is a note that summarizes bootm usage
> scenarios (present and planned), and defines extensions to bootm
> arguments' syntax. The note, or its portions, can be later on added to
> the tree as documentation.

Here's a revised note, with the following changes from the first version:
- addressed Wolfgang's comments posted to the list
- dropped support for standalone applications from bootm

Looking forward to any comments, questions, etc.

Thanks,
Bartlomiej



New syntax for bootm (v2)
=========================

As part of adding support for new uImage format, bootm command (and other
commands as well) will have to understand new syntax of the arguments.
This is necessary in order to specify objects contained in the new
uImage, on which bootm has to operate. This note attempts to first
summarize both current and future bootm usage scenarios, and then
introduces new argument syntax.


bootm usage scenarios
---------------------

Below is a summary of bootm usage scenarios, focused on booting a PowerPC
Linux kernel. Some of the scenarios exist and are supported already, some
will be extended/added along with the new uImage format. The purpose of
the following list is to document a complete list of supported bootm
usages.

Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old
way, i.e., without passing the Flattened Device Tree (FDT), and new way,
where the kernel is passed a pointer to the FDT. The boot method is
indicated for each scenario.


1.  bootm               boot image at the current address, equivalent to 
2,3,8

Old uImage:
2.  bootm <addr1>                   /* single image at <addr1> */
3.  bootm <addr1>                   /* multi-image at <addr1>  */
4.  bootm <addr1> -                 /* multi-image at <addr1>  */
5.  bootm <addr1> <addr2>           /* single image at <addr1> */
6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
7.  bootm <addr1> -       <addr3>   /* single image at <addr1> */

New uImage:
8.  bootm <addr1>
9.  bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> -                   [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> -                   <addr3>


Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image
at the current image address.
- boot method: see cases 2,3,8

Ad. 2. Boot kernel image located at <addr1>.ddr1> with initrd loaded 
with ramdisk <subimg2> from the image
at <addr2>.
- boot method: non-FDT

Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the
image at <addr1> with initrd loaded with ramdisk <subimg2> from the image
at <addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
- boot method: FDT

Ad. 13. Similar to case 12, the difference being that <addr3> is the
address of FDT binary blob that is to be passed to the kernel.
- boot method: FDT

Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the
image at <addr1>, without initrd, and pass FDT blob <subimg3> from the
image at <addr3>.
- boot method: FDT

Ad. 15. Similar to case 14, the difference being that <addr3> is the
address of the FDT binary blob that is to be passed to the kernel.
- boot method: FDT


Note on current image address
-----------------------------

When bootm is called without arguments, the image at current image
address is booted. The current image address is the address set most
recently by a load command, etc, and is by default equal to
CFG_LOAD_ADDR. For example, consider the following commands:

tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000

In case of the new uImage argument syntax, the address portion of any
argument can be omitted. If <addr3> is omitted, then it is assumed that
image at <addr2> should be used. Similarly, when <addr2> is omitted, is
is assumed that image at <addr1> should be used. If <addr1> is omitted,
it is assumed that the current image address is to be used. For example
consider the following commands:

tftp 200000 /tftpboot/uImage
bootm :kernel at 1
Last command is equivalent to:
bootm 200000:kernel at 1

tftp 200000 /tftpboot/uImage
bootm 400000:kernel at 1 :ramdisk at 1
Last command is equivalent to:
bootm 400000:kernel at 1 400000:ramdisk at 1

tftp 200000 /tftpboot/uImage
bootm :kernel at 1 400000:ramdisk at 1 :fdt at 1
Last command is equivalent to:
bootm 200000:kernel at 1 400000:ramdisk at 1 400000:fdt at 1
 

[U-Boot-Users] RFC: new bootm syntax v2

[Bartlomiej Sieka]

Bartlomiej Sieka wrote:
> [...]
>> As part of adding support for the new uImage format, bootm command will
>> be reworked quite a bit. Below is a note that summarizes bootm usage
>> scenarios (present and planned), and defines extensions to bootm
>> arguments' syntax. The note, or its portions, can be later on added to
>> the tree as documentation.
> 
> Here's a revised note, with the following changes from the first version:
> - addressed Wolfgang's comments posted to the list
> - dropped support for standalone applications from bootm
> 
> Looking forward to any comments, questions, etc.

Hmm, seems like a portion of the note with new syntax and examples got
lost somehow. I'm resending entire note below, please disregard previous
attempt.

Regards,
Bartlomiej



New syntax for bootm (v2)
=========================

As part of adding support for new uImage format, bootm command (and other
commands as well) will have to understand new syntax of the arguments.
This is necessary in order to specify objects contained in the new
uImage, on which bootm has to operate. This note attempts to first
summarize both current and future bootm usage scenarios, and then
introduces new argument syntax.


bootm usage scenarios
---------------------

Below is a summary of bootm usage scenarios, focused on booting a PowerPC
Linux kernel. Some of the scenarios exist and are supported already, some
will be extended/added along with the new uImage format. The purpose of
the following list is to document a complete list of supported bootm
usages.

Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old
way, i.e., without passing the Flattened Device Tree (FDT), and new way,
where the kernel is passed a pointer to the FDT. The boot method is
indicated for each scenario.


1.  bootm               boot image at the current address, equivalent to 
2,3,8

Old uImage:
2.  bootm <addr1>                   /* single image at <addr1> */
3.  bootm <addr1>                   /* multi-image at <addr1>  */
4.  bootm <addr1> -                 /* multi-image at <addr1>  */
5.  bootm <addr1> <addr2>           /* single image at <addr1> */
6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
7.  bootm <addr1> -       <addr3>   /* single image at <addr1> */

New uImage:
8.  bootm <addr1>
9.  bootm [<addr1>]:<subimg1>
10. bootm [<addr1>]#<conf>
11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
14. bootm [<addr1>]:<subimg1> -                   [<addr3>]:<subimg3>
15. bootm [<addr1>]:<subimg1> -                   <addr3>


Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image
at the current image address.
- boot method: see cases 2,3,8

Ad. 2. Boot kernel image located at <addr1>.
- boot method: non-FDT

Ad. 3. First and second components of the image at <addr1> are assumed to
be a kernel and a ramdisk, respectively. The kernel is booted with initrd
loaded with the ramdisk from the image.
- boot method: depends on the number of components at <addr1>, and on
   whether U-Boot is compiled with OF support:

                     |          2 components |          3 components |
                     |      (kernel, initrd) | (kernel, initrd, fdt) |
---------------------------------------------------------------------
#ifdef CONFIG_OF_*  |               non-FDT |                   FDT |
#ifndef CONFIG_OF_* |               non-FDT |               non-FDT |

Ad. 4. Similar to case 3, but the kernel is booted without initrd.
Second component of the multi-image is irrelevant (it can be a dummy,
1-byte file). Note: currently, U-Boot compiled without OF support does
not handle this case properly, this shall be fixed along with adding
support for new uImage.
- boot method: see case 3

Ad. 5. Boot kernel image located at <addr1> with initrd loaded with
ramdisk from the image at <addr2>.
- boot method: non-FDT

Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address
of a ramdisk image, and <addr3> is the address of a FDT binary blob.
Kernel is booted with initrd loaded with ramdisk from the image at
<addr2>.
- boot method: FDT

Ad. 7. <addr1> is the address of a kernel image and <addr3> is the
address of a FDT binary blob. Kernel is booted without initrd.
- boot method: FDT

Ad. 8. Image at <addr1> is assumed to contain a default configuration,
which is booted.
- boot method: FDT or non-FDT, depending on whether the default
   configuration defines FDT

Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image
at address <addr1>.
- boot method: non-FDT

Ad. 10. Boot configuration <conf> from the image at <addr1>.
- boot method: FDT or non-FDT, depending on whether the configuration
   given defines FDT

Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the
image at <addr1> with initrd loaded with ramdisk <subimg2> from the image
at <addr2>.
- boot method: non-FDT

Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the
image at <addr1> with initrd loaded with ramdisk <subimg2> from the image
at <addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
- boot method: FDT

Ad. 13. Similar to case 12, the difference being that <addr3> is the
address of FDT binary blob that is to be passed to the kernel.
- boot method: FDT

Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the
image at <addr1>, without initrd, and pass FDT blob <subimg3> from the
image at <addr3>.
- boot method: FDT

Ad. 15. Similar to case 14, the difference being that <addr3> is the
address of the FDT binary blob that is to be passed to the kernel.
- boot method: FDT


Note on current image address
-----------------------------

When bootm is called without arguments, the image at current image
address is booted. The current image address is the address set most
recently by a load command, etc, and is by default equal to
CFG_LOAD_ADDR. For example, consider the following commands:

tftp 200000 /tftpboot/kernel
bootm
Last command is equivalent to:
bootm 200000

In case of the new uImage argument syntax, the address portion of any
argument can be omitted. If <addr3> is omitted, then it is assumed that
image at <addr2> should be used. Similarly, when <addr2> is omitted, is
is assumed that image at <addr1> should be used. If <addr1> is omitted,
it is assumed that the current image address is to be used. For example
consider the following commands:

tftp 200000 /tftpboot/uImage
bootm :kernel at 1
Last command is equivalent to:
bootm 200000:kernel at 1

tftp 200000 /tftpboot/uImage
bootm 400000:kernel at 1 :ramdisk at 1
Last command is equivalent to:
bootm 400000:kernel at 1 400000:ramdisk at 1

tftp 200000 /tftpboot/uImage
bootm :kernel at 1 400000:ramdisk at 1 :fdt at 1
Last command is equivalent to:
bootm 200000:kernel at 1 400000:ramdisk at 1 400000:fdt at 1


New argument syntax
-------------------

New uImage support introduces two new forms for bootm arguments, with the
following syntax:

- new uImage sub-image specification
<addr>:<sub-image unit_name>

- new uImage configuration specification
<addr>#<configuration unit_name>


Examples:

- boot kernel "kernel at 1" stored in a new uImage located at 200000:
bootm 200000:kernel at 1

- boot configuration "cfg at 1" from a new uImage located at 200000:
bootm 200000#cfg at 1

- boot "kernel at 1" from a new uImage at 200000 with initrd "ramdisk at 2"
   found in some other new uImage stored at address 800000:
bootm 200000:kernel at 1 800000:ramdisk at 2

- boot "kernel at 2" from a new uImage at 200000, with initrd "ramdisk at 1"
   and FDT "fdt at 1", both stored in some other new uImage located at
   800000:
bootm 200000:kernel at 1 800000:ramdisk at 1 800000:fdt at 1

- boot kernel "kernel at 2" with initrd "ramdisk at 2", both stored in a new
   uImage at address 200000, with a raw FDT blob stored at address 600000:
bootm 200000:kernel at 2 200000:ramdisk at 2 600000

- boot kernel "kernel at 2" from new uImage at 200000 with FDT "fdt at 1" from
   the same new uImage:
bootm 200000:kernel at 2 - 200000:fdt at 1