wiki:GSoC/2015/BeagleBSPPortingUmon

Beagle BSP Improvements - Porting uMon to the Beaglebone Black

The goal of this project is to port uMon, which is an open-source bootloader, to the Beaglebone Black in order to replace the more license-restrictive U-boot.

Mentors

Ben Gras, Ed Sutter, DrJoel?, Thomas Doerfler

Student

Jarielle Catbagan

Project Description

The goal of this project is to undertake the development of porting uMon to the Beaglebone Black. This is part of an effort to replace the limitations associated with a GPL-licensed bootloader such as U-boot that currently exists on the board. This project will require understanding the boot process that the Beaglebone Black and the AM335x processor in general undergo in order to initialize the system properly, locate an application image, and then to execute it.

The only responsibility that uMon has, and will be the primary focus that this project will strive to achieve, is to initialize the whole system to the point where an application image can be transferred into main memory and then executed. There are a multitude of sources where an application image can be obtained, such as via Ethernet, UART, or directly from a physical memory medium, where a majority will be integrated into the uMon port for the Beaglebone Black initially.

One of the goals of this project is establishing the mechanisms to locate and transfer an application image. When the AM335x processor powers on, the first program that runs is the internal ROM code. This ROM code does the minimal amount of tasks to initialize the processor and then to locate for an application image. This application will then be transferred into the internal SRAM where control will then be passed. At this point in time, the functionality and memory are limited. It is up to this transferred image to set up any additional functions, to initialize a much larger external memory, and to possibly locate and execute a larger application image, which in many cases would be an operating system.

The image that will be transferred into the internal SRAM by the internal ROM code will be uMon. uMon will then initialize the system even further, most importantly the external DDR3 RAM, and then transfer the main application image into this external memory before passing control to it. How this main application image is transferred is another one of the primary focus of this project and that is to provide the capability to provide options for booting from Ethernet, UART, or from an external non-volatile memory such as the onboard eMMC or a uSD card.

Building uMon

In order to build uMon, navigate to the Beaglebone Black port directory and invoke the following commands to setup the environment and build uMon.

source envsetup
make boot

After the build completes, this should produce a couple of binaries under 'build_BEAGLEBONEBLACK' for booting uMon either via UART or from an SD card which can be transferred to the on-board eMMC. For convenience there is a script located in the same directory that will automate the process of installing the uMon image into an SD card.

Booting

SD Card:

The Beaglebone Black can boot uMon from an SD card using two different boot modes. The first boot mode is to boot using "raw" mode. The second boot mode is to boot from a FAT primary partition marked as bootable. The details and the steps required to set up the SD card for each of the boot modes are elaborated in the following two sections on SD card booting. For more information on "raw" mode and FAT mode, please refer to the AM335s TRM Sections 26.1.7.5.5 "MMC/SD Read Sector Procedure in Raw Mode" and 26.1.7.5.6 "MMC/SD Read Sector Procedure in FAT Mode" respectively.

In order to boot uMon from an SD card using FAT mode, a GP Header must be prepended to the uMon image. In the case of booting uMon using "raw" mode, both a Configuration Header TOC Structure followed by a GP Header must be prepended to the uMon image.

The GP Header is 8 bytes long where the first 4 bytes specify the size of the uMon image that will be transferred while the last 4 bytes specify both the destination address where the uMon image will be transferred to and the entry point.

For information on the layout of the Configuration Header TOC Structure required for "raw" mode booting, please refer to the AM335x TRM Section 26.1.7.5.5.1 "Configuration Header".

One thing worth mentioning is that the Beaglebone Black is connected to the SD card using MMC0 and as a result the size of the SD card must not be greater than 4GB. This is indicated in the AM335x TRM Section 26.1.7.5.2 "System Interconnection".

In order to configure the Beaglebone Black to boot from an SD card, a uSD must be inserted and the boot switch held down while the board is powered up. Once the board is powered on, the boot switch can be released. If the attempt to boot from the uSD fails, the Beaglebone Black will fall back and attempt to boot using UART. As a result, this will provide a way to determine whether the boot from SD has succeeded or not.

Before starting, it is recommended that the device that will be manipulated is verified to be the right device. An approach to determine the right device name assigned to the SD card is by observing the output of

cat /proc/partitions

before and after inserting the SD card.

RAW MODE:

In order to boot from an SD card using "raw" mode, the uMon image must be prepended with a Configuration Header TOC Structure and a GP Header. The GP Header is placed right after the Configuration Header TOC Structure.

When uMon is built, a uMon image containing the necessary headers is already created and is located under ./build_BEAGLEBONEBLACK.

The next step is to setup the SD card. Fortunately, the script ./sd_setup.sh can be used to automate the process of setting up an SD card for "raw" mode booting. To do so, invoke the script as

./sd_setup.sh RAW <device>

<device> shown above and for the remainder of this document will refer to the SD card.

The following information specify how to manually set up the SD card.

With the proper headers prepended, the image is ready to be booted. In order for the Beaglebone Black/AM335x to boot the image, the image must be placed at one of the offsets 0x00000/0x20000/0x40000/0x60000.

As an example, to place the uMon image at the first offset

# Get the size of the uMon image to transfer into the SD card
export UMON_IMG_SIZE=`wc --bytes <uMon image> | cut -f 1 -d ' '`

# Transfer the uMon image at offset 0x00000
dd if=<uMon image> bs=1 count=$UMON_IMG_SIZE of=/dev/<device>

