BeagleBone Black

Installing Gentoo on a Beaglebone Black Rev. C
These instructions are specifically for the Beaglebone Black Rev. C. I found instructions here dev.gentoo.org but they were for a 3.8 kernel. 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
More info: wiki.gentoo.org

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 /usr/local/portage/cross-armv7a-hardfloat-linux-gnueabihf and stuff under /usr/armv7a-hardfloat-linux-gnueabihf.
 * 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.
 * 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:.

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 and extract.
 * 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 user.name or user.email, try this:
 * If you get any GIT errors about not having user.name or user.email, try this:


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


 * copy bb.org config to .config 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 LOADADDR you'll get a build error.
 * I have no idea why the LOADADDR is set to this, just following instructions from TI here: wiki.ti.com. If you omit the LOADADDR 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
 * releases/arm/autobuilds/20140819/stage3-armv7a_hardfp-20140819.tar.bz2
 * snapshots/portage-latest.tar.bz2.


 * extract the tarballs:
 * 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 ~/bbb/deploy/etc/fstab:
 * edit ~/bbb/deploy/etc/fstab:


 * edit ~/bbb/deploy/etc/shadow so root can login:
 * grab hash output, edit deploy/etc/shadow, and put here:
 * grab hash output, edit deploy/etc/shadow, and put here:


 * edit ~/bbb/deploy/etc/inittab since everyone expects serial port to run at 115200 and have the name ttyO0

Optional

 * setup a static IP on your BBB first, since we don't have dhcpcd installed: edit ~/bbb/deploy/etc/conf.d/net.


 * 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
if | -z $2 || -z $3 || -z $4 then echo "mksd-am335x Usage:" echo "	mksd-am335x    " echo "	Example: mksd-am335x /dev/sdc MLO u-boot.img uImage nfs.tar.gz" exit fi if ! -e $2 then echo "Incorrect MLO location!" exit fi if ! -e $3 then echo "Incorrect u-boot.img location!" exit fi if ! -e $4 then echo "Incorrect uImage location!" exithttp://elinux.org/Beagleboard:BeagleBoneBlack#BeagleBone_Black_Connector_and_Switch_Locations fi if ! -e $5 then echo "Incorrect rootfs location!" exit fi echo "All data on "$1" now will be destroyed! Continue? [y/n]" read ans if ! [ $ans == 'y' ] then exit fi echo "[Partitioning $1...]" DRIVE=$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 CYLINDERS=`echo $SIZE/255/63/512 | bc` echo CYLINDERS - $CYLINDERS { echo ,9,0x0C,* echo ,,,- } | sfdisk -D -H 255 -S 63 -C $CYLINDERS $DRIVE echo "[Making filesystems...]" mkfs.vfat -F 32 -n boot "$1"1 &> /dev/null mkfs.ext4 -L rootfs -T small "$1"2 &> /dev/null echo "[Copying files...]" mount "$1"1 /mnt/sdcard cp $2 /mnt/sdcard/MLO cp $3 /mnt/sdcard/u-boot.img umount "$1"1 mount "$1"2 /mnt/sdcard tar zxvf $5 -C /mnt/sdcard chmod 755 /mnt/sdcard umount "$1"2 echo "[Done]"
 * 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.
 * 1) !/bin/bash
 * 1) the "-T small" is so I have enough inodes for portage
 * 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 /dev/sdf.
 * 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)
 * (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 df -kh (and watch it go down in size, weird) and dmesg 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
/dev/ttyUSB0 speed(baud): 115200 data bits:   8 stop bits:   1 parity:      none flow control: none
 * 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:
 * emerge --sync

Tips and tricks

 * Do not bother setting boot options in the kernel: u-boot will override them.
 * 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:


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