Differences between revisions 2 and 14 (spanning 12 versions)
Revision 2 as of 2016-12-17 13:03:10
Size: 4142
Editor: ?VagrantCascadian
Comment: Add link to Status page.
Revision 14 as of 2021-12-31 08:04:36
Size: 9709
Editor: ?RainerDorsch
Comment: Added links to u-boot upstream documentation
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= General Information =
Line 4: Line 5:
<<TableOfContents(2)>>

= Support in Debian =
Line 11: Line 14:
  https://anonscm.debian.org/cgit/collab-maint/u-boot.git/tree/debian/targets

There may also be a newer version of this file in the most recent
experimental branch.
  https://salsa.debian.org/debian/u-boot/blob/master/debian/targets
Line 21: Line 21:
You can subscribe to
get notifications of uploads by emailing "pts@qa.debian.org" with the
following:

{{{
subscribe u-boot email@example.com
keyword u-boot email@example.com upload-source
}}}

For more details, see:

  https://www.debian.org/doc/manuals/developers-reference/resources.html#pts-commands
You can subscribe to get notifications by subscribing on the package [[https://tracker.debian.org/pkg/u-boot|tracker]] page.
Line 58: Line 46:
= Troubleshooting, debugging =
== Using a serial console ==
Line 63: Line 52:
cable. When booting u-boot from serial console, you should see output cable.

There are several console terminal programs in Debian that can attach to a serial connection, for example [[DebianPkg:screen|GNU Screen]].

For a serial port you would use something like (please adapt to your serial adapter name in `/dev`):
{{{
screen /dev/ttyS0 115200
}}}
And for an USB-TTL adapter:
{{{
screen /dev/ttyUSB0 115200
}}}

When booting u-boot from serial console, you should see output
Line 112: Line 114:

== U-boot prompt, custom kernel arguments ==
Additional kernel arguments can be given from u-boot before booting into the system by stopping normal boot and dropping to the u-boot prompt.

When started and before booting into the OS u-boot will show a 3 seconds countdown:
{{{
Hit any key to stop autoboot: 2
}}}
Hit any key from the serial console to interrupt boot to drop to the u-boot prompt: "`=>`"

From there you can add custom kernel arguments by adding aguments to the `bootargs` variable.
For example to bypass the installed init system and drop to a root shell you may use:
{{{
=> setenv bootargs ${bootargs} init=/bin/bash
=> boot
}}}

or boot an older kernel which is still installed by setting {{{fk_kvers}}} e.g.
{{{
=> setenv fk_kvers 4.19.0-18-armmp
}}}

More information about available commands can be obtained from the `help` command.


== Checking the environment ==
Line 121: Line 149:
unsure, you can run "env default -a" to reset the running environment,
followed by "boot".
unsure, you can run `env default -a` to reset the running environment,
followed by `boot`.

== Logging Commands used for Booting ==

Sometimes it is useful to log the commands and kernel, initrd.img, and DTB addresses which boot a newly installed system to debug the boot system a similar system. A typical usecase is that u-boot breaks for a release/kernel. Installing on a different media a new Debian system might help to get the upgraded system booting again.

Adding the two echos in {{{/etc/flash-kernel/bootscript/bootscr.uboot-generic}}} should reveal the standard u-boot boot commands
{{{
rd@bc-text:~$ cat /etc/flash-kernel/bootscript/bootscr.uboot-generic
[...]
for pathprefix in ${fk_image_locations}
do
  if test -e ${devtype} ${devnum}:${partition} ${pathprefix}vmlinuz-${fk_kvers}
  then
    echo bootargs: ${bootargs}
    echo "load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz-${fk_kvers} \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}${fdtpath} \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img-${fk_kvers} \
    && echo Booting Debian ${fk_kvers} from ${devtype} ${devnum}:${partition}... \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}"
    load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz-${fk_kvers} \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}${fdtpath} \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img-${fk_kvers} \
    && echo "Booting Debian ${fk_kvers} from ${devtype} ${devnum}:${partition}..." \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}
  fi
done

for pathprefix in ${fk_image_locations}
do
  if test -e ${devtype} ${devnum}:${partition} ${pathprefix}vmlinuz
  then
    load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}dtb \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img \
    && echo "Booting Debian from ${devtype} ${devnum}:${partition}..." \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}
  fi
done
rd@bc-text:~$
}}}

