Minnowboard:Debian Bare Minimum Bootstrapping

'''This document is a work in progress. Feedback is needed to improve this document'''

Bootstrapping Debian onto your MinnowBoard is a fairly simple process. At the end of this guide you will have a complete minimum Debian system you can use on your MinnowBoard.

Requirements:
 * 1) MinnowBoard that has a working micro SD card preloaded with the MinnowBoard Angstrom Linux Distribution
 * 2) USB Thumb drive >2GB or SATA drive
 * 3) Internet connection
 * 4) Some spare time

Lets Get Started
You will need a place to install Debian onto, for safety sake we are installing onto a drive other then the micro SD card. This way if you mess up you can simply format the drive and start over and still have a good install of Angstrom to use. Your Minnowboard came with Angstrom preinstalled on a micro SD card that had two partitions. The first partition is the UEFI boot partition, which we will keep to boot our Debian system. The second partition is the Angstrom root partition which should be left intact as well.


 * TIP: Save the kernel modules in /lib/modules/ directory to preserve the Angstrom kernel modules which a guaranteed to work. You can use these modules and the Angstrom kernel with your Debian root filesystem also.

If you are using a new micro sd card or SATA disk you'll want to create a small (approximately 20MB) fat16 or fat32 partition and enable the boot flag on it. This partition will be your new UEFI boot partition. You can use GPT partitioning or MSDOS partitioning if you wish. The Minnowboard's UEFI system can boot off of either of the two.


 * TIP: You can merely copy the files from the Angstrom Boot partition to your new media and you'll have a working Grub UEFI bootloader.

First plugin your thumb drive and use your favorite Disk Utility to properly partition it out. Create the following partitions:

Partition 1: 50-100MB marked as Active or Bootable Partition 2: 2GB-10GB depending on if you plan on install X11

Create filesystems on partitions

 * NOTE: Check, Double Check and Triple Check that you are using the CORRECT devices. This could potentially erase your filesystem if you choose the wrong device.

Create a fat32 filesystem on the UEFI boot partition mkfs.vfat /dev/sdb1 Create an ext4 filesystem on the root partition

mkfs.ext4 /dev/sdb2

Mount the UEFI boot partition and copy all of the files from the device

Mount the Angstrom micro sd card mkdir /mnt/angstromuefi mount /dev/mmcblk0p1 /mnt/angstromuefi

Mount your new UEFI boot partition mkdir /mnt/debianuefi mount /dev/sdb1 /mnt/debianuefi

Copy the Angstrom Bootloader files
Now we will copy all of the files from the Angstrom micro sd UEFI boot partition

