BeagleBone Black

Installing Gentoo on a Beaglebone Black Rev. C
These instructions are specifically for the Beaglebone Black Rev. C. This guide will utilize u-boot from the original sources and a modified 3.14.17 kernel from Beagleboard.org's github repo.

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 elinux.org.
 * 4GB micro SD card to create the Gentoo image (you can flash to NAND later).
 * An SD card reader/writer to write the Gentoo image.
 * Create the udev rules mentioned beagleboard.org. These work for eudev as well.

Emerge the toolchain
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
edit /etc/portage/make.conf:

Setup portage for crossdev
More info: forums.gentoo.org and wiki.gentoo.org.

Run Crossdev and let it setup a build environment

 * I settled on the tuple: "armv7a-hardfloat-linux-gnueabihf." TI recommends "arm-linux-gnueabihf." wiki.ti.com
 * Test with:
 * You should see binutils, gcc, glibc, linux-headers, and gdb under and stuff under.
 * You should see binutils, gcc, glibc, linux-headers, and gdb under and stuff under.


 * If you change your mind on the tuple, to uninstall the existing target run:

Configure U-Boot for the BBB

 * Note: is out-of-date, last commit is 3 years old.
 * make a build directory:
 * grab latest stable from denx.de, extract and  to the extracted directory.
 * This article helped me find the correct make target: crashcourse.ca.
 * This article helped me find the correct make target: crashcourse.ca.


 * install mkimage so it's in your path. (As root)
 * to test:  should say 2014.07.
 * to test:  should say 2014.07.

Grab kernel configured specifically for the Beaglebone

 * Note: is deprecated.
 * This one from beaglebone.org will build the firmware into the kernel under linux/firmware and includes patched sources. The older versions required you to run patch.sh, download the firmware manually, and drop it in the firmware folder.
 * Go to github.com and decide which branch you want to check out. I settled on the latest long-term release kernel, 3.14.17.
 * If you get any GIT errors about not having or, try this:
 * If you get any GIT errors about not having or, try this:


 * check that you got the right kernel version.
 * and look at the top lines in Makefile:


 * copy bb.org config to by running the bb.org target:
 * If there's anything you want to tweak in the kernel, do so now with:
 * Compile the kernel:
 * Generate a uImage:
 * I have no idea why the LOADADDR is set to this, just following instructions from TI here: wiki.ti.com. If you omit the   you'll get a build error.


 * Compile kernel modules:
 * make a directory for the kernel modules and install them:

Create the root filesystem for the SD card

 * grab the latest Gentoo source from your mirror


 * extract the tarballs:


 * Add username for root paths:
 * As root, extract the stage3 since it will execute mknod:
 * As root, extract the portage snapshot:
 * As root, extract the portage snapshot:


 * Manually add files to root partition so u-boot will find them and boot your kernel.
 * IMPORTANT: BBB will not boot without this file:
 * Copy the device tree blob:
 * Copy the kernel modules:
 * Copy the kernel modules:


 * Make a directory where I can mount the boot partition under
 * edit :


 * edit so root can login:
 * grab hash output, edit, and put here:


 * edit since everyone expects serial port to run at 115200 and have the name

Optional

 * setup a static IP on your BBB first, since we don't have dhcpcd installed: edit.


 * edit ~/bbb/deploy/etc/conf.d/hostname:


 * add net.eth0 to startup:


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


 * Set timezone (can't finish until system is up and running).

Finish creating the root filesystem for the SD card

 * tar it all up:

Format the MicroSD card the way BeagleBoard wants it
Sfdisk devs having not played nice I adapted the formatting without CHS, as any implementation has been deemed useless and so removed. Please tell me if anything bad happens without the CHS settings!
 * Similar scripts: github.com/beagleboard, dev.gentoo.org, omappedia.org.
 * I chose a modified version of TI's from here: downloads.ti.com. Original is under host-tools/mksd-am335x.sh.
 * Use 'lsblk' to verify your sd device id. If through an sd card reader it might be mmcblk0 with partitions mmcblk0p1 & p2. If this is the case alter the script before hand to use "$1"p1 and "$1"p2 instead of "$1"1 & "$1"2.


 * Run the script to format the SD card. All data will be lost on it.


 * plugin your SD card and check dmesg for the name of your SD card: mine was.
 * 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)


 * 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   (and watch it go down in size, weird) and   for more info and possible errors.  I have seen   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:


 * Open your serial terminal window with this profile.
 * Connect your serial debug cable to the BBB as described here: elinux.org.
 * 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: elinux.org.

Moment of truth

 * You should see a Gentoo prompt! Thank God!

Optional follow-on

 * you should now have a running system and network connectivity
 * Time will start from this point on next time you boot:

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 .  Then edit the Default kernel command string as desired.
 * You can create a 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:


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

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

External resources

 * BeagleBone Black on elinux.org