Gentoo on the Beaglebone

1.  Overview

Installing Gentoo in the Beaglebone is pretty simple if you're already a Gentoo user. You need to use an SD card, at least of 2 GB of size. If you are familar with the Gentoo Linux installation process, there is not much different here.

2.  Requirements

To be able to install Gentoo, you'll need the following:

• An x86/amd64 based PC with Gentoo and an SD card reader on it
• A Beaglebone
• One SD card (2 GB is enough)
• A network connection

3.  Preparing to install your Beaglebone

Overview

Before we start the installation process, we need to get/build a kernel, bootloader and X-Loader for the Beaglebone.

The Beaglebone doesn't have a NAND/flash device, so the bootloader (U-Boot) needs to be located on the SD card, along with X-Loader and the kernel.

Emerging needed tools

For building the stuff needed to boot our Beaglebone, we need the following tools emerged on the host system where we're going to build them.

• dev-vcs/git - to download U-Boot, X-Loader and the kernel
• dev-util/crossdev - to create a crosscompiler
• dev-embedded/u-boot-tools - to create a kernel image U-Boot can understand
• sys-fs/dosfstools - to create FAT32 filesystems

# emerge dev-vcs/git dev-util/crossdev dev-embedded/u-boot-tools sys-fs/dosfstools

Build a crosscompiler

# crossdev -S armv7a-unknown-linux-gnueabi

Obtaining/Building U-Boot

Upstream U-Boot(the one you can download from www.denx.de)'s SPL support doesn't include the AM33XX chip, which is the one used in the Beaglebone. Progress is being done as of December 2011 to get it included. For this reason, we'll use a patched U-Boot provided from TI.

# git clone git://arago-project.org/git/projects/u-boot-am33x.git

(Change to the directory)
# cd u-boot-am33x

# make ARCH=arm CROSS_COMPILE=armv7a-unknown-linux-gnueabi- am335x_evm_config
# make ARCH=arm CROSS_COMPILE=armv7a-unknown-linux-gnueabi-

Obtaining/Building a kernel

For booting the Beaglebone we need a kernel. The vanilla kernel.org doesn't support the Beaglebone as of December 2011, for this reason we'll use a kernel provided by TI.

# git clone git://arago-project.org/git/projects/linux-am33x.git

(Change to the directory)
# cd linux-am33x

# make ARCH=arm CROSS_COMPILE=armv7a-unknown-linux-gnueabi- am335x_evm_defconfig

(Replace 9 with the number of cores you have on your computer)
# make -j9 ARCH=arm CROSS_COMPILE=armv7a-unknown-linux-gnueabi- uImage

Once it gets built we'll have a kernel image on arch/arm/boot/uImage.

4.  SD card setup

Overview

OMAP-based systems need a special setup of the SD card to boot from it. For more information please check this link.

Formatting the SD card

The following script will format your SD card accordingly, creating two partitions. The first partition size is based on the size of the SD card itself, and it's formatted in vfat. The second partition is the free space left on the card after the first partition, and it's formatted in ext3.

# wget http://dev.gentoo.org/~armin76/arm/beaglebone/sdcardsetup.sh

(Replace mmcblk0 with the name of the device of your SD card)
# bash sdcardsetup.sh /dev/mmcblk0

Disabling DHCP when booting the kernel

The default configuration of U-Boot makes the kernel wait for a DHCP address upon boot. If it doesn't get an address assigned, it won't boot.

We workaround that by creating a file called uEnv.txt with the following contents:

ip_method=none

Copying U-Boot, MLO and the kernel to the SD card

Now we'll mount the first partition on the card and copy the needed files (the ones that we built before) to boot our Beaglebone.