Recreate {{{/boot/boot.scr}}}
{{{
root@bc-text:~# flash-kernel
Using DTB: imx6q-cubox-i.dtb
Installing /usr/lib/linux-image-5.10.0-10-armmp/imx6q-cubox-i.dtb into /boot/dtbs/5.10.0-10-armmp/./imx6q-cubox-i.dtb
Taking backup of imx6q-cubox-i.dtb.
Installing new imx6q-cubox-i.dtb.
flash-kernel: installing version 5.10.0-10-armmp
Generating boot script u-boot image... done.
Taking backup of boot.scr.
Installing new boot.scr.
root@bc-text:~#
}}}

Reboot the system and monitor the u-boot output on a serial console
{{{
Hit any key to stop autoboot: 0
switch to partitions #0, OK
mmc1 is current device
Scanning mmc 1:2...
Found U-Boot script /boot.scr
4095 bytes read in 2 ms (2 MiB/s)
## Executing script at 12000000
bootargs: console=ttymxc0,115200
load mmc 1:2 0x12000000 /vmlinuz-5.10.0-10-armmp && load mmc 1:2 0x18000000 /dtbs/5.10.0-10-armmp/imx6q-cubox-i.dtb && load mmc 1:2 0x13000000 /initrd.img-5.10.0-10-armmp && echo Booting Debian 5.10.0-10-armmp from mmc 1:2... && bootz 0x12000000 0x13000000:fff 0x18000000
4960768 bytes read in 244 ms (19.4 MiB/s)
}}}

The system should boot with purely running
{{{
=> setenv bootargs console=ttymxc0,115200
=> load mmc 1:2 0x12000000 /vmlinuz-5.10.0-10-armmp && load mmc 1:2 0x18000000 /dtbs/5.10.0-10-armmp/imx6q-cubox-i.dtb && load mmc 1:2 0x13000000 /initrd.img-5.10.0-10-armmp && echo Booting Debian 5.10.0-10-armmp from mmc 1:2... && bootz 0x12000000 0x13000000:fff 0x18000000
}}}
in the u-boot shell. The same two commands should also boot the failing system.

