Differences between revisions 30 and 70 (spanning 40 versions)
Revision 30 as of 2016-05-18 09:55:41
Size: 3598
Editor: matej
Comment: link to cubox product page fixed
Revision 70 as of 2022-01-04 21:52:30
Size: 15089
Editor: ?RainerDorsch
Comment: Added a description of /boot/boot.scr
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
## page was renamed from ArmHardFloatPort/CuBox-i
Line 2: Line 3:

<<TableOfContents(3)>>
Line 9: Line 12:
The Cu``Box-i uses U-Boot as a bootloader. As of 2014-03-09, upstream provides [[https://github.com/rabeeh/u-boot-imx6.git|a git tree]] based on U-Boot 2013.10. A port of upstream U-Boot support to 2014.01 (the version in jessie/sid) is available [[https://github.com/vorlonofportland/u-boot.git|here]] and was included in the Debian package u-boot 2014.04-1 (see: Bug:741127).

The Cu``Box-i U-Boot uses SPL (allowing the same U-Boot image to be used across multiple models), and should be installed to the SD card using the layout described [[http://wiki.solid-run.com/Building_the_kernel_and_u-boot_for_the_CuBox-i_and_the_HummingBoard|here]]. Note that this version of U-Boot will also support reading the second-stage bootloader from a FAT filesystem on the first partition of the device; however, since U-Boot also reads its environment from an offset of 384K on the SD card, there is 342K of reserved space at the front of the disk which will be otherwise unused. It is therefore recommended to install U-Boot to the embedded space at the front of the disk, and not to set up a dedicated boot partition on the SD card.
The Cu``Box-i uses [[U-boot|U-Boot]] as a bootloader, and is supported by the U-Boot version in Debian 9/Stretch onwards.

The Debian installer creates the SPL and the U-Boot image with the default environment (=set of environment variables) before the first partition.

See section [[https://wiki.debian.org/InstallingDebianOn/SolidRun/CuBox-i#Upgrading_U-Boot|Upgrading U-Boot]] for the location of SPL and the U-Boot image and Section [[https://wiki.debian.org/InstallingDebianOn/SolidRun/CuBox-i#Printing_the_U-Boot_User_Environment_from_Linux|Printing the U-Boot User Environment from Linux]] for the location of the user environment.
Line 15: Line 20:
The Cu``Box-i should have basic support with the armmp linux kernel (3.16+) in Debian Jessie, including serial console, usb, ethernet, mmc, HDMI, eSATA and ir receiver. To enable additional features, you may need to explore one of the following options:

 * Install a kernel from jessie-backports, stretch, sid or experimental.
 * Apply the [[http://www.home.arm.linux.org.uk/~rmk/cubox/|enablement patches]] to your linux source.
 * Build a kernel from the [[https://github.com/SolidRun/linux-linaro-stable-mx6.git|SolidRun 3.10 stable kernel branch]].
 * Use a pre-built binary kernel image from Solid``Run, available [[http://download.solid-run.com/pub/solidrun/cubox-i/|here]]. (Note: these kernels are based on a Linux 3.0 Android BSP.)
The Cu``Box-i is supported by the armmp linux kernel since version 4.9+ in Debian 9/Stretch including serial console, usb, ethernet, mmc, HDMI, eSATA and ir receiver.
Line 23: Line 23:
Starting from Debian 8.0, the cubox-i and hummingboard are supported through the official [[https://www.debian.org/releases/stable/armhf/ch02s01.html#armhf-armmp-supported-platforms|debian installer]]. Be prepared to attach a serial console to your cubox-i/hummingboard, because the installer does not output messages on the HDMI interface.

In the default configuration after rebooting from the installer the serial console is not(!) enabled. To enable execute

{{{
 echo 'T0:23:respawn:/sbin/getty -L ttymxc0 115200 vt100' >> /etc/inittab
}}}

== Further info ==
Starting from Debian 8/Jessie, the cubox-i and hummingboard are supported through the official [[https://www.debian.org/releases/stable/armhf/ch02s01.en.html#armhf-armmp-supported-platforms|debian installer]].

 * For Debian stable, instructions for pre-build images can be found in the [[https://www.debian.org/releases/stable/armhf/ch05s01.en.html#boot-installer-sd-image|official documentation]] of the Debian Installer.
 * Daily images of the Debian Installer are also available for:
  * [[https://d-i.debian.org/daily-images/armhf/daily/netboot/SD-card-images/|netboot]] installation
  * [[https://d-i.debian.org/daily-images/armhf/daily/hd-media/SD-card-images/|hd-media]] installation

Be prepared to attach a serial console to your cubox-i/hummingboard, because the installer does not output on the HDMI interface. This can be done for example by installing [[DebianPkg:screen|GNU Screen]] and launching:
{{{
screen /dev/ttyUSB0 115200
}}}

The serial console is available both in the installer and after rebooting into a newly installed (buster) system.

An alternative to [[DebianPkg:screen|GNU Screen]] is [[DebianPkg:busybox|busybox microcom]]

{{{
 busybox microcom -d 20 -s 115200 /dev/ttyUSB0
}}}

An important feature to avoid characters when pasting into the u-boot shell is to be able to specify inter-character delays (-d 20 means 20 ms).

== Desktop Environments ==

On Debian 10/Buster [[DebianPkg:GNOME]] defaults to Wayland and works out of the box. Still it is important to boot the kernel with the cma=... parameter set, e.g. cma=256M:
{{{
# echo 'setenv bootargs ${bootargs} cma=256M' | tee /etc/flash-kernel/ubootenv.d/cma && flash-kernel
}}}

See also [[https://wiki.debian.org/InstallingDebianOn/Wandboard#cma|cma entry for the Wandboard]]

= Advanced Topics =

== Modifying the Boot Process ==

Environment variables may be set or modified for the boot process in {{{/etc/flash-kernel/ubootenv.d/}}} e.g. setting a MAC address
{{{
root@home:~# cat /etc/flash-kernel/ubootenv.d/macaddr
# Set the mac address to avoid collisions
setenv ethaddr d0:63:b4:00:32:5c
root@home:~#
}}}

To apply the files, it is required to run {{{flash-kernel}}} as root, which will update {{{/boot/boot.scr}}}

For details see also {{{/etc/flash-kernel/bootscript/bootscr.uboot-generic}}}


== Upgrading U-Boot ==

The U-Boot SPL and the U-Boot environment variables are not updated automatically during an upgrade to a new Debian release and the details how the boot process is implemented depends on the Debian release which was originally installed. For details see [[https://bugs.debian.org/812611|Bug 812611]]

For upgrading the U-Boot SPL and the U-Boot environment install
{{{
# apt install u-boot-imx
}}}
and see {{{/usr/share/doc/u-boot-imx/README.Debian}}}

The new u-boot image may contain updated of the U-Boot default environment. If you have created a user environment you would mask these updates. Therefore it is recommended to implement customizations of the environment in {{{/boot/boot.scr}}} instead of creating a user environment.

A user environement can be invalidated by changing a few bytes and thus invalidating the CRC of the user environment, e.g.
{{{
 dd if=/dev/random of=/dev/mmcblk1 bs=1 seek=1040484 count=4
}}}
This ensures that the default environment in the u-boot image is used.

== Creating a U-Boot User Environment ==

The installer does not create a valid user environment (i.e. it has an invalid CRC), thus always the default environment is used, which typically executes {{{/boot/boot.scr}}} during the boot process. If you create a user environment (typically by the u-boot command {{{saveenv}}} or from Linux using

{{{
rd@bc-text:~$ mkenvimage -s 8192 -o empty_env.img test.env
rd@bc-text:~$ ls -l empty_env.img
-rw-r----- 1 rd rd 8192 Dec 31 19:45 empty_env.img
rd@bc-text:~$ su -
Password:
root@bc-text:~# dd of=/dev/mmcblk1 if=/home/rd/empty_env.img bs=1 seek=1040384 count=8192
8192+0 records in
8192+0 records out
8192 bytes (8.2 kB, 8.0 KiB) copied, 0.0679415 s, 121 kB/s
root@bc-text:~#
}}}

the default environment is ignored entirely. If you ever intend to upgrade U-Boot, it is recommended not to create a user environment, since it would mask the updates in the default environment which comes with the updated the U-Boot image.

== Printing the U-Boot User Environment from Linux ==

Install the tools
{{{
# apt install libubootenv-tool
}}}

Add the location of the user environment to the config file
{{{
root@bc-text:~# cat /etc/fw_env.config
# Configuration file for fw_(printenv/setenv) utility.
# Up to two entries are valid, in this case the redundant
# environment sector is assumed present.


# Device name Device offset Env. size
/dev/mmcblk1 0xFE000 0x2000
root@bc-text:~#
}}}

Dump the environment:
{{{
root@bc-text:~# fw_printenv
arch=arm
baudrate=115200
board=mx6cuboxi
board_name=CUBOXI
[...]
root@bc-text:~#
}}}

Config is derived from:
{{{
root@bc-text:~# zgrep CONFIG_ENV_OFFSET /usr/share/doc/u-boot-imx/configs/config.mx6cuboxi.gz
CONFIG_ENV_OFFSET=0xFE000
root@bc-text:~# zgrep CONFIG_ENV_SIZE /usr/share/doc/u-boot-imx/configs/config.mx6cuboxi.gz
CONFIG_ENV_SIZE=0x2000
root@bc-text:~#
}}}




= Troubleshooting =

== Low Network Bandwith on Ethernet ==
ERR004512 results in a risk of ethernet RX FIFO overrun on the i.MX6 chip in the Cubox-i.

A solid description of the issue and workarounds implemented in the Linux kernel is given at
[[https://boundarydevices.com/i-mx6-ethernet/|Boundarydevices]]

Good news is that is seems that Debian buster contains at least the most relevant patches. But even with these patches, it is required to enable flow control on the switch which connects to the Cubox-i. With flowcontrol I saw bandwidths of around 400 MBit/s for TX and 600 MBit/s for RX with Debian buster (measured by iperf). With Debian stretch I saw that enabling flow control also removes the overflows and increases the measured bandwidth, but it was lower than with the buster installation (even with a backports kernel).

With link level flow control enabled, there should be no RX overruns or dropped frames as shown below:

{{{
rd@home:~$ /sbin/ifconfig eth0
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
        inet6 fe80::d263:b4ff:fe00:325c prefixlen 64 scopeid 0x20<link>
        ether d0:63:b4:00:32:5c txqueuelen 1000 (Ethernet)
        RX packets 133763491 bytes 1832846878 (1.7 GiB)
        RX errors 0 dropped 0 overruns 0 frame 0
        TX packets 11202123 bytes 395662770 (377.3 MiB)
        TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0

rd@home:~$
}}}

Without link level flow control, there may be RX fifo overruns and dropped frames on the cubox ethernet network interface. I have seen bandwidth degradation down to 2 MBit/s on the RX side. I think the latency for retries determines the performance degradation...i.e. on the local networks the bandwidths are still higher if talking to a remote machine on the WAN, severe drops must be expected.

== Boot Process ==

The standard U-Boot boot process executes the {{{boot}}} command, which expands to {{{run bootcmd}}}.

The boot process may be interrupted as described in [[U-boot|U-Boot]]

The boot procedure can now be traced down using the definition of bootcmd and other environment variables, which can be shown using

{{{
=> printenv
}}}

In bullseye, this is a generic procedure which typically ends in the execution of {{{/boot/boot.scr}}}.

=== Steps in Boot Process ===

Loading a kernel is performed in u-boot consists of three essential steps:

1. setting bootargs: kernel parameters are defined in the environment variable, e.g. the root filesystem.
   (Example: {{{ setenv bootargs "enable_wait_mode=off root=UUID=233113e0-67d1-409f-b2c0-57bd496213de rootfstype=ext4 ro rootwait console=ttymxc0,115200 console=tty1 break" }}})
2. Loading kernel, initial ramdisk (initrd.img), and the device tree (dtb) into the ram
   (Example: {{{ load mmc 1:2 ${kernel_addr_r} vmlinuz-${ver} }}})
3. Starting the kernel
   (Example: {{{ bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r} }}})

See also [[https://wiki.debian.org/U-boot#Logging_Commands_used_for_Booting|Logging_Commands used for Booting]] for a description on how to log the commands for a working system.

=== Booting a Kernel manually ===

A simple procedure to start a system installed on a microSD card manually

Determine mmc device and set {{{local_mmcdev}}}:
{{{
=> mmc list
FSL_SDHC: 1 (SD)
FSL_SDHC: 2
=> mmc dev 2
Card did not respond to voltage select! : -110
=> mmc dev 1
switch to partitions #0, OK
mmc1 is current device
=> setenv local_mmcdev 1
=>
}}}

(on an alternative system I get
{{{
CuBox-i U-Boot > mmc list
FSL_SDHC: 0
CuBox-i U-Boot > mmc dev 0
switch to partitions #0, OK
mmc0 is current device
CuBox-i U-Boot >
}}}
)

Show available mmc partitions
{{{
=> mmc part

Partition Map for MMC device 1 -- Partition Type: DOS

Part Start Sector Num Sectors UUID Type
  1 32768 267232 8ad3fb70-01 0c
  2 301056 999424 8ad3fb70-02 83 Boot
  3 1300480 119515136 8ad3fb70-03 83
  4 120817662 1990658 8ad3fb70-04 05 Extd
  5 120817664 1990656 8ad3fb70-05 82
=>
}}}

Find boot partition (you might have to try several partitions):
{{{
=> ext4ls mmc ${local_mmcdev}:2
<DIR> 1024 .
<DIR> 1024 ..
<DIR> 12288 lost+found
          250465 config-5.10.0-10-armmp
         4960768 vmlinuz-5.10.0-10-armmp
<SYM> 26 initrd.img.old
<SYM> 23 vmlinuz.old
<DIR> 1024 dtbs
              83 System.map-5.10.0-10-armmp
<SYM> 26 initrd.img
<SYM> 23 vmlinuz
<SYM> 40 dtb-5.10.0-10-armmp
<SYM> 40 dtb
        23951051 initrd.img-5.10.0-10-armmp
            4499 boot.scr.bak
            4512 boot.scr
=>
}}}

Set boot partition number
{{{
=> setenv local_bootpart 2
}}}

Find root partition (you might have to try several partitions)
{{{
=> ext4ls mmc ${local_mmcdev}:3
<DIR> 4096 .
<DIR> 4096 ..
<DIR> 16384 lost+found
<DIR> 4096 boot
<DIR> 4096 etc
<DIR> 4096 media
<DIR> 4096 var
<SYM> 7 bin
<DIR> 4096 usr
<SYM> 8 sbin
<SYM> 7 lib
<DIR> 4096 dev
<DIR> 4096 home
<DIR> 4096 proc
<DIR> 4096 root
<DIR> 4096 run
<DIR> 4096 sys
<DIR> 4096 tmp
<DIR> 4096 mnt
<DIR> 4096 srv
<DIR> 4096 opt
=>
}}}


Find the partition UUID of the root filesystem
{{{
=> part uuid mmc ${local_mmcdev}:3
8ad3fb70-03
=>
}}}

Set root filesystem to the partition UUID
{{{
=> setenv local_rootfs root=PARTUUID=8ad3fb70-03
=>
}}}

Enable a console on the serial interface
{{{
=> setenv local_bootargs "console=ttymxc0,115200"
=>
}}}

Define bootcmd_local (filesize is set by the load command)
{{{
=> setenv bootcmd_local 'mmc dev ${local_mmcdev} && mmc rescan && setenv bootargs ${local_rootfs} ${local_bootargs} && load mmc ${local_mmcdev}:${local_bootpart} ${kernel_addr_r} vmlinuz-${local_kver} && load mmc ${local_mmcdev}:${local_bootpart} ${fdt_addr_r} dtbs/${local_kver}/imx6q-cubox-i.dtb && load mmc ${local_mmcdev}:${local_bootpart} ${ramdisk_addr_r} initrd.img-${local_kver} && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}'
=>
}}}

Set kernel version to boot:
{{{
=> setenv local_kver "5.10.0-10-armmp"
=>
}}}

Load kernel, device tree, and initrd into RAM and boot Linux zImage stored in RAM
{{{
=> run bootcmd_local
switch to partitions #0, OK
mmc1 is current device
[...]
}}}

The entire process heavily depends that the addresses you load the kernel, device tree, and initial RAM disk are correct. For my cubox-i the bullseye installer uses
{{{
=> printenv kernel_addr_r
kernel_addr_r=0x12000000
=> printenv fdt_addr_r
fdt_addr_r=0x18000000
=> printenv ramdisk_addr_r
ramdisk_addr_r=0x13000000
=>
}}}

{{{${filesize} }}}is set by the load command to the size of the loaded data.


(in previous Debian versions, different addresses have been used
{{{
kernel_addr_r=0x10800000
ramdisk_addr_r=0x11800000
fdt_addr_r=0x18000000
}}}
This caused that my bullseye kernel failed to boot

The error indication was hard to spot, but pointed to that there was something wrong with initrd
{{{
[ 2.313122] Trying to unpack rootfs image as initramfs...
[ 2.313168] Initramfs unpacking failed: invalid magic at start of
compressed archive
[ 2.338783] Freeing initrd memory: 23480K
}}}
)


= Further info =
 * [[https://wiki.gentoo.org/wiki/Cubox-i|The Gentoo Cubox-i Wiki]] contains a lot of useful information

CuBox-i support in Debian

This page exists to collate information about the status of support in Debian for the CuBox-i family of devices by SolidRun (CuBox-i1, CuBox-i2, CuBox-i2Ultra, CuBox-i4Pro).

General information

The CuBox-i devices are a series of small-footprint, always-on computers based on the FreeScale i.MX6 chipset.

Bootloader support

The CuBox-i uses U-Boot as a bootloader, and is supported by the U-Boot version in Debian 9/Stretch onwards.

The Debian installer creates the SPL and the U-Boot image with the default environment (=set of environment variables) before the first partition.

See section Upgrading U-Boot for the location of SPL and the U-Boot image and Section Printing the U-Boot User Environment from Linux for the location of the user environment.

Kernel support

The CuBox-i is supported by the armmp linux kernel since version 4.9+ in Debian 9/Stretch including serial console, usb, ethernet, mmc, HDMI, eSATA and ir receiver.

Installing Debian

Starting from Debian 8/Jessie, the cubox-i and hummingboard are supported through the official debian installer.

  • For Debian stable, instructions for pre-build images can be found in the official documentation of the Debian Installer.

  • Daily images of the Debian Installer are also available for:

Be prepared to attach a serial console to your cubox-i/hummingboard, because the installer does not output on the HDMI interface. This can be done for example by installing GNU Screen and launching:

screen /dev/ttyUSB0 115200

The serial console is available both in the installer and after rebooting into a newly installed (buster) system.

An alternative to GNU Screen is busybox microcom

 busybox microcom -d 20 -s 115200 /dev/ttyUSB0

An important feature to avoid characters when pasting into the u-boot shell is to be able to specify inter-character delays (-d 20 means 20 ms).

Desktop Environments

On Debian 10/Buster GNOME defaults to Wayland and works out of the box. Still it is important to boot the kernel with the cma=... parameter set, e.g. cma=256M:

# echo 'setenv bootargs ${bootargs} cma=256M' | tee /etc/flash-kernel/ubootenv.d/cma  && flash-kernel

See also cma entry for the Wandboard

Advanced Topics

Modifying the Boot Process

Environment variables may be set or modified for the boot process in /etc/flash-kernel/ubootenv.d/ e.g. setting a MAC address

root@home:~# cat /etc/flash-kernel/ubootenv.d/macaddr 
# Set the mac address to avoid collisions
setenv ethaddr d0:63:b4:00:32:5c
root@home:~# 

To apply the files, it is required to run flash-kernel as root, which will update /boot/boot.scr

For details see also /etc/flash-kernel/bootscript/bootscr.uboot-generic

Upgrading U-Boot

The U-Boot SPL and the U-Boot environment variables are not updated automatically during an upgrade to a new Debian release and the details how the boot process is implemented depends on the Debian release which was originally installed. For details see Bug 812611

For upgrading the U-Boot SPL and the U-Boot environment install

# apt install u-boot-imx

and see /usr/share/doc/u-boot-imx/README.Debian

The new u-boot image may contain updated of the U-Boot default environment. If you have created a user environment you would mask these updates. Therefore it is recommended to implement customizations of the environment in /boot/boot.scr instead of creating a user environment.

A user environement can be invalidated by changing a few bytes and thus invalidating the CRC of the user environment, e.g.

 dd if=/dev/random of=/dev/mmcblk1 bs=1 seek=1040484 count=4

This ensures that the default environment in the u-boot image is used.

Creating a U-Boot User Environment

The installer does not create a valid user environment (i.e. it has an invalid CRC), thus always the default environment is used, which typically executes /boot/boot.scr during the boot process. If you create a user environment (typically by the u-boot command saveenv or from Linux using

rd@bc-text:~$ mkenvimage -s 8192 -o empty_env.img test.env 
rd@bc-text:~$ ls -l empty_env.img 
-rw-r----- 1 rd rd 8192 Dec 31 19:45 empty_env.img
rd@bc-text:~$ su -
Password: 
root@bc-text:~# dd of=/dev/mmcblk1 if=/home/rd/empty_env.img bs=1 seek=1040384 count=8192
8192+0 records in
8192+0 records out
8192 bytes (8.2 kB, 8.0 KiB) copied, 0.0679415 s, 121 kB/s
root@bc-text:~#

the default environment is ignored entirely. If you ever intend to upgrade U-Boot, it is recommended not to create a user environment, since it would mask the updates in the default environment which comes with the updated the U-Boot image.

Printing the U-Boot User Environment from Linux

Install the tools

# apt install libubootenv-tool

Add the location of the user environment to the config file

root@bc-text:~# cat /etc/fw_env.config
# Configuration file for fw_(printenv/setenv) utility.
# Up to two entries are valid, in this case the redundant
# environment sector is assumed present.


# Device name           Device offset   Env. size
/dev/mmcblk1            0xFE000         0x2000          
root@bc-text:~# 

Dump the environment:

root@bc-text:~# fw_printenv 
arch=arm
baudrate=115200
board=mx6cuboxi
board_name=CUBOXI
[...]
root@bc-text:~# 

Config is derived from:

root@bc-text:~# zgrep CONFIG_ENV_OFFSET /usr/share/doc/u-boot-imx/configs/config.mx6cuboxi.gz
CONFIG_ENV_OFFSET=0xFE000
root@bc-text:~# zgrep CONFIG_ENV_SIZE /usr/share/doc/u-boot-imx/configs/config.mx6cuboxi.gz
CONFIG_ENV_SIZE=0x2000
root@bc-text:~#

Troubleshooting

Low Network Bandwith on Ethernet

ERR004512 results in a risk of ethernet RX FIFO overrun on the i.MX6 chip in the Cubox-i.

A solid description of the issue and workarounds implemented in the Linux kernel is given at Boundarydevices

Good news is that is seems that Debian buster contains at least the most relevant patches. But even with these patches, it is required to enable flow control on the switch which connects to the Cubox-i. With flowcontrol I saw bandwidths of around 400 MBit/s for TX and 600 MBit/s for RX with Debian buster (measured by iperf). With Debian stretch I saw that enabling flow control also removes the overflows and increases the measured bandwidth, but it was lower than with the buster installation (even with a backports kernel).

With link level flow control enabled, there should be no RX overruns or dropped frames as shown below:

rd@home:~$ /sbin/ifconfig eth0
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet6 fe80::d263:b4ff:fe00:325c  prefixlen 64  scopeid 0x20<link>
        ether d0:63:b4:00:32:5c  txqueuelen 1000  (Ethernet)
        RX packets 133763491  bytes 1832846878 (1.7 GiB)
        RX errors 0  dropped 0  overruns 0  frame 0
        TX packets 11202123  bytes 395662770 (377.3 MiB)
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

rd@home:~$ 

Without link level flow control, there may be RX fifo overruns and dropped frames on the cubox ethernet network interface. I have seen bandwidth degradation down to 2 MBit/s on the RX side. I think the latency for retries determines the performance degradation...i.e. on the local networks the bandwidths are still higher if talking to a remote machine on the WAN, severe drops must be expected.

Boot Process

The standard U-Boot boot process executes the boot command, which expands to run bootcmd.

The boot process may be interrupted as described in U-Boot

The boot procedure can now be traced down using the definition of bootcmd and other environment variables, which can be shown using

=> printenv

In bullseye, this is a generic procedure which typically ends in the execution of /boot/boot.scr.

Steps in Boot Process

Loading a kernel is performed in u-boot consists of three essential steps:

1. setting bootargs: kernel parameters are defined in the environment variable, e.g. the root filesystem.

  • (Example:  setenv bootargs "enable_wait_mode=off root=UUID=233113e0-67d1-409f-b2c0-57bd496213de rootfstype=ext4 ro rootwait console=ttymxc0,115200 console=tty1 break" )

2. Loading kernel, initial ramdisk (initrd.img), and the device tree (dtb) into the ram

  • (Example:  load mmc 1:2 ${kernel_addr_r} vmlinuz-${ver} )

3. Starting the kernel

  • (Example:  bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r} )

See also Logging_Commands used for Booting for a description on how to log the commands for a working system.

Booting a Kernel manually

A simple procedure to start a system installed on a microSD card manually

Determine mmc device and set local_mmcdev:

=> mmc list 
FSL_SDHC: 1 (SD)
FSL_SDHC: 2
=> mmc dev 2
Card did not respond to voltage select! : -110
=> mmc dev 1
switch to partitions #0, OK
mmc1 is current device
=> setenv local_mmcdev 1
=>

(on an alternative system I get

CuBox-i U-Boot > mmc list
FSL_SDHC: 0
CuBox-i U-Boot > mmc dev 0
switch to partitions #0, OK
mmc0 is current device
CuBox-i U-Boot > 

)

Show available mmc partitions

=> mmc part

Partition Map for MMC device 1  --   Partition Type: DOS

Part    Start Sector    Num Sectors     UUID            Type
  1     32768           267232          8ad3fb70-01     0c
  2     301056          999424          8ad3fb70-02     83 Boot
  3     1300480         119515136       8ad3fb70-03     83
  4     120817662       1990658         8ad3fb70-04     05 Extd
  5     120817664       1990656         8ad3fb70-05     82
=>

Find boot partition (you might have to try several partitions):

=> ext4ls mmc ${local_mmcdev}:2
<DIR>       1024 .
<DIR>       1024 ..
<DIR>      12288 lost+found
          250465 config-5.10.0-10-armmp
         4960768 vmlinuz-5.10.0-10-armmp
<SYM>         26 initrd.img.old
<SYM>         23 vmlinuz.old
<DIR>       1024 dtbs
              83 System.map-5.10.0-10-armmp
<SYM>         26 initrd.img
<SYM>         23 vmlinuz
<SYM>         40 dtb-5.10.0-10-armmp
<SYM>         40 dtb
        23951051 initrd.img-5.10.0-10-armmp
            4499 boot.scr.bak
            4512 boot.scr
=>

Set boot partition number

=> setenv local_bootpart 2

Find root partition (you might have to try several partitions)

=> ext4ls mmc ${local_mmcdev}:3
<DIR>       4096 .
<DIR>       4096 ..
<DIR>      16384 lost+found
<DIR>       4096 boot
<DIR>       4096 etc
<DIR>       4096 media
<DIR>       4096 var
<SYM>          7 bin
<DIR>       4096 usr
<SYM>          8 sbin
<SYM>          7 lib
<DIR>       4096 dev
<DIR>       4096 home
<DIR>       4096 proc
<DIR>       4096 root
<DIR>       4096 run
<DIR>       4096 sys
<DIR>       4096 tmp
<DIR>       4096 mnt
<DIR>       4096 srv
<DIR>       4096 opt
=>

Find the partition UUID of the root filesystem

=> part uuid mmc ${local_mmcdev}:3
8ad3fb70-03
=>

Set root filesystem to the partition UUID

=> setenv local_rootfs root=PARTUUID=8ad3fb70-03
=>

Enable a console on the serial interface

=> setenv local_bootargs "console=ttymxc0,115200"
=>

Define bootcmd_local (filesize is set by the load command)

=> setenv bootcmd_local 'mmc dev ${local_mmcdev} && mmc rescan && setenv bootargs ${local_rootfs} ${local_bootargs} && load mmc ${local_mmcdev}:${local_bootpart} ${kernel_addr_r} vmlinuz-${local_kver} && load mmc ${local_mmcdev}:${local_bootpart} ${fdt_addr_r} dtbs/${local_kver}/imx6q-cubox-i.dtb && load mmc ${local_mmcdev}:${local_bootpart} ${ramdisk_addr_r} initrd.img-${local_kver} && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}'
=>   

Set kernel version to boot:

=> setenv local_kver "5.10.0-10-armmp"
=>

Load kernel, device tree, and initrd into RAM and boot Linux zImage stored in RAM

=> run bootcmd_local 
switch to partitions #0, OK
mmc1 is current device
[...]

The entire process heavily depends that the addresses you load the kernel, device tree, and initial RAM disk are correct. For my cubox-i the bullseye installer uses

=> printenv kernel_addr_r
kernel_addr_r=0x12000000
=> printenv fdt_addr_r
fdt_addr_r=0x18000000
=> printenv ramdisk_addr_r
ramdisk_addr_r=0x13000000
=> 

${filesize} is set by the load command to the size of the loaded data.

(in previous Debian versions, different addresses have been used

kernel_addr_r=0x10800000
ramdisk_addr_r=0x11800000
fdt_addr_r=0x18000000

This caused that my bullseye kernel failed to boot

The error indication was hard to spot, but pointed to that there was something wrong with initrd

[    2.313122] Trying to unpack rootfs image as initramfs...
[    2.313168] Initramfs unpacking failed: invalid magic at start of 
compressed archive
[    2.338783] Freeing initrd memory: 23480K

)

Further info