where <uMon image> is the path to the uMon image prepended with a Configuration Header TOC Structure and a GP Header.

FAT MODE:

In FAT Mode, an "MLO" file is searched for in the root directory of a primary partition formatted as FAT12/FAT16 or FAT32 and marked bootable. This "MLO" file must contain a GP Header followed by the uMon image. When uMon is built, an "MLO" file is already created and is located in ./build_BEAGLEBONEBLACK.

For convenience, preparing the SD card for FAT Mode booting has been automated through the use of the same aforementioned script, ./sd_setup.sh.

Invoking the script in order to create an SD card for FAT mode booting is as follows:

./sd_setup.sh FAT <device>

The script simply sets up a primary partition on the SD card, marks it as bootable, formats it as FAT16 and then transfers the MLO file under ./build_BEAGLEBONEBLACK to the root directory of the primary partition on the SD card.

The following elaborates the sequence of steps on how exactly an SD card is prepared for FAT Mode booting for the Beaglebone Black to boot from.

Assuming that the SD card has not been formatted yet...

Just to be safe, clear out the partition table at the base of the SD card to start fresh.

dd if=/dev/zero of=<device> bs=1M count=1

The next step is to create a primary partition with the filesystem type set to FAT16. This primary partition will be placed as an entry in an MBR located in the first sector of the SD card. Fortunately, these intial steps are taken care of by the fdisk utility.

To allocate a partition that will be formatted as FAT16 and to create an entry for the partition in the MBR,

fdisk <device>

Suppose the SD card is registered under /dev as "sdc", this would be

fdisk /dev/sdc

fdisk will then present a command-line dialog.

From here, a new partition must be created using 'n'. This partition must have a type of 0x06 for FAT16 which is set with 't' and with the size allocated to the partition to be at least 3MB. This size is the minimum size required and is more than enough to hold a uMon image and to allow for future expansion. It is recommended that not all of the sectors of the SD card are allocated to the FAT16 primary partition in order to provide room for the possibility of storing user data or perhaps a kernel.

Once that is done, the next step is to mark the primary partition as bootable. This is done using the 'a' option.

With all that in place, the partition can be verified before writing it to the SD card with 'p'. Once the partition has been verified, it can be written to the SD card using 'w'.

After using fdisk to set up the partition, the new partition can be viewed under /dev. So for example, if the base of the SD card is given as /dev/sdc, then the newly created FAT16 partition will be given as /dev/sdc1.

The next step is to format this partition as FAT16:

mkfs.fat -f 2 -F 16 -M 0xF8 -s 1 -S 512 <device>

with <device> set to the primary partition of the SD card.

The final step is to place the "MLO" file in the root directory of the FAT16 primary partition.

cd ~
mkdir mnt
mount <device> mnt
cp <path_to_umon>/ports/beagleboneblack/build_BEAGLEBONEBLACK/MLO mnt
umount mnt
rmdir mnt

In the previous set of commands, <device> is set to the primary partition of the SD card that was recently formatted as FAT16.

The SD card is now ready.

eMMC:

Booting uMon from the onboard eMMC requires a multiple-step procedure that will be simplified in the future as the uMon port progresses.

To transfer a uMon image into the onboard eMMC requires an SD card where uMon is configured to boot in RAW mode from a known offset.

With uMon configured to boot in RAW mode from a known offset in the SD card, the next step is to determine the size of the uMon image in 512-byte blocks.

With all of this in place, the sequence of uMon commands required to transfer the uMon image are as follows:

sd init
mmc init
sd read <destination in RAM> <SD sector address> <# of 512-byte blocks>
mmc write <source in RAM> <eMMC sector address> <# of 512-byte blocks>

With these steps, the uMon image is first transferred into DDR3 RAM and then written to the eMMC. The reason for this appraoch is that there is currently no supported mechanism to write the eMMC directly from an SD card.

The user must take care to transfer the uMon image in a location in RAM not currently owned by the uMon image currently in execution.

As for the final destination in the eMMC, the uMon image must be stored in a locatation where the internal ROM-bootloader will be able to find and boot this image.

UART:

Unlike booting from SD, booting via UART does not require any GP Header, Configuration Header TOC Structure, or both to be prepended to the uMon image. The uMon image that will be booted using UART is boot.bin which is located in ./build_BEAGLEBONEBLACK.

In order to boot from UART, a 3.3V USB-to-Serial cable is required, e.g. the FTDI USB TTL Serial cable is a possible option.

The last requirement is to have a terminal emulator (e.g. minicom/picocom/etc.) set up to perform XMODEM transfers using 1K packets and 16-bit CRC.

To initiate the UART booting procedure on the Beaglebone Black, ensure that there is no uSD card inserted and then hold the boot switch down while powering up the board. Once the board is powered on, the boot switch can be released.

If a terminal emulator is set up already and connected to the serial port of the Beaglebone Black, the character 'C' will be outputted continuously. This indicates that the UART booting procedure has initiated and is waiting for an image to be transferred via UART.

From here, the uMon image can now be transferred using the terminal emulator.

For more information on the UART boot procedure, please refer to the AM335x TRM Section 26.1.8.5 "UART Boot Procedure".

Current Development Efforts

  1. Ethernet functionality
  2. Booting an application image using either TFS or TFS-less mechanisms
  3. Integrating uMon into RSB

References

Last modified on 08/21/15 at 18:18:14 Last modified on 08/21/15 18:18:14