Note: Determining the root file system might be required. A [[https://wiki.debian.org/InstallingDebianOn/SolidRun/CuBox-i#Boot_Process|recipe for determining the root filesystem]] is given in for Cubox-i and should apply for similar systems.


= Links =
 * [[http://www.denx.de/wiki/U-Boot|U-Boot Homepage]]
 * [[http://www.denx.de/wiki/DULG/Manual|U-Boot Manual]]
 * [[https://www.vermasachin.com/posts/3-u-boot-environment-variables/|Sachin Verma's blog post on u-boot]]
 * Barebox: alternative bootloader for embedded systems
  * [[https://www.barebox.org/|Homepage]]
  * [[https://bugs.debian.org/900958| Debian ITP]]

General Information

U-boot is a bootloader for embedded boards. Most boards supported in the Debian packages of u-boot are ARM based.

Support in Debian

Since each u-boot target is fairly board-specific, often supporting only a single board, the u-boot maintainers require someone from the Debian community to be listed as a tester for each of the boards included in the Debian package. The list of boards included in the Debian packages are in the debian/targets file:

Ideally each board gets tested every upload to the Debian archive, or at the very least once for each upstream version.

The current status page lists the last known working version for a variety of boards.

You can subscribe to get notifications by subscribing on the package tracker page.

Support for boards enabled in the Debian u-boot packages should be in mainline u-boot, although backporting patches from newer versions of u-boot is a reasonable option:

If you'd like to get a support for a new board into Debian's u-boot, please get it in mainline u-boot and file a wishlist bug against u-boot:

Please also use the Debian bug tracking system for submitting other fixes to the Debian u-boot packages.

To test u-boot packages from debian, install the u-boot or appropriate u-boot-VARIANT package for your board. There may be instructions for installing u-boot in the corresponding /usr/share/doc/u-boot*/README.Debian* files. Typically, it involves using the "dd" command to write a u-boot image directly a raw SD card, or possibly flashing to NAND or other media.

Troubleshooting, debugging

Using a serial console

For debugging u-boot, a serial console is usually required. Accessing the serial console varies greatly by board; it often requires connecting a USB-TTL adapter to the ground, rx and tx pins on the board, but may instead use a 9-pin serial port with a null-modem cable.

There are several console terminal programs in Debian that can attach to a serial connection, for example GNU Screen.

For a serial port you would use something like (please adapt to your serial adapter name in /dev):

screen /dev/ttyS0 115200

And for an USB-TTL adapter:

screen /dev/ttyUSB0 115200

When booting u-boot from serial console, you should see output like the following:

U-Boot SPL 2014.10+dfsg1-5~20150407~1 (Apr 07 2015 - 18:39:36)
DRAM: 1024 MiB
CPU: 1008000000Hz, AXI/AHB/APB: 3/2/2


U-Boot 2014.10+dfsg1-5~20150407~1 (Apr 07 2015 - 18:39:36) Allwinner Technology

CPU:   Allwinner A10 (SUN4I)
I2C:   ready
DRAM:  1 GiB
MMC:   SUNXI SD/MMC: 0
*** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
SCSI:  SUNXI SCSI INIT
SATA link 0 timeout.
AHCI 0001.0100 32 slots 1 ports 3 Gbps 0x1 impl SATA mode
flags: ncq stag pm led clo only pmp pio slum part ccc apst
Net:   emac
Hit any key to stop autoboot:  0
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0...
Found U-Boot script /boot/boot.scr
2163 bytes read in 303 ms (6.8 KiB/s)
## Executing script at 43100000
Mainline u-boot / new-style environment detected.
3181344 bytes read in 445 ms (6.8 MiB/s)
17835 bytes read in 334 ms (51.8 KiB/s)
12598748 bytes read in 1137 ms (10.6 MiB/s)
Booting Debian 3.16.0-4-armmp from mmc 0:1...
Kernel image @ 0x42000000 [ 0x000000 - 0x308b20 ]
## Flattened Device Tree blob at 43000000
   Booting using the fdt blob at 0x43000000
   Loading Ramdisk to 4f3fc000, end 4ffffddc ... OK
   Loading Device Tree to 4f3f4000, end 4f3fb5aa ... OK

Starting kernel ...

This should show you the version of u-boot being loaded.

U-boot prompt, custom kernel arguments

Additional kernel arguments can be given from u-boot before booting into the system by stopping normal boot and dropping to the u-boot prompt.

When started and before booting into the OS u-boot will show a 3 seconds countdown:

Hit any key to stop autoboot:  2 

Hit any key from the serial console to interrupt boot to drop to the u-boot prompt: "=>"

From there you can add custom kernel arguments by adding aguments to the bootargs variable. For example to bypass the installed init system and drop to a root shell you may use:

=> setenv bootargs ${bootargs} init=/bin/bash
=> boot

or boot an older kernel which is still installed by setting fk_kvers e.g.

=> setenv fk_kvers 4.19.0-18-armmp

More information about available commands can be obtained from the help command.

Checking the environment

You'll also want to test with the default u-boot environment variables, otherwise bugs in the default environment may go unnoticed. If you see:

*** Warning - bad CRC, using default environment

This should be using the default environment variables. If you're unsure, you can run env default -a to reset the running environment, followed by boot.

Logging Commands used for Booting

Sometimes it is useful to log the commands and kernel, initrd.img, and DTB addresses which boot a newly installed system to debug the boot system a similar system. A typical usecase is that u-boot breaks for a release/kernel. Installing on a different media a new Debian system might help to get the upgraded system booting again.

Adding the two echos in /etc/flash-kernel/bootscript/bootscr.uboot-generic should reveal the standard u-boot boot commands

rd@bc-text:~$ cat /etc/flash-kernel/bootscript/bootscr.uboot-generic
[...]
for pathprefix in ${fk_image_locations}
do
  if test -e ${devtype} ${devnum}:${partition} ${pathprefix}vmlinuz-${fk_kvers}
  then
    echo bootargs: ${bootargs}
    echo "load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz-${fk_kvers} \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}${fdtpath} \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img-${fk_kvers} \
    && echo Booting Debian ${fk_kvers} from ${devtype} ${devnum}:${partition}... \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}"
    load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz-${fk_kvers} \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}${fdtpath} \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img-${fk_kvers} \
    && echo "Booting Debian ${fk_kvers} from ${devtype} ${devnum}:${partition}..." \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}
  fi
done

for pathprefix in ${fk_image_locations}
do
  if test -e ${devtype} ${devnum}:${partition} ${pathprefix}vmlinuz
  then
    load ${devtype} ${devnum}:${partition} ${kernel_addr_r} ${pathprefix}vmlinuz \
    && load ${devtype} ${devnum}:${partition} ${fdt_addr_r} ${pathprefix}dtb \
    && load ${devtype} ${devnum}:${partition} ${ramdisk_addr_r} ${pathprefix}initrd.img \
    && echo "Booting Debian from ${devtype} ${devnum}:${partition}..." \
    && bootz ${kernel_addr_r} ${ramdisk_addr_r}:${filesize} ${fdt_addr_r}
  fi
done
rd@bc-text:~$ 

Recreate /boot/boot.scr

root@bc-text:~# flash-kernel 
Using DTB: imx6q-cubox-i.dtb
Installing /usr/lib/linux-image-5.10.0-10-armmp/imx6q-cubox-i.dtb into /boot/dtbs/5.10.0-10-armmp/./imx6q-cubox-i.dtb
Taking backup of imx6q-cubox-i.dtb.
Installing new imx6q-cubox-i.dtb.
flash-kernel: installing version 5.10.0-10-armmp
Generating boot script u-boot image... done.
Taking backup of boot.scr.
Installing new boot.scr.
root@bc-text:~#

Reboot the system and monitor the u-boot output on a serial console

Hit any key to stop autoboot:  0 
switch to partitions #0, OK
mmc1 is current device
Scanning mmc 1:2...
Found U-Boot script /boot.scr
4095 bytes read in 2 ms (2 MiB/s)
## Executing script at 12000000
bootargs: console=ttymxc0,115200
load mmc 1:2 0x12000000 /vmlinuz-5.10.0-10-armmp      && load mmc 1:2 0x18000000 /dtbs/5.10.0-10-armmp/imx6q-cubox-i.dtb      && load mmc 1:2 0x13000000 /initrd.img-5.10.0-10-armmp      && echo Booting Debian 5.10.0-10-armmp from mmc 1:2...      && bootz 0x12000000 0x13000000:fff 0x18000000
4960768 bytes read in 244 ms (19.4 MiB/s)

The system should boot with purely running

=> setenv bootargs console=ttymxc0,115200
=> load mmc 1:2 0x12000000 /vmlinuz-5.10.0-10-armmp      && load mmc 1:2 0x18000000 /dtbs/5.10.0-10-armmp/imx6q-cubox-i.dtb      && load mmc 1:2 0x13000000 /initrd.img-5.10.0-10-armmp      && echo Booting Debian 5.10.0-10-armmp from mmc 1:2...      && bootz 0x12000000 0x13000000:fff 0x18000000

in the u-boot shell. The same two commands should also boot the failing system.

Note: Determining the root file system might be required. A recipe for determining the root filesystem is given in for Cubox-i and should apply for similar systems.

Links