BeagleBone Black 4

From Gentoo Wiki
Jump to:navigation Jump to:search

Installing Gentoo on a Beaglebone Black Rev. C and Derivatives

These instructions are specifically for the Beaglebone Black Rev. C. This guide will utilize u-boot from the original sources and a the 4.4.44 kernel from's github repo with patched Linux kernels.

You will need

  • USB -> serial port debug connector so you can view boot errors, see the u-boot prompt if necessary, and not have to switch out HDMI cables on your monitor. More detail at
  • >= 4GB micro SD card to create the Gentoo image (you can flash to the eMMC later).
  • An SD card reader/writer to write the Gentoo image.
  • Create the udev rules mentioned These work for eudev as well.

Emerge the toolchain

root #emerge dev-vcs/git sys-devel/crossdev sys-fs/dosfstools app-arch/lzop

Do not merge u-boot-tools as we will be using a version of u-boot configured specifically for the BBB (Beaglebone Black).

Create an overlay for crossdev

root #mkdir -p /var/db/repos/crossdev/{metadata,profiles}
root #echo "crossdev" > /var/db/repos/crossdev/profiles/repo_name
root #echo "masters = gentoo" > /var/db/repos/crossdev/metadata/layout.conf
root #chown -R portage:portage /var/db/repos/crossdev

Create /etc/portage/repos.conf/crossdev:

FILE /etc/portage/repos.conf/crossdev

More info: Creating an ebuild repository

Setup portage for crossdev

root #[ ! -d /etc/portage/package.use ] && mv -i package.use use && mkdir package.use && mv use package.use
root #[ ! -d /etc/portage/package.accept_keywords ] && mv -i package.accept_keywords accept_keywords && mkdir package.accept_keywords && mv accept_keywords package.accept_keywords
root #[ ! -d /etc/portage/package.license ] && mv -i package.license license && mkdir package.license && mv license package.license
root #[ ! -d /etc/portage/package.mask ] && mv -i package.mask mask && mkdir package.mask && mv mask package.mask
root #[ ! -d /etc/portage/package.unmask ] && mv -i package.unmask unmask && mkdir package.unmask && mv unmask package.unmask

More info: and Raspberry_Pi_Cross_building#crossdev.

Run Crossdev and let it setup a build environment

  • I settled on the tuple: "armv7a-hardfloat-linux-gnueabihf." TI recommends "arm-linux-gnueabihf."
user $crossdev -S -P -v -t armv7a-hardfloat-linux-gnueabihf
  • Test with:
    user $armv7a-hardfloat-linux-gnueabihf-gcc --version
You should see binutils, gcc, glibc, linux-headers, and gdb under /usr/local/portage/cross-armv7a-hardfloat-linux-gnueabihf and stuff under /usr/armv7a-hardfloat-linux-gnueabihf.
  • If you change your mind on the tuple, to uninstall the existing target run:
    user $crossdev -C armv7a-hardfloat-linux-gnueabihf

Configure U-Boot for the BBB

  • Note: We don't use [1] as it is out-of-date -- last commit is 3 years old.
  • make a build directory:
    user $mkdir ~/bbb
  • grab latest stable from and extract.
root #make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- am335x_boneblack_config
This article helped me find the correct make target:
user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf-
  • install mkimage so it's in your path. (As root)
    root #install tools/mkimage /usr/local/bin
  • to test: mkimage -V should say 2016.11.

Grab kernel configured specifically for the Beaglebone

  • Note: [2] is deprecated.
  • This one from will build the firmware into the kernel under linux/firmware and includes patched sources. The older versions required you to run, download the firmware manually, and drop it in the firmware folder.
  • Go to and decide which branch you want to check out. Here we use the latest long-term release kernel, 4.4.x
user $git clone -b 4.4 --single-branch
If you get any GIT errors about not having or, try this:
user $git config --global ""
user $git config --global "Username"
  • check that you got the right kernel version.
    user $cd linux; cat Makefile | head
and look at the top lines in Makefile:
FILE Makefile
  • copy config to .config by running the target:
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- bb.org_defconfig
  • If there's anything you want to tweak in the kernel, do so now with:
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- menuconfig
  • Compile the kernel:
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- -j8
  • Generate a uImage:
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- -j8 uImage dtbs LOADADDR=0x82000000
I have no idea why the LOADADDR is set to this, just following instructions from TI here: If you omit the LOADADDR you'll get a build error.
  • Compile kernel modules:
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- -j8 modules
  • make a directory for the kernel modules and install them:
    user $mkdir ~/bbb/linux_modules
    user $make ARCH=arm CROSS_COMPILE=armv7a-hardfloat-linux-gnueabihf- INSTALL_MOD_PATH=../linux_modules modules_install

