Difference between revisions of "Debian on APF"

Latest revision as of 17:23, 8 October 2019

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

Requirements

• 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.
• For the lazy one and also beholder of an OPOS6UL, you can find an image here: opos6ul_debian_jessie_rootfs.ext4.
• Download it and put it in your TFTP directory:

# cp xxx_debian_wheezy_rootfs.ext4 /tftpboot/xxx-rootfs.ext4    (where xxx is the name of you module)

• reflash your rootfs from U-Boot (if you have 512 Mbytes of RAM):

BIOS> run update_rootfs

• or use UMS mode otherwise.
• Then you can reset your board and directly skip to "First login".

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 http://ftp.debian.org/debian 

• 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: On APF6 & OPOS6UL 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.

...
I: Base system installed successfully.

Tweaking the filesystem

• After the file system 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, ttymxc0 on OPOS6UL), 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 http://ftp.debian.org/debian jessie main' > rootfs/etc/apt/sources.list

• The hostname of the debian system has to be set properly (here apf6, change it accordingly to your board):

# echo 'apf6' > rootfs/etc/hostname
# echo '127.0.1.1 apf6' >> 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

• Copy kernel image and modules:

# export YOUR_BSP_PATH=your_armadeus_bsp_path
# cp -r ${YOUR_BSP_PATH}/buildroot/output/target/boot rootfs/
# cp -r ${YOUR_BSP_PATH}/buildroot/output/target/lib/modules rootfs/lib/

• 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. You have 2 solutions:

1] Overwriting default rootfs on Flash (APF6/OPOS6UL)

• The APF6/OPOS6UL 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/OPOS6UL are compatible with Debian armhf port):

# YOUR_BSP_PATH=your_armadeus_bsp_path
# cp $YOUR_BSP_PATH/buildroot/output/target/sbin/resize2fs rootfs/sbin/

• To generate a .ext4 image from the rootfs/ directory:

# YOUR_BSP_PATH=your_armadeus_bsp_path
# PATH=$PATH:$YOUR_BSP_PATH/buildroot/output/host/usr/bin/:$YOUR_BSP_PATH/buildroot/output/host/usr/sbin/ \
    mke2img -G 4 -R 1 -d ./rootfs/ -o apf_debian_jessie_rootfs.ext4
# cp apf_debian_jessie_rootfs.ext4 /tftpboot/XXX-rootfs.ext4      (where XXX is the name of your module)
# chmod a+rw /tftpboot/opos6ul-rootfs.ext4

• Now on your board, boot into U-Boot and:

BIOS> run update_rootfs

• If the rootfs image is too big for your SoM RAM size, you can also use UMS USB mode of U-Boot to flash this image.
• Congratulations, you can go to first login

2] 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 :

#!/bin/sh
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

Configure U-Boot to boot debian

• 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 8 apfxx/opos6ul ttySMX0/ttymxc2|0

apfxx/opos6ul login:

• Login as root with no password

• If rootfs is mounted read-only, then remount it rw:

root@apf6:~# mount -o remount,rw /dev/mmcblk2p2

root@opos6ul:~# mount -o remount,rw /dev/mmcblk0p2

• You might also definitely change this behavior (rootfs mounted read-only), by modifying U-Boot's mmcroot variable: replace ro with rw:

root@apf6:~# reboot
BIOS> setenv mmcroot /dev/mmcblk2p2 rw
BIOS> saveenv

root@opos6ul:~# reboot
BIOS> setenv mmcroot /dev/mmcblk0p2 rw
BIOS> saveenv

• On modules with eMMC only, if you replaced the default rootfs, you might want to use all eMMC space for debian:

root@apf6:~# /usr/sbin/resize2fs /dev/mmcblk2p2

root@opos6ul:~# /usr/sbin/resize2fs /dev/mmcblk0p2

• If /etc/mtab is absent, regenerate it:

root@opos6ul:~# grep -v rootfs /proc/mounts > /etc/mtab

• Update packages (network should be up and running):

root@apfxx:~# apt-get update
root@apfxx:~# apt-get upgrade
...

• 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 but have Internet access, then it could be a good idea to install ntpdate and use it:

root@apfxx:~# apt-get install ntpdate
...
root@apfxx:~# ntpdate-debian

• To configure TimeZone:

root@apfxx:~# dpkg-reconfigure tzdata

• 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

• If you want remote network/SSH access to your board:

root@apf|oposxx:~# apt-get install dropbear

• Other packages that may also be useful (for development):

root@apfxx:~# apt-get install build-essential gcc-4.8 tftp vim strace i2c-tools iw psmisc

• If you want an X server (requires ~60 MBytes of free space):

root@apfxx:~# apt-get install xserver-xorg              (xserver-xfbdev ?)

• If you want some apps for X (requires ~20 MBytes of free space):

root@apfxx:~# apt-get install x11-apps

• If you want a graphical login manager:

root@apfxx:~# apt-get install xdm

• if you want a touchscreen calibrator and a virtual keyboard:

root@apfxx:~# apt-get install xinput-calibrator xvkbd

• if you want a lightweight Web browser:

root@apfxx:~# apt-get install netsurf

• If you want a desktop manager (requires >300 MBytes o_O):

root@apfxx:~# apt-get install xfce4

• You might also want to try another "lightweight" desktop manager (>600 MBytes o_O<):

root@apfxx:~# apt-get install lxde

Known issues

APF27

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

APF51

• 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.

APF6

• hcitool lescan command is reported to not work. Use bluetoothctl instead.

OPOS6UL

• onboard Wi-Fi chip doesn't seem operational.
• to have Wi-Fi firmware on Debian Jessie:

root@opos6ul:~# vim /etc/apt/sources.list
                   add non-free
root@opos6ul:~# apt-get update
root@opos6ul:~# apt-get install firmware-brcm80211

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.)

Automatically starts your custom application

• Edit a shell script named /etc/init.d/myapp, here we suppose your application is named /root/myapp:

#!/bin/sh

### BEGIN INIT INFO
# Provides:        myapp
# Required-Start:  $network $remote_fs $syslog
# Required-Stop:   $network $remote_fs $syslog
# Default-Start:   2 3 4 5
# Default-Stop: 
# Short-Description: Start my application
### END INIT INFO

PATH=/sbin:/bin:/usr/sbin:/usr/bin

. /lib/lsb/init-functions

MY_APP=/root/myapp

test -x $MY_APP || exit 5

case $1 in
        start)
                log_daemon_msg "Starting my app"
                $MY_APP &
                ;;
        stop)
                log_daemon_msg "Stopping my app"
                ;;
        restart)
                $0 stop && sleep 2 && $0 start
                ;;
        *)
                echo "Usage: $0 {start|stop|restart}"
                exit 2
                ;;
esac

• make it executable:

root@opos6ul:~# chmod a+x /etc/init.d/myapp

• create a symlink to start the previous script in runlevel 5:

root@opos6ul:~# ln -sf /etc/init.d/myapp /etc/rc5.d/S99myapp

• reboot and check that you application is successfully started ;-)

Links

• Installing Debian GNU/Linux from a Unix/Linux System
• http://free-electrons.com/blog/embdebian-with-multistrap/
• http://wiki.debian.org/Xfce
• Enhanced french tutorial to install Debian on an APF28 board
• Buildroot_inside_Debian_on_APF