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
=> bootor 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
donerd@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.
Alternative Bootloaders for Embedded Systems
- Barebox