diff options
Diffstat (limited to 'Documentation/user/booting-linux.rst')
| -rw-r--r-- | Documentation/user/booting-linux.rst | 79 |
1 files changed, 48 insertions, 31 deletions
diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst index 983b56deef..b26ada943a 100644 --- a/Documentation/user/booting-linux.rst +++ b/Documentation/user/booting-linux.rst @@ -19,8 +19,10 @@ architecture the bootm command handles different image types. On ARM the following images are supported: * ARM Linux zImage +* ARM64 Linux Image, plain or compressed * U-Boot uImage * barebox images +* FIT images, containing a zImage or Image The images can either be passed directly to the bootm command as argument or in the ``global.bootm.image`` variable: @@ -48,6 +50,14 @@ variable: global.bootm.image=/path/to/zImage bootm +FIT image configurations will be matched by comparing the ``compatible`` property +inside the configuration node with the barebox live tree's ``/compatible``. +It's also possible to select a specific configuration explicitly: + +.. code-block:: sh + + global.bootm.image=/dev/mmc0.fit@conf-imx8mm-evk.dtb + **NOTE:** it may happen that barebox is probed from the devicetree, but you have want to start a Kernel without passing a devicetree. In this case set the ``global.bootm.boot_atag`` variable to ``true``. @@ -153,22 +163,23 @@ setting the ``global.boot.default`` variable to ``mmc`` and then calling .. _bootloader_spec: -Bootloader Spec -^^^^^^^^^^^^^^^ - -barebox supports booting according to the bootloader spec: +Boot Loader Specification +^^^^^^^^^^^^^^^^^^^^^^^^^ -https://systemd.io/BOOT_LOADER_SPECIFICATION/ +barebox supports booting according to the `Boot Loader Specification +<https://uapi-group.org/specifications/specs/boot_loader_specification/>`__ +(sometimes also known as *Bootloader Spec*, *bootspec* or *blspec*). It follows another philosophy than the :ref:`boot_entries`. With Boot Entries booting is completely configured in the bootloader. Bootloader Spec Entries -on the other hand the boot entries are on a boot medium. This gives a boot medium -the possibility to describe where a Kernel is and what parameters it needs. +on the other hand are part of the boot medium. This gives a boot medium +the possibility to describe where a kernel is located and which parameters are +needed to boot it. -All Bootloader Spec Entries are in a partition on the boot medium under ``/loader/entries/*.conf``. -In the Bootloader Spec a boot medium has a dedicated partition to use for -boot entries. barebox is less strict, it accepts Bootloader Spec Entries on -every partition barebox can read. +All Bootloader Spec Entries are located in a partition on the boot medium under +``/loader/entries/*.conf``. According to the Bootloader Spec, a boot medium has +to use a dedicated partition for boot entries. barebox is less strict, it +accepts Bootloader Spec Entries on every partition that barebox can read. A Bootloader Spec Entry consists of key value pairs:: @@ -184,7 +195,7 @@ A Bootloader Spec Entry consists of key value pairs:: All paths are absolute paths in the partition. Bootloader Spec Entries can be created manually, but there also is the ``scripts/kernel-install`` tool to create/list/modify entries directly on a MMC/SD card or other media. To use -it create a SD card / USB memory stick with a /boot partition with type 0xea. +it, create an SD card / USB memory stick with a ``/boot`` partition with type ``0xea``. The partition can be formatted with FAT or EXT4 filesystem. If you wish to write to it from barebox later you must use FAT. The following creates a Bootloader Spec Entry on a SD card: @@ -196,9 +207,9 @@ Spec Entry on a SD card: --kernel=/home/sha/linux/arch/arm/boot/zImage --add-root-option \ --root=/dev/mmcblk0p1 -o "console=ttymxc0,115200" -The entry can be listed with the -l option: +The entry can be listed with the ``-l`` option: -.. code-block:: sh +.. code-block:: none scripts/kernel-install --device=/dev/mmcblk0 -l @@ -209,28 +220,34 @@ The entry can be listed with the -l option: options: console=ttymxc0,115200 root=PARTUUID=0007CB20-01 linux: 11ab7c89d02c4f66a4e2474ea25b2b84.15/linux -When on barebox the SD card shows up as ``mmc1`` then this entry can be booted with -``boot mmc1`` or with setting ``global.boot.default`` to ``mmc1``. - -``machine-id`` is an optional key. If ``global.boot.machine_id`` variable is set to -non-empty value, then barebox accepts only Bootloader Spec entries with ``machine-id`` -key. In case if value of global variable and Bootloader Spec key match each other, -barebox will choose the boot entry for booting. All other Bootloader Spec entries will -be ignored. +When the SD card shows up as ``mmc1`` in barebox, this entry can be booted with +``boot mmc1`` or by setting ``global.boot.default`` to ``mmc1``. -A bootloader spec entry can also reside on an NFS server in which case a RFC2224 -compatible NFS URI string must be passed to the boot command: +A bootloader spec entry can also reside on an NFS server, in which case an +`RFC 2224 <https://datatracker.ietf.org/doc/html/rfc2224>`__-compatible NFS URI +must be passed to the boot command: .. code-block:: sh boot nfs://nfshost[:port]//path/ -Additionally to the options defined in the original spec barebox understands the -``linux-appendroot`` option. This is a boolean value and if set to ``true`` barebox -will automatically append a ``root=`` string to the Linux commandline based on the -device where the entry is found on. This makes it possible to use the same rootfs -image on different devices without having to specify a different root= option each -time. +Additional notes about keys in the bootloader spec entries: + +``machine-id`` + This key is optional. If the ``global.boot.machine_id`` variable is set to a + non-empty value, barebox will only boot the Bootloader Spec Entry whose + ``machine-id`` key matches the ``global.boot.machine_id`` variable. All + other Bootloader Spec entries will be ignored. + +``linux-appendroot`` + This boolean option is understood by Barebox although it is not part of the + original specification. If set to ``true``, barebox will automatically append + a ``root=`` string to the Linux commandline based on the device where the + entry is found on. This makes it possible to use the same rootfs image on + different devices without having to specify a different ``root=`` option each + time. + +.. _booting_linux_net: Network boot ------------ @@ -274,7 +291,7 @@ In any case, make sure that the specified mountpoint is exported by your NFS server. For more information about booting with ``nfsroot``, see -`Documentation/filesystems/nfs/nfsroot.txt <https://github.com/torvalds/linux/blob/master/Documentation/filesystems/nfs/nfsroot.txt>`__ +`Documentation/admin-guide/nfs/nfsroot.rst <https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/nfs/nfsroot.rst>`__ in the Linux kernel documentation. If the preconfigured paths or names are not suitable, they can be adjusted in |