Create the root filesystem for the SD card

  • grab the latest Gentoo source from a mirror
  • extract the tarballs:
user $mkdir ~/bbb/deploy
Add username for root paths:
user $export user=$(whoami)
As root, extract the stage3 since it will execute mknod:
root #tar xjpf stage3-armv7a_hardfp-20121006.tar.bz2 -C /home/${user}/bbb/deploy
As root, extract the portage snapshot:
root #tar xjpf portage-latest.tar.bz2 -C /home/${user}/bbb/deploy/usr/
  • Manually add files to root partition so u-boot will find them and boot your kernel.
user $cp ~/bbb/linux/arch/arm/boot/uImage ~/bbb/deploy/boot
IMPORTANT: BBB will not boot without this file:
user $cp ~/bbb/linux/arch/arm/boot/zImage ~/bbb/deploy/boot
Copy the device tree blob:
user $cp ~/bbb/linux/arch/arm/boot/dts/am335x-boneblack.dtb ~/bbb/deploy/boot
Copy the kernel modules:
user $cp -r ~/bbb/linux_modules/lib/modules ~/bbb/deploy/lib
  • Make a directory where I can mount the boot partition under /
    user $mkdir ~/bbb/deploy/boot/uboot
edit ~/bbb/deploy/etc/fstab:
FILE ~/bbb/deploy/etc/fstab
/dev/mmcblk0p2		/		ext4		noatime,errors=remount-ro	0 1
/dev/mmcblk0p1		/boot/uboot	auto		noatime				1 2
  • edit ~/bbb/deploy/etc/shadow so root can login:
    root #openssl passwd -1
grab hash output, edit deploy/etc/shadow, and put here:
FILE ~/bbb/deploy/etc/shadow
  • edit ~/bbb/deploy/etc/inittab since everyone expects serial port to run at 115200 and have the name ttyO0
FILE ~/bbb/deploy/etc/inittab
s0:12345:respawn:/sbin/agetty -L 115200 ttyS0 vt100


  • setup a static IP on your BBB first, since we don't have dhcpcd installed: edit ~/bbb/deploy/etc/conf.d/net.
FILE ~/bbb/deploy/etc/conf.d/net
config_eth0="<your IP> netmask <your netmask> brd <network broadcast IP>"
routes_eth0="default via <your router IP>"
dns_servers_eth0="<nameserver IP> <another nameserver IP>"
  • edit ~/bbb/deploy/etc/conf.d/hostname:
FILE ~/bbb/deploy/etc/conf.d/hostname
  • add net.eth0 to startup:
root #cd /home/${user}/bbb/deploy/etc/init.d; ln -s net.lo net.eth0
root #cd /home/${user}/bbb/deploy/etc/runlevels/default; ln -s /etc/init.d/net.eth0
  • replace hwclock with swclock. BBB does not have a built-in hardware clock so setting based on last modified date is the next best thing.