cp -r /mnt/angstromuefi/* /mnt/debianuefi/

Other Prerequisites
You need to have the xzcat command for debootstrap to work, so install it in your running Angstrom image with:

opkg update opkg install xz

Debootstrapping
Mount the Debian root partition mkdir /media/debian mount /dev/sdb2 /media/debian

Next make a root directory on your Angstrom micro SD card to hold all the bootstrap files call it debinst. mkdir /debinst cd /debinst

Then choose what version of Debian you want to use. It should be either Debian Jessie or Sid to ensure that you have a serial console.


 * NOTE: If you are currently running a Debian based system you can run this command 'sudo aptitude install debootstrap fakeroot' and your system will install the chroot and debootstrap packages for you. If this is the case then the following step is unecessary.

http://ftp.debian.org/debian/pool/main/d/debootstrap/ mkdir work cd work wget http://ftp.debian.org/debian/pool/main/d/debootstrap/debootstrap_1.0.48+deb7u1_all.deb copy the package to the work folder, and extract the files from it. ar -x debootstrap_1.0.48+deb7u1_all.deb cd /debinst zcat work/data.tar.gz | tar xv

There is a small issue with the installer that needs to be fixed before we start the script. Edit /debinst/usr/sbin/debootstrap line 16 to DEBOOTSTRAP_DIR=/debinst/usr/share/debootstrap

Next Comes the part that will take some time. Running the bootsrtap script /debinst/usr/sbin/debootstrap --verbose --extractor=ar --arch i386 jessie /media/debian http://ftp.us.debian.org/debian


 * NOTE: You can replace jessie in the command above with wheezy or sid, but wheezy should not be used unless you plan on using an alternate kernel(or the Angstrom kernel). The kernels in wheezy are too old for the needed changes to support a serial console and perhaps ethernet for the Minnowboard.

Configuring
Lets configure a few things by chrooting into the system. LANG=C.UTF-8 chroot /media/debian /bin/bash Set the terminal to be compatible with the Debian System export TERM=xterm-color

Now we can create the device files (there may be a better way to do this) apt-get install makedev cd /dev MAKEDEV generic

You will see warnings about not being able to read /proc/devices - these are safe to ignore.

You will need to add Mount points in your fstab. Below is a very good starting point for both sd cards and SATA disks.

editor /etc/fstab


 * TIP: If you are using an sd card or any flash based storage you will benefit considerably by removing the # in front of the tmpfs entries below. These entries mount various filesystem to tmpfs which help reduce writes on your flash devices; thus prolonging their life. Also note that the log files will not be retain after subsequent boots, so if you need them copy them elsewhere before rebooting.

rootfs         /                       ext4       defaults              1  1 proc           /proc                   proc       defaults              0  0 devpts         /dev/pts                devpts     mode=0620,gid=5       0  0
 * 1) tmpfs          /var/run                tmpfs   defaults                0  0
 * 2) tmpfs          /var/lock               tmpfs   defaults                0  0
 * 3) tmpfs          /var/log                tmpfs   defaults                0  0
 * 4) tmpfs          /tmp                    tmpfs   defaults                0  0

CPU Throttling
The cpu is set to 600Mhz by default, we'd like to have it at 1GHZ apt-get install cpufrequtils

You have to create the file below but that is no problem, we give you the appropriate contents to fill it with editor /etc/default/cpufrequtils

Add the correct governor to boost performance GOVERNOR="performance"
 * 1) you can run 'cpufreq-info -g' to get a list of available governors

Timezone settings
The following command allows you to choose your timezone. dpkg-reconfigure tzdata

Configure Networking
editor /etc/network/interfaces

Add the following lines to provision your interface. If you are using a wireless adapter use the appropriate steps to configure it as well.

auto eth0 iface eth0 inet dhcp


 * NOTE: replace 'auto eth0' with 'noauto eth0' if you'd rather not wait for the interface to attempt to obtain an ipaddress.

Enter your nameserver(s) and search directives in /etc/resolv.conf: editor /etc/resolv.conf Enter your system's host name (2 to 63 characters) echo DebianMinnow > /etc/hostname

Configure Apt
Debootstrap will have created a very basic /etc/apt/sources.list you can add more repositories deb http://ftp.us.debian.org/debian jessie main deb-src http://ftp.us.debian.org/debian jessie main deb http://security.debian.org/ jessie/updates main deb-src http://security.debian.org/ jessie/updates main


 * NOTE: You should put the correct release in the sources.list whether it be sid or wheezy but stay away from wheezy unless you plan on using an alternate kernel such as the kernel included with Angstrom.

Install a Kernel
To install the latest kernel from your chosen Debian release, run the command below:

apt-get install linux-image-686-pae
 * NOTE: It is best to use 3.12.X kernels or greater with the Minnowboard because they have better support for its peripherals such as builtin ethernet and serial console. Install this kernel for the greatest compatibility


 * NOTE: This is Debian's experimental kernel; you MUST install the linux-image-686-pae package first before installing this experimental kernel. If you don't install linux-image-686-pae first, the kernel installation will surely fail!

Download the kernel

wget http://ftp.us.debian.org/debian/pool/main/l/linux/linux-image-3.12-trunk-686-pae_3.12.3-1~exp1_i386.deb Install the kernel

dpkg -i linux-image-3.12-trunk-686-pae_3.12.3-1~exp1_i386.deb

Rebuild your initramfs
Certain modules need to be preloaded for your system to fully boot. These modules should be added to the ramdisk so that your root file system can be mounted

editor /etc/initramfs-tools/modules

If you are using the micro sd slot you must have the mmc module in the ramdisk for the root filesystem to mount

add the following line mmc

Rebuild the initramfs

update-initramfs -u

Configure a Serial Console
Debian needs the following lines added to it's configuration files for your serial console to display a login prompt after booting editor /etc/modules

add the following line to automatically load the uart console module pch_uart

editor /etc/inittab

add the following the bottom of the inittab to tell getty to spawn consoles on the 3 uart devices T0:23:respawn:/sbin/getty -L ttyPCH0 115200 vt100 T1:23:respawn:/sbin/getty -L ttyPCH1 115200 vt100 T2:23:respawn:/sbin/getty -L ttyPCH2 115200 vt100

editor /etc/securetty

add the follwing entries to the securetty file so that the root user can login via the console

ttyPCH0 ttyPCH1 ttyPCH2

Blacklist Modules
Currently the gma500_gfx module needs to be blacklisted in 3.12.X and older kernels so that you can use the framebuffer device. Without blacklisting this module you won't see a login prompt on your screen will just be black.

First create a file called blacklist.conf editor /etc/modprobe.d/blacklist.conf

add the following entry

blacklist gma500_gfx

Boot Loader
In order to simplify things we will just reuse the boot partition that was provided with the Angstrom Minnowboard image. More information will be added here later but until then, this is the quickest way to achieve a working system.

There is a grub.cfg included in the /EFI/BOOT directory of the uefi boot partition of the Angstrom Minnowboard image. Edit it as follows

editor /mnt/debianuefi/EFI/BOOT/grub.cfg

Use this for a MBR partitioned disk

menuentry "Debian 7.0 3.12-trunk-pae (32-bit, EFI)" { insmod part_msdos insmod ext2 set root='(hd0,msdos2)' linux /boot/vmlinuz-3.12-trunk-686-pae root=/dev/sda2 ro rootwait console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0 initrd /boot/initrd.img-3.12-trunk-686-pae }

Use this entry for a GPT partitioned disk

menuentry "Debian 7.0 3.12-trunk-pae (32-bit, EFI)" { insmod part_gpt insmod ext2 set root='(hd0,gpt2)' linux /boot/vmlinuz-3.12-trunk-686-pae root=/dev/sda2 ro rootwait console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0 initrd /boot/initrd.img-3.12-trunk-686-pae }

If you are using a micro sd card make sure that you change the 'root=/dev/sda2' line to 'root=/dev/mmcblkp2'

Install grub-efi

apt-get install grub-efi-ia32

mount your uefi boot partition mount /dev/sda1 /mnt or mount /dev/mmcblkp1 /mnt

Copy all of the modules from the grub-efi directory to the boot partition cp -r /usr/lib/grub/i386-efi /mnt/EFI/BOOT/

More information will come soon on the installation of grub via Debian Grub 2.X but many errors were produced during installation.

SSH and Remote Access
apt-get install openssh-server passwd

Finishing Up
Exit the chroot environment exit

You system is now ready to boot from the installed media

Expanding Further
As mentioned earlier, the installed system will be very basic. You can expand your system more with the following command tasksel install standard

From the bootstrapping process there will be a ton of left over packages in /var/cache/apt/archives/. You may want to remove them. aptitude clean

Things that don't quite work

 * NOTE: Minnowboard development is moving rapidly so many things that don't seem to work, may be fixed in subsequent days or weeks.

3.12 Kernels
It has been observed that SPI, GPIO, LED Heartbeart, Push buttons, USB OTG and the GMA500_GFX module fail to work out of the box. Built in Ethernet works in these kernels and it is currently the most desirable other than the Angstrom Kernel that was provided with your Minnowboard.

3.11 Kernels
It has been observed that SPI, GPIO, LED Heartbeart, Push buttons, USB OTG, ETHERNET and the GMA500_GFX module fail to work out of the box.


 * NOTE: GMA500_GFX is said to be patched for 3.13-rc1

Using the Angstrom Kernel
You can use the provided Angstrom kernel with your Debian root filesystem and the system hardware will function properly due to the Minnowboard being Yocto Program Certified. This means that Angstrom is ahead of the curve in this regard and their kernel supports the Minnowboard the best.


 * NOTE: The Angstrom kernel is very streamlined so it does not have a plethora of modules like the Debian kernel does. If your desired modules are is not included then you will either have to build it yourself of use the Debian kernel such as 3.12.X or greater.

Mount the Angstrom UEFI boot partition mkdir /mnt/angstromuefi mount /dev/mmcblk0p1 /mnt/angstromuefi

Mount the Angstrom Filesystem mkdir /mnt/angstromroot mount /dev/mmcblk0p2 /mnt/angstromroot

Mount your Debian root filesystem mkdir /mnt/debianroot mount /dev/sdb2 /mnt/debian

Now copy over the kernel from the Angstrom UEFI boot partition and then the modules from the Angstrom root filesystem

cp -r /mnt/angstromroot/lib/modules/3.8.13-yocto-standard /mnt/debianroot/lib/modules cp /mnt/angstromuefi/vmlinuz /mnt/debianroot/boot/vmlinuz-3.8.13-yocto-standard

You can add an entry to the grub.cfg to boot your Debian root filesystem with the Angstrom kernel


 * NOTE: The Angstrom kernel does not need an initramfs because the modules necessary are all built in

editor /mnt/debianuefi/EFI/BOOT/grub.cfg

Use this for a MBR partitioned disk

menuentry "Debian 7.0 3.8.13-yocto-standard (32-bit, EFI)" { insmod part_msdos insmod ext2 set root='(hd0,msdos2)' linux /boot/vmlinuz-3.8.13-yocto-standard root=/dev/sda2 ro rootwait console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0 }

Use this entry for a GPT partitioned disk

menuentry "Debian 7.0 3.8.13-yocto-standard (32-bit, EFI)" { insmod part_gpt insmod ext2 set root='(hd0,gpt2)' linux /boot/vmlinuz-3.8.13-yocto-standard root=/dev/sda2 ro rootwait console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0 }