Gentoo Logo

Gentoo on the BeagleBone Black's eMMC


1.  Overview

This guide assumes you've installed Gentoo onto an SD card by following the Gentoo on the BeagleBone Black guide and your BeagleBone Black is booted.

2.  Requirements

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

  • A BeagleBone Black booted
  • A working portage tree
  • A network connection

3.  Installation in the eMMC


Before we start the installation process, we need to emerge a few tools that aren't present on the default stage3.

Emerging needed tools

  • sys-fs/dosfstools - to create FAT32 filesystems
  • sys-devel/bc

Code Listing 3.1: Emerge needed tools

# emerge sys-fs/dosfstools sys-devel/bc

4.  eMMC setup


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

Formatting the eMMC

The following script will format your eMMC accordingly, creating two partitions. The first partition size is based on the size of the eMMC 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.

Warning: Make sure you're using /dev/mmcblk1 on this guide and *NOT* /dev/mmcblk0

Code Listing 4.1: Formatting the eMMC

# wget

# bash /dev/mmcblk1

If you plan to have a portage tree in the eMMC, you need to reformat the device with more inodes, otherwise you'll run out of them.

Code Listing 4.2: Reformatting the 2nd partition with more inodes

# mkfs.ext4 -i 4096 /dev/mmcblk1p2

5.  Installing Gentoo


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

  1. Extract stage3 to the 2nd partition of the eMMC
  2. Setup fstab
  3. Setup root password
  4. Configure hostname and networking (optional, but recommended)
  5. Enable SSH access (optional, but recommended)
  6. Enable serial console access (optional, but recommended)

Stages information

Here's some information about the stages.

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

We'll be using the new EABI, also called gnueabi.

Therefore, we need an armv7a-hardfloat-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 eMMC and extract the stage3 you downloaded.

Code Listing 5.1: Mounting the partition and extracting the stage3

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

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

Extracting a portage snapshot (optional)

Warning: Make sure you've formatted the eMMC with enough inodes

Code Listing 5.2: Extracting the snapshot

(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:

Code Listing 5.3: /mnt/p2/etc/fstab

(Comment/Remove this line)
/dev/BOOT               /boot           ext2            noauto,noatime  1 2

(This is the important part)
rootfs			/		auto		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!

Code Listing 5.4: Change the default root password

# chroot /mnt/p2 passwd

Setup hostname and networking

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

Using swclock

One of the problems the BeagleBone Black has, is that it doesn't have a battery to save the clock time. To mitigate this, on Gentoo we have an option in our init system called swclock which sets the date of the system upon boot from a last modified date of a file.

Code Listing 5.5: Adding swclock to the startup

# ln -sf /etc/init.d/swclock /mnt/p2/etc/runlevels/boot

We remove hwclock from the startup because it sets the date from the RTC, which is 2000-01-01 upon startup and overrides swclock's date.

Code Listing 5.6: Removing hwclock from the startup

# rm /mnt/p2/etc/runlevels/boot/hwclock

swclock uses the /sbin/rc's modification time to set the date, therefore we update it to have the current date and time.

Code Listing 5.7: Setting the correct date

# touch /mnt/p2/sbin/rc

Although this doesn't fix the issue, at least helps to set a sane date and time.

Note: Consider using NTP, documented on the next chapter

Enabling SSH access (optional)

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

Code Listing 5.8: Adding sshd to the startup

# ln -sf /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 Black, 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:

Code Listing 5.9: Configuring serial console

# 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

Copying U-Boot, MLO and the kernel to the eMMC

Now we'll mount the first partition of the eMMC, the first partition of the SD card, and copy the needed files from the first partition of the SD card to the first partition of the eMMC to boot our BeagleBone Black from eMMC.

Code Listing 5.10: Copying U-Boot, MLO and the kernel to the eMMC

(Make sure you're root)
(This is the 1st partition of the eMMC)
# mkdir /mnt/p1 ; mount /dev/mmcblk1p1 /mnt/p1

(This is the 1st partition of the SD card)
# mkdir /mnt/sd1 ; mount /dev/mmcblk0p1 /mnt/sd1
(This is the 2nd partition of the SD card)
# mkdir /mnt/sd2 ; mount /dev/mmcblk0p2 /mnt/sd2

# cp /mnt/sd1/{MLO,u-boot.img} /mnt/p1
# cp /mnt/sd2/boot/{uImage,am335x-boneblack.dtb} /mnt/p2/boot/

Finishing the installation

Let's unmount the eMMC and SD card

Code Listing 5.11: Unmounting the eMMC and SD card

(May take a while)
# umount /mnt/p1 /mnt/p2 /mnt/sd1 /mnt/sd2

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

Power off your BeagleBone Black, remove the SD card, and if everything was done correctly, it should boot from eMMC when you power it on again.

7.  After booting

Keeping the clock up to date

One of the problems of the BeagleBone Black 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 Black 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.

Code Listing 7.1: Emerging net-misc/ntp

(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

Expanding storage with an microSD card

You can expand easily the storage space on the BeagleBone Black using either an USB flash drive or an USB hard drive. You may also use a microSD card.

This however brings up an issue: right now, the bootloader checks for a microSD card with the default OMAP SD card layout(1st partition FAT containing the MLO an u-boot.img files) , if there is no card, it boots from the eMMC. If there's a card but it doesn't contain the OMAP layout, it simply fails to boot.

Therefore, to be able to use a microSD card for additional storage, the microSD card needs to have the OMAP layout. Thats what the script does.

Now, let's put the microSD card we want to use into our PC, and format it with the script.

Code Listing 7.2: Formatting the microSD card

# wget

(Replace mmcblk0 with the name of the device of your microSD card)
(If you use an USB-based SD card reader, the card may show up as a /dev/sd* device, for example /dev/sdd, replace it accordingly)
# bash /dev/mmcblk0

We need to pass an special environment to U-Boot, for doing so we need to create a file called uEnv.txt with the following contents on it.

Code Listing 7.3: uEnv.txt contents


Mount the first partition of the microSD card and copy this uEnv.txt file

Code Listing 7.4: Copying U-Boot and MLO to the microSD card

(Make sure you're root)
(Replace mmcblk0p1 with sdd1 if your card showed up as /dev/sdd)
# mkdir /mnt/p1 ; mount /dev/mmcblk0p1 /mnt/p1

# cp uEnv.txt /mnt/p1

(Unmount the partition)
# umount /mnt/p1

Now simply put the microSD card in the BeagleBone Black and it should boot using the rootfs from the eMMC. The eMMC will become /dev/mmcblk1 and the microSD card will be /dev/mmcblk0.

8.  References

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

9.  Thanks


Page updated April 21, 2013

Summary: This guide shows you how to install Gentoo on the BeagleBone Black's eMMC.

Raúl Porcel

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.