<NME> README
<BEF> BeagleBone is supported by FreeBSD-CURRENT since
August, 2012.  BeagleBone Black is also supported.

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.

============================================================

processor and a wealth of on-chip peripheral support.  Details can be
found at:

   http://beagleboard.org/bone

The BeagleBone is an easy way to learn about ARM development: it is
inexpensive (about $55) and does not require any special skills or
hardware to use.  You 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 boot the BeagleBone Black
--------------------------------

============================================================

How to Build a Disk Image
-------------------------

The beaglebsd.sh 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:

1. EDIT beaglebsd-config.sh

   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 beaglebsd.sh as root

   $ sudo /bin/sh beaglebsd.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
--------------------------


2. ACCESS the serial console

3. INSERT the MicroSDHC card into your BeagleBone Black

4. HOLD the boot switch next to the MicroSDHC slot

5. POWER the board by connecting it to a 5v power supply

Note:  The original BeagleBone has a built-in serial-to-USB
converter that is not present on the later BeagleBone Black.
This is why I recommend using a separate adapter cable.

Note:  As of July 2014, the micro-HDMI video output
on the BeagleBone Black is not supported.  To access the
board, you'll need to use a serial-to-USB adapter or SSH.

============================================================

How to boot the BeagleBone White
--------------------------------

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.

============================================================

Booting from eMMC for BeagleBone Black
--------------------------------------

Login as root and look at
   /root/copy-to-emmc.sh

This script can be used to copy a full FreeBSD system
from SD card to the eMMC.

============================================================

IF SOMETHING GOES WRONG
-----------------------

If the image fails to boot:
  * Look at the build and install logs under the 'work' directory.
  * Ask on the arm@freebsd.org or freebsd-current@freebsd.org mailing list for
help.

============================================================

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
     uboot.img - Second stage: U-Boot
     uEnv.txt - configuration for U-Boot
     BBONE.DTB - Binary FDT
     BBONE.DTS - Source FDT for reference
     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 UBOOT.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.

============================================================

NATIVE SOURCE REBUILDS
---------------------------------------

The usual "make buildworld", "make installworld",
"make buildkernel", and "make installkernel" all work
natively on the BeagleBone.  Due to limited memory and
slow speed of SD, a full buildworld can take 30-40 hours:

 $ make buildworld
 $ make installworld
 $ make KERNCONF=GENERIC buildkernel
 $ make KERNCONF=GENERIC installkernel

If you want to try this, you'll want an 8G image.  You can put the
source tree into the image when you build it by including the
following in your config.sh:

  option UsrSrc
  option SwapFile 768mb

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

Alternatively, of course, you can use "portsnap" to download and
install a ports tree, build the subversion port, and checkout the
FreeBSD source code using that.  This works, I've done it.

================================================================

<MSG> Reorganized README files a bit.

<DFF> @@ -3,11 +3,8 @@ freebsd-beaglebone
 
 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.
+BeagleBone is supported by FreeBSD-CURRENT since
+August, 2012.
 
 ============================================================
 
@@ -33,46 +30,6 @@ connectors on the board.
 
 ============================================================
 
-How to Build a Disk Image
--------------------------
-
-The beaglebsd.sh 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:
-
-1. EDIT beaglebsd-config.sh
-
-   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 beaglebsd.sh as root
-
-   $ sudo /bin/sh beaglebsd.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
 --------------------------
 

{'addition_count': 2, 'commit_subject': 'Reorganized README files a bit.', 'deletion_count': 45, 'file_extension': '', 'lang': 'README', 'license': 'bsd-2-clause', 'repo_name': 'freebsd/crochet'}