Debian on APF

From ArmadeusWiki
Revision as of 15:38, 26 May 2016 by FabienM (Talk | contribs) (Overwriting default rootfs on Flash (APF6))

Jump to: navigation, search

This page details how to install Debian on an APF27 / APF28 / APF51 / APF6.


  • an APF board (with corresponding docking board)
  • a development PC running linux
  • the debootstrap program installed on the development PC
  • the ARM qemu-user, statically linked on the development PC
  • about an hour of free time

Lazy guys

For the lazy one and also beholder of an APF6, you can find an image here: apf6_debian_wheezy_rootfs.ext4

  • Download it and put it in your TFTP directory:
# cp xxx/apf6_debian_wheezy_rootfs.ext4 /tftpboot/apf6-rootfs.ext4
  • reflash your rootfs:
BIOS> run update_rootfs

Preparing the development PC

  • In this tutorial, we use Ubuntu on the development PC. Any other distribution can be used with some adjustments but of course, Debian based distributions are recommended.
  • Let's first install all the packages that will be used :
$ sudo apt-get install debootstrap qemu-user-static
  • then get in a root shell and prepare a work folder:
$ sudo su
# cd anywhere_you_have_free_space
# mkdir apf_debian
# cd apf_debian

Bootstrapping the Debian filesystem

  • The debootstrap command is generating a base debian filesystem by downloading all debian base packages and unpacking them in a folder, in order to build a fresh debian root filesystem.
  • Installing deb packages is not only extracting archive files, it also consists in running scripts after unpacking the files. Running these scripts is handled by the script interpreters that have been unpacked in the generated folders. Therefore generating an ARM debian filesystem on an x86 based computer requires to do this in two steps.
  • Let's run the first step. That one consists in downloading all the deb packages and unpacking the files, but without running the scripts :
# debootstrap --foreign --arch=armel jessie rootfs 
  • The --foreign option makes debootstrap stop right after unpacking.
  • The --arch option specifies the architecture we want to make a rootfs for, armel is the name of the ARM port of debian for processors without FPU.
Note Note: On APF6 you might want to use armhf (i.MX6 has an FPU) instead of armel.
  • jessie is the name of the debian version we want to get (latest stable one). rootfs is the name of the subfolder where debootstrap will work. Finally we give the URL of the debian mirror we want to use (you can use another one which sits in your country, to make it faster).
  • This process may take a while: it will download all the debian base packages from the mirror and unpack them in the rootfs/ folder.

second stage of debootstrap

  • The next step is to run the second stage of debootstrap. That stage consists in finalizing the installation of the package by running the configuration scripts we mentionned earlier. Since these scripts will be executed using the interpreter who is in the new filesystem, and not by the interpreter from your development PC, we are now facing a problem : the interpreter in that new filesystem is an ARM program, and won't run on an x86 system. To overcome this, we will make use of qemu, who allows to run foreign architecture Linux programs through emulation.
  • First, we need to copy the qemu binary into the new filesystem :
# cp /usr/bin/qemu-arm-static rootfs/usr/bin/
  • Then we can launch the second stage of debootstrap; qemu will automatically run the ARM binaries :
# DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true LC_ALL=C LANGUAGE=C LANG=C chroot rootfs debootstrap/debootstrap --second-stage
  • This process may also take a while: it will run the scripts of each package, in order to finalize the package installation.

Tweaking the filesystem

  • After the filesystem has been generated by debootstrap, some adjustments need to be done.
  • First, we need to have debian run a getty on the console serial port (replace ttyXXX with ttymxc2 on APF51, ttySMX0 on APF27, ttymxc3 on APF6), otherwise no login prompt will be available on the console port :
# echo 'T0:23:respawn:/sbin/getty -L ttyXXX 115200 vt100' >> rootfs/etc/inittab
  • The debian mirror also has to be specified in the APT configuration, in order to install new debian packages later :
# echo 'deb jessie main' > rootfs/etc/apt/sources.list
  • The hostname of the debian system has to be set properly (here apf51, change it accordingly to your board):
# echo 'apf51' > rootfs/etc/hostname
# echo ' apf51' >> rootfs/etc/hosts
  • Remove root password (for first login):
# sed -i -e 's/root:\*:/root::/' rootfs/etc/shadow
  • Add eth0 network interface configuration:
# echo -e "\nauto eth0\nallow-hotplug eth0\niface eth0 inet dhcp\n" >> rootfs/etc/network/interfaces
  • Finally we can clean the APT cache (we no longer need the deb files, and that will save quite some disk space) :
# chroot rootfs apt-get clean

Copying the filesystem on the APF

  • Now that the debian filesystem is ready, it must be transferred to the APF.

Overwriting default rootfs on Flash (APF6)

  • The APF6 eMMC has enough space to run debian directly on it
  • To finalize installation you will need resize2fs tool (recent version of Armadeus BSP), so copy it to Debian rootfs (Armadeus binaries for APF6 or compatible with Debian armhf port):
# cp ../buildroot/output/target/usr/sbin/resize2fs rootfs/usr/sbin/
  • To generate a .ext4 image from the rootfs/:
# PATH=$PATH:/your_armadeus_bsp_for_apf6/buildroot/output/host/usr/bin/:/your_armadeus_bsp_for_apf6/buildroot/output/host/usr/sbin/ \
    mke2img -G 4 -R 1 -d apf_debian/rootfs/ -o apf_debian/apf6_debian_jessie_rootfs.ext4
# cp apf_debian/apf6_debian_jessie_rootfs.ext4 /tftpboot/apf6-rootfs.ext4
BIOS> run update_rootfs