root #cd /home/${user}/bbb/deploy/etc/runlevels/boot
root #unlink hwclock
root #ln -s /etc/init.d/swclock .
  • Set timezone (can't finish until system is up and running).
root #ls /usr/share/zoneinfo
root #echo "America/YOUR_TIMEZONE" > /home/${user}/deploy/etc/timezone

Finish creating the root filesystem for the SD card

  • tar it all up:
root #cd /home/${user}/bbb/deploy
root #tar cvzpf ../deploy.tar.gz .

Format the MicroSD card the way BeagleBoard wants it

  • Similar scripts:,
  • I chose a modified version of TI's from here: Original is under host-tools/
  • Use 'lsblk' to verify your SD device IDs match the ones used in the script. For a device mmcblk0, the script assumes /dev/mmcblk0{p1,p2} as partitions.
FILE host-tools/
if [[ -z $1 || -z $2 || -z $3 || -z $4 ]]
	echo "mksd-am335x Usage:"
	echo "	mksd-am335x <device> <MLO> <u-boot.img> <uImage> <rootfs tar.gz>"
	echo "	Example: mksd-am335x /dev/sdc MLO u-boot.img uImage nfs.tar.gz"
if ! [[ -e $2 ]]
	echo "Incorrect MLO location!"
if ! [[ -e $3 ]]
	echo "Incorrect u-boot.img location!"
if ! [[ -e $4 ]]
	echo "Incorrect uImage location!"
if ! [[ -e $5 ]]
	echo "Incorrect rootfs location!"

echo "All data on "$1" now will be destroyed! Continue? [y/n]"
read ans
if ! [ $ans == 'y' ]

echo "[Partitioning $1...]"

dd if=/dev/zero of=$DRIVE bs=1024 count=1024
SIZE=`fdisk -l $DRIVE | grep Disk | awk '{print $5}'`
echo DISK SIZE - $SIZE bytes

parted -s $DRIVE mklabel msdos
parted -s $DRIVE unit cyl mkpart primary fat32 -- 0 9
parted -s $DRIVE set 1 boot on
parted -s $DRIVE unit cyl mkpart primary ext4 -- 9 -2

echo "[Making filesystems...]"

mkfs.vfat -F 32 -n boot "$1"p1 &> /dev/null
# the "-T small" is so I have enough inodes for portage
mkfs.ext4 -L rootfs -T small "$1"p2 &> /dev/null

echo "[Copying files...]"

mount "$1"p1 /mnt/usbstick
cp $2 /mnt/usbstick/MLO
cp $3 /mnt/usbstick/u-boot.img
umount "$1"p1

mount "$1"p2 /mnt/usbstick
tar zxvf $5 -C /mnt/usbstick
chmod 755 /mnt/usbstick
umount "$1"p2

echo "[Done]"
  • Run the script to format the SD card. All data will be lost on it.
root #mkdir /mnt/usbstick
plugin your SD card and check dmesg for the name of your SD card: mine was /dev/mmcblk0.
You will probably have to manually umount the sdcard if Linux automounts it. The script will complain if the SD card is mounted.
(as root)
root #cd /home/${user}/bbb; ./ /dev/mmcblk0 u-boot-2016.11/MLO u-boot-2016.11/u-boot.img linux/arch/arm/boot/uImage deploy.tar.gz
  • Don't pull out the card until the light on the SD-Card reader stops flashing, even if the script has stopped. I guess it takes awhile for the journal to catch up. Check df -kh (and watch it go down in size, weird) and dmesg for more info and possible errors. I have seen INFO: task umount:2515 blocked for more than 120 seconds. messages before and it will still be blinking. When it's done the reader light should stay illuminated.

Almost ready

  • Emerge a serial terminal emulator like PuTTY, etc.
  • Create a profile with these settings:
CODE Terminal Profile Settings
speed(baud):  115200
data bits:    8
stop bits:    1
parity:       none
flow control: none
  • Open your serial terminal window with this profile.
  • Connect your serial debug cable to the BBB as described here:
  • Insert your SD card into the BBB.
  • Hold down the button closest to the SD card and press the button closest to the Ethernet port once. More info:

Moment of truth

  • You should see a Gentoo prompt! Thank God!

Optional follow-on

  • you should now have a running system and network connectivity
    root #date MMDDhhmmYYYY
    root #emerge --config sys-libs/timezone-data
  • Time will start from this point on next time you boot:
    root #touch /sbin/rc
    root #emerge --sync

Tips and tricks

  • If you want to override boot options without messing with uEnv.txt, make sure you compile your kernel with Boot options->Kernel command line type: "Always use the default kernel command string," or CONFIG_CMDLINE_FORCE=y. Then edit the Default kernel command string as desired.
  • You can create a /boot/uEnv.txt and override u-boot settings if you want. I couldn't figure this out so please add this info if you can.
  • If you just need to tweak u-boot or kernel files:
root #mount /dev/mmcblk0p1 /mnt/p1; mount /dev/mmcblk0p2 /mnt/p2;
root #cp /home/${user}/bbb/u-boot-2016.11/{MLO,u-boot.img} /mnt/p1
root #cp /home/${user}/bbb/linux/arch/arm/boot/{uImage,zImage,/dts/am335x-boneblack.dtb} /mnt/p2
  • If you need to dump a new root file structure to the SD card. Be very careful here, don't want to replace your root filesystem with ARM junk.
As root:
root #mount /dev/mmcblk0p2 /mnt/usbstick
root #rm -rf /mnt/usbstick/*
root #cd /home/${user}/bbb
root #tar xzvpf deploy.tar.gz -C /mnt/usbstick

Older Beaglebone versions

The installation procedure also works for the Beaglebone aka Beaglebone white (see This was tested with revision A6a. Instead of the am335x-boneblack.dtb the am335x-bone.dtb has to be used.

See also

External resources