(Make sure you're root)
# mkdir /mnt/p1 ; mount /dev/mmcblk0p1 /mnt/p1


# cp uEnv.txt /mnt/p1
# cp u-boot-am33x/{MLO,u-boot.img} /mnt/p1
# cp linux-am33x/arch/arm/boot/uImage /mnt/p1

5.  Installing Gentoo

Overview

The installation on this device is a bit different, and therefore easy, as we can't install Gentoo on it by booting an installation environment. For installing Gentoo (and any other distro, really) you need to put the SD card on your PC and prepare there the minimal installation.

What we'll have to do to setup our installation is:

1. Extract stage3 to the 2nd partition of the SD card
2. Extract portage snapshot (required to emerge things and ntp(see below))
3. Setup fstab
4. Setup root password
5. Configure hostname and networking (optional, but recommended)
6. Enable SSH access (optional, but recommended)
7. Enable serial console access (optional, but recommended)

Stages information

Here's some information about the stages.

• Architecture: arm
• Subarchitecture: armv7a
• CHOST: armv7a-unknown-linux-gnueabi
• Profile: default/linux/arm/10.0

We'll be using the new EABI, also called gnueabi. That is armel on Debian.

Therefore, we need an armv7a-unknown-linux-gnueabi stage3 for best performance, available under the releases/arm/autobuilds directory in your favorite mirror

Optionally you can also grab a portage snapshot

Extracting a stage3

Mount the second partition of the SD card and extract the stage3 you downloaded.

(Make sure you're root)
# mkdir /mnt/p2
# mount /dev/mmcblk0p2 /mnt/p2

(Extract the stage3, it may take a while)
# tar xjpf stage3-armv7a-20101118.tar.bz2 -C /mnt/p2

Extracting a portage snapshot (optional)

(Extract the snapshot, it may take a while)
# tar xjpf portage-latest.tar.bz2 -C /mnt/p2/usr

Setup fstab

Edit the /mnt/p2/etc/fstab file to look like this:

(This is the important part)
# NOTE: If your BOOT partition is ReiserFS, add the notail option to opts.
/dev/mmcblk0p1		/boot		vfat		noauto,noatime	1 2
/dev/mmcblk0p2		/		ext3		noatime		0 1

(Remove the following lines as we don't have SWAP, cdrom, or floppy)
/dev/SWAP		none		swap		sw		0 0
/dev/cdrom		/mnt/cdrom	auto		noauto,ro	0 0
#/dev/fd0		/mnt/floppy	auto		noauto		0 0

Setting the default root password

This is the most important part of the installation. As without the root password we won't be able to login!

For setting the password, we need to be able to run passwd. However that's not possible since our PC can't run ARM binaries. Therefore we need to modify the file that contains the passwords (/etc/shadow) inside the chroot, so we can set a default root password.

(Generate a password)
# openssl passwd -1

# nano -w /mnt/p2/etc/shadow

(Replace the first line with the following line)
root:s3cr3t:14698:0:::::
(Replace s3cr3t with the output the openssl command gave you)

(For example, this line makes the password be gentoo)
root:$6$I9Q9AyTL$Z76H7wD8mT9JAyrp/vaYyFwyA5wRVN0tze8pvM.MqScC7BBm2PU7pLL0h5nSxueqUpYAlZTox4Ag2Dp5vchjJ0:14698:0:::::

Setup hostname and networking

Please read the network configuration chapter of the ARM handbook to configure the network.

Enabling SSH access (optional)

We can add sshd to the startup of our system so we can access our Beaglebone using ssh.

# ln -s /mnt/p2/etc/init.d/sshd /mnt/p2/etc/runlevels/default

Enabling serial console access (optional)

By default the ttyS0 port is configured at 9600 bps. However, almost all of the ARM devices run the serial port at 115200 bps. Also, in the case of the Beaglebone, the port is ttyO0(that is a t-t-y-capitalO-zero) instead of the normal ttyS0. So this should be added to the /etc/inittab file:

# nano -w /mnt/p2/etc/inittab

(Replace 9600 with 115200 on the ttyS0 line, and replace ttyS0 with ttyO0)
s0:12345:respawn:/sbin/agetty 115200 ttyO0 vt100

Also for enabling root access through the serial console, since we are not using the default ttyS0 port, we need to add the Beaglebone port to /etc/securetty.

# nano -w /mnt/p2/etc/securetty

(Simply add ttyO0 to the end of the file)
ttyO0

Finishing the installation

Let's unmount the SD card

(May take a while depending the speed of your SD card)
# umount /mnt/p1 /mnt/p2

This is pretty much all of the installation. I'd highly recommend that you read all the recommendations of the handbook.

6.  Booting up our new system

Accessing the console (optional)

If you want to see the beaglebone boot, connect an USB cable to the mini USB port (you should have it if you aren't powering it using an external PSU...) and load the ftdi_sio kernel module with the following command:

(Remember we're still root)
# modprobe ftdi_sio vendor=0x0403 product=0xa6d0

New devices called ttyUSB0 and ttyUSB1 should show up on /dev. Use them with a terminal emulator like picocom or minicom configuring them with 115200bps 8N1

Once you have the card ready, put it into the Beaglebone... and you should be able to boot it.

7.  After booting

Troubles with USB

Due to a bug on the USB driver used in the beaglebone, once you unplug the first USB device, it won't detect any new USB device.

The quick fix to make the USB port work again, you must do:

# echo F > /proc/driver/musb_hdrc.1

This is really uncofortable if you have to do it everytime you plug a new USB device, so a workaround is to use udev rules. This idea comes from the angstrom people, so thank them.

Create a new udev rule in /etc/udev/rules.d, we'll name it 99-hokey-pokey.rules.

# nano /etc/udev/rules.d/99-hokey-pokey.rules


ACTION=="remove", DEVPATH=="/devices/platform/omap/ti81xx-usbss/musb-hdrc.1/usb1/1-1",  RUN+="/usr/bin/hokey-pokey.sh"

Create this script which will call the command I mentioned above everytime an USB device gets desconnected. We'll name it /usr/bin/hokey-pokey.sh

# nano /usr/bin/hokey-pokey.sh


#!/bin/sh

sleep 1
echo F > /proc/driver/musb_hdrc.1
sleep 1
echo F > /proc/driver/musb_hdrc.1

Give it executable permissions
# chmod +x /usr/bin/hokey-pokey.sh

And thats it. Hopefully this gets fixed in the future.

Keeping the clock up to date

One of the problems of the Beaglebone is that it doesn't save the date because it doesn't have a battery for the clock.

After logging into our new Gentoo on Beaglebone installation, I'd recommend setting a date and emerging net-misc/ntp to keep the clock up-to-date. Also it's recommended to put both ntp-client and ntpd to boot on startup, so you get a proper date setup.

However, keep in mind that NTP requires a network connection and a NTP server being reachable, either on the local network or on the Internet.

(Make sure you're root)
# emerge net-misc/ntp

(Put both ntp-client and ntpd to boot on startup)
# rc-update add ntpd default
# rc-update add ntp-client default

(Start ntp-client and ntpd)
# /etc/init.d/ntp-client start
# /etc/init.d/ntpd start

8.  References

You may find more documentation about the device itself and Linux-related at the following links:

• http://beagleboard.org/bone

9.  Thanks

• http://beagleboard.org/bone for providing me a Beaglebone to document and support Gentoo on it
• Siarhei Siamashka (ssvb) for giving helpful hints

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.