Using Debian on Flash while keeping default rootfs (APF6/APF51)

  • This tutorial will describe a method that will allow to keep the original Armadeus system on the board, and that will permit to choose which system to boot very easily. It is not the only way to run Debian on the APF, but it is quite convenient.
  • You need to have an APF51 or an APF6 running the Buildroot based original system.
  • The first step is to pack the debian filesystem that has been created on the development PC:
# tar cvf debian_arm_rootfs.tar rootfs/
  • You will end up with a ~150 MBytes tarball
  • Then this archive should be transferred to the APF board. You can use a USB key or a microSD for example. (or TFTP if you have a lot of free space on your APF NAND; then put the file in /root on the APF)
  • Now, on the APF, the archive should be extracted (from the media holding it to the APF NAND FLASH). Don't forget the p option of tar, which is required to properly extract permissions on files :
# cd /root
# tar xvpf debian_arm_rootfs.tar
  • We will boot this distribution using chroot. We need to write a script that will be run by the kernel on startup and that will do the chroot at an early stage of the boot process, so that nothing from the original rootfs is started when we want to boot Debian. To do this, create a file called /debinit that contains the following lines :
mount -t proc none /root/rootfs/proc
exec chroot /root/rootfs /sbin/init
  • This script needs to be executable :
# chmod 755 /debinit
  • Kernel modules and firmware files need to be copied from the default filesystem to the Debian filesystem :
# cp -r /lib/modules/* /root/rootfs/lib/modules
# cp -r /lib/firmware /root/rootfs/lib/firmware
# chroot /root/rootfs /sbin/depmod -a
  • Finally, we need to configure U-Boot so it tells the kernel to use that script on bootup. Reboot your board, press a key to interrupt the automatic boot in U-Boot, then do :
BIOS> setenv debboot 'setenv extrabootargs ${extrabootargs} init=/debinit; run ubifsboot'
BIOS> saveenv
BIOS> setenv debboot 'setenv extrabootargs ${extrabootargs} init=/debinit; run emmcboot'
BIOS> saveenv
  • That's all. Now you board will keep booting the original system but if you want to boot debian instead, you can interrupt the autoboot of U-Boot and run the command :
BIOS> run debboot
  • In case you want the board to boot debian automatically, you can do so by running :
BIOS> setenv bootcmd run debboot
BIOS> saveenv
  • You can then switch back to the original Armadeus system by running :
BIOS> setenv bootcmd run ubifsboot
BIOS> saveenv

First login

Whaoouh ! It booted ! ;-)

Debian GNU/Linux 6.0 apfxx ttySMX0/ttymxc2

apfxx login:
  • Login as root with no password
  • On APF6 only, if you replaced the default rootfs, you might want to use all eMMC space for debian:
root@apfxx:~# /usr/sbin/resize2fs /dev/mmcblk2p2
  • Update packages:
root@apfxx:~# apt-get update
  • If the keyboard layout doesn't suite yours, you can change it with (keyboard type, then keymap):
root@apfxx:~# dpkg-reconfigure keyboard-configuration
  • Setup system and RTC date:
root@apfxx:~# date 012011552010
Wed Jan 20 11:55:00 UTC 2010
root@apfxx:~# hwclock -wu
  • If you don't have any RTC chip (or no RTC backup cell) on your development board, then it could be a good idea to install ntpdate and use it:
root@apfxx:~# apt-get install ntpdate
root@apfxx:~# ntpdate-debian
  • Change root password:
root@apfxx:~# passwd
  • Add a user (armadeus):
root@apfxx:~# adduser armadeus
  • Remove x86 qemu used during installation to get some free space:
root@apfxx:/tmp# rm /usr/bin/qemu-arm-static
  • Other packages that may also be useful:
root@apfxx:~# apt-get install gcc-4.4 tftp vim
  • If you want an X server (requires ~60 MBytes of free space):
root@apfxx:~# aptitude install xserver-xorg              (xserver-xfbdev ?)
  • If you want some apps for X (requires ~20 MBytes of free space):
root@apfxx:~# aptitude install x11-apps
  • If you want a graphical login manager:
root@apfxx:~# aptitude install xdm
  • If you want a desktop manager (requires >300 MBytes o_O):
root@apfxx:~# aptitude install xfce4
  • You might also want to try another "lightweigth" desktop manager (>600 MBytes o_O<):
root@apfxx:~# aptitude install lxde

Known issues


  • Xorg won't start. (compatibility problem with framebuffer driver)


  • There's a kernel oops during the boot process. This is related to the SPI driver.
  • Booting takes quite some time because udev has an issue with the SPI port and it takes some time before it timeouts and continues the boot.

Console Port Issues

In some cases the boot crashes and errors like these appear

init: Id "T0" respawning too fast: disabled for 5 minutes

It means that the /dev folder haven't been populated with your console serial port.

To fix this, you need to reboot the apf and run armadeus system, then you need to do the following commands :

# cp -r /dev/ttymxc0 /root/rootfs/dev/ttymxc0 (for apf51)
# cp -r /dev/ttySMX0 /root/rootfs/dev/ttySMX0 (for apf27)

You also need to check that the file /root/rootfs/etc/securetty contains the console serial port (ttymxc0 for APF51 and ttySMX0 for APF27) if not :

# echo 'ttymxc0' >> /root/rootfs/etc/securetty (for apf51)
# echo 'ttySMX0' >> /root/rootfs/etc/securetty (for apf27)

It will allow the root user to login via this serial console.

It could also affects other ports and you will need to do the same procedure for them (ttyX, fbX, input, ttymxcX, ttySMXX, etc.)