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

Thu Jan 3 11:03:45 CET 2008

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