Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Scripts to build a bootable FreeBSD image for BeagleBone.
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



Script to build a bootable FreeBSD image for BeagleBone.

Milestone reached: On 15 August, 2012, Oleksandr Tymoshenko (gonzo@)
finished merging the experimental "projects/armv6" work into
FreeBSD-CURRENT.  So all of the BeagleBone support (and related
support for many other late-model ARM systems) will be part of FreeBSD
10.0 when it ships.


What is a BeagleBone?

The BeagleBone is an ARM-based development/test board from the
BeagleBoard project.  It features a modern ARMv7 processor and a
wealth of on-chip peripheral support.  Details can be found at:

The BeagleBone is an easy way to learn about ARM development: it is
inexpensive (about $85) and does not require any special skills or
hardware to use.  You connect it to your desktop with a Mini USB cable
(which both powers the board and provides serial console access) and
boot it from a MicroSDHC card with the system image.

Once you have the BeagleBone working, you can expand it by connecting
it to Ethernet, adding USB peripherals (such as external disk drives
or wireless network interfaces) or attaching new hardware to the
connectors on the board.


How to Build a Disk Image

The script can build a complete bootable FreeBSD image
ready to be copied to a MicroSDHC card.  The script runs on
FreeBSD-CURRENT (March 2012 or later).

Using the script to build an image consists of three steps:


   You need to set the image size to match the MicroSDHC card you'll
   be using and verify that certain directories have enough free
   space.  There are lots of comments in this file to help you.

2. RUN as root

   $ sudo /bin/sh

   The script will first check that you have all the needed sources.
   If you don't, the script will tell you exactly how to obtain the
   missing pieces.  Follow the instructions and re-run the script
   until you have everything.

   As soon as it finds all the required pieces, the script will then
   compile everything and build the disk image.  This part of the
   process can take several hours.

3. COPY the image to a MicroSDHC card.

   The script will suggest a command to do this.

To verify the image, try mounting the card on your FreeBSD system.  It
should show up with two slices: The first slice is FAT formatted and
contains the necessary boot machinery, including the U-Boot loader.
The second slice is a standard FreeBSD UFS partition with the actual
system installed.


How to boot the BeagleBone

1. CONNECT the board to your FreeBSD system using a Mini-USB cable.
   The Mini-USB connector is on the bottom of the BeagleBone.

2. ACCESS the serial console on the board from your desktop:
   $ sudo cu -l /dev/ttyU1 -s 115200

   (You may need to load the uftdi driver into your kernel.)

3. INSERT the MicroSDHC card into your BeagleBone

4. REBOOT the BeagleBone by depressing the small
   switch next to the Ethernet port.



If the image fails to boot:
  * Look at the build and install logs under the 'work' directory.
  * Ask on the or mailing list for


Anatomy of a BeagleBone Boot Image

The FreeBSD bootable image for BeagleBone has both FAT
and UFS partitions containing the following files:

  FAT Partition
     MLO  - First stage boot, from U-Boot
     u-boot.img - Second stage: U-Boot
     uEnv.txt - configuration for U-Boot
     ubldr - Third stage: FreeBSD bootloader

  UFS Partition
     /boot/kernel - dynamic kernel
     ... rest of FreeBSD ...

The boot process works like this:

 1) AM3358 SoC ROM code inspects the MicroSDHC card, finds the MBR
    partition table and loads "MLO" from the first FAT partition.

    MLO is loaded before external RAM is initialized, so it has to be
    under 110k to fit within the on-chip RAM.  MLO here is a
    stripped-down version of U-Boot.

 2) MLO loads u-boot.img from the first FAT partition.

    U-Boot is a highly modular boot loader system that can be used on
    a wide variety of systems.  The loader is configured with built-in
    script commands that can be partially overridden by additional
    commands in the uEnv.txt file.

 3) U-Boot loads uEnv.txt and follows those commands to load ubldr at
    address 0x88000000.

    ubldr is a variant of FreeBSD's standard loader(8) program that is
    designed to be chain-loaded from U-Boot.  It calls into U-Boot for
    low-level device access, which allows ubldr to load FreeBSD on any
    system that supports U-Boot.

 4) ubldr locates the UFS partition, loads /boot/kernel/kernel from
    UFS to address 0x80200000 and executes it.



One of my goals is for the usual "make buildworld",
"make installworld", "make buildkernel", and
"make installkernel" to all work natively on the BeagleBone.

If you want to try this:
 * You probably want at least a 6G image.
 * Uncomment INSTALL_USR_SRC in
 * You may need to set up a swap partition; the script
   doesn't do this automatically (see PROJECTS list below)

After you boot the resulting image, you'll have a fully
populated /usr/src and can try rebuilding the system

Here are the commands you can try.  Patches appreciated
if you figure out how to deal with any of the issues here:

 $ make buildworld

Issue:  The new TARGET_ARCH support miscompiles
rtld (something to do with ARM_TP_ADDRESS
being used in the new rtld when it shouldn't?).

Issue: Buildworld takes about 30 hours.
I have not yet tried this with /usr/src and /usr/obj
mounted over NFS; that would help identify whether
the slow SD interface is the primary issue.

 $ make installworld
Status: The install per se is okay, but as soon
as the broken rtld (see above) gets installed,
the system crashes.

 $ make KERNCONF=BEAGLEBONE buildkernel
 $ make KERNCONF=BEAGLEBONE installkernel
Status:  This seems to work since the
TARGET_ARCH support went in.



If you're interested, there are a lot of things still to
be done:

 * Test ports.  I've tried building a few ports natively with
   somewhat mixed success.  Try things and let us know what
   you find.
 * Improve cpsw Ethernet driver.  Damjan Marion's initial
   driver works, but could certainly use more work.
 * USB.  Benjamin Gray has written a driver, it's in the
   tree, but I haven't had time to try to get it to actually
   work.  (Among other things, USB disk might be faster,
   allowing for faster native buildworlds/buildkernel.)
 * GPIO.  Some initial GPIO work is done but there are
   evolving ideas about how to make the GPIO framework
   more robust.
 * Other drivers.  The AM3358 SoC has a lot of hardware
   components that are still unsupported.
 * Modular kernel.  The kernel can load modules, I've successfully
   built and loaded cpsw as a module.
 * Refining the BEAGLEBONE kernel configuration:  For example,
   adding bpf allows dhclient to work.
 * Refining the system configuration:  A machine with only
   256MB RAM probably should not have sendmail, syslog, and
   other daemons started by default.
 * Memory.  Some recent change reduced available memory quite
   a bit.  Easy fix is to turn off things in rc.conf.
   There are probably also kernel tweaks possible.
 * Swap.  The script should allow you to specify a swap size
   and automatically adjust the disk layout accordingly.
 * USB client.  The Linux distros have a virtual Ethernet
   client that allows true single-cable development.  I would
   like to do something similar for FreeBSD.

Something went wrong with that request. Please try again.