Changes between Version 1 and Version 2 of GSoC/2015/BeagleBSPPortingUmon


Ignore:
Timestamp:
08/21/15 18:18:14 (9 years ago)
Author:
Jarielle Catbagan
Comment:

Updated wiki for Beagle BSP Improvements - Porting uMon to the Beaglebone Black

Legend:

Unmodified
Added
Removed
Modified

  • GSoC/2015/BeagleBSPPortingUmon

    v1 v2  
    1 = Beagle BSP Improvements - Porting Umon to the Beaglebone Black =
    2 
    3 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.
     1= Beagle BSP Improvements - Porting uMon to the Beaglebone Black =
     2
     3The 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.
    44
    55= Mentors =
    … …  
    1313= Project Description =
    1414
    15 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.
    16 
    17 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. 
     15The 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.
     16
     17The 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. 
    1818
    1919One 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. 
    2020
    21 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.
     21The 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.
     22
     23= Building uMon =
     24
     25In order to build uMon, navigate to the Beaglebone Black port directory and invoke the following commands to setup the environment and build uMon.
     26
     27
     28{{{
     29source envsetup
     30make boot
     31}}}
     32
     33After 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.
     34
     35= Booting =
     36
     37'''SD Card:'''
     38
     39The Beaglebone Black can boot uMon from an SD card using two different
     40boot modes.  The first boot mode is to boot using "raw" mode.  The
     41second boot mode is to boot from a FAT primary partition marked as
     42bootable.  The details and the steps required to set up the SD card
     43for each of the boot modes are elaborated in the following two sections
     44on SD card booting.  For more information on "raw" mode and FAT mode,
     45please refer to the AM335s TRM Sections 26.1.7.5.5 "MMC/SD Read Sector
     46Procedure in Raw Mode" and 26.1.7.5.6 "MMC/SD Read Sector Procedure
     47in FAT Mode" respectively.
     48
     49In order to boot uMon from an SD card using FAT mode, a GP Header must
     50be prepended to the uMon image.  In the case of booting uMon using
     51"raw" mode, both a Configuration Header TOC Structure followed by a
     52GP Header must be prepended to the uMon image.
     53
     54The GP Header is 8 bytes long where the first 4 bytes specify the size
     55of the uMon image that will be transferred while the last 4 bytes
     56specify both the destination address where the uMon image will be
     57transferred to and the entry point.
     58
     59For information on the layout of the Configuration Header TOC Structure
     60required for "raw" mode booting, please refer to the AM335x TRM
     61Section 26.1.7.5.5.1 "Configuration Header".
     62
     63One thing worth mentioning is that the Beaglebone Black is connected to
     64the SD card using MMC0 and as a result the size of the SD card must not
     65be greater than 4GB.  This is indicated in the AM335x TRM Section
     6626.1.7.5.2 "System Interconnection".
     67
     68In order to configure the Beaglebone Black to boot from an SD card,
     69a uSD must be inserted and the boot switch held down while the board
     70is powered up.  Once the board is powered on, the boot switch can
     71be released.  If the attempt to boot from the uSD fails, the
     72Beaglebone Black will fall back and attempt to boot using UART.
     73As a result, this will provide a way to determine whether the boot
     74from SD has succeeded or not.
     75
     76Before starting, it is recommended that the device that will be
     77manipulated is verified to be the right device.  An approach to
     78determine the right device name assigned to the SD card is by
     79observing the output of
     80
     81{{{
     82cat /proc/partitions
     83}}}
     84
     85before and after inserting the SD card.
     86
     87
     88RAW MODE:
     89
     90In order to boot from an SD card using "raw" mode, the uMon image
     91must be prepended with a Configuration Header TOC Structure and a
     92GP Header.  The GP Header is placed right after the Configuration
     93Header TOC Structure.
     94
     95When uMon is built, a uMon image containing the necessary headers
     96is already created and is located under ./build_BEAGLEBONEBLACK.
     97
     98The next step is to setup the SD card.  Fortunately, the script
     99./sd_setup.sh can be used to automate the process of setting up
     100an SD card for "raw" mode booting.  To do so, invoke the script as
     101
     102{{{
     103./sd_setup.sh RAW <device>
     104}}}
     105
     106<device> shown above and for the remainder of this document will
     107refer to the SD card.
     108
     109The following information specify how to manually set up the SD
     110card.
     111
     112With the proper headers prepended, the image is ready to be booted.
     113In order for the Beaglebone Black/AM335x to boot the image, the
     114image must be placed at one of the offsets
     1150x00000/0x20000/0x40000/0x60000.
     116
     117As an example, to place the uMon image at the first offset
     118
     119{{{
     120# Get the size of the uMon image to transfer into the SD card
     121export UMON_IMG_SIZE=`wc --bytes <uMon image> | cut -f 1 -d ' '`
     122
     123# Transfer the uMon image at offset 0x00000
     124dd if=<uMon image> bs=1 count=$UMON_IMG_SIZE of=/dev/<device>
     125}}}
     126
     127where <uMon image> is the path to the uMon image prepended with a
     128Configuration Header TOC Structure and a GP Header.
     129
     130
     131FAT MODE:
     132
     133In FAT Mode, an "MLO" file is searched for in the root directory of
     134a primary partition formatted as FAT12/FAT16 or FAT32 and marked
     135bootable.  This "MLO" file must contain a GP Header followed by the
     136uMon image.  When uMon is built, an "MLO" file is already created and
     137is located in ./build_BEAGLEBONEBLACK.
     138
     139For convenience, preparing the SD card for FAT Mode booting has
     140been automated through the use of the same aforementioned script,
     141./sd_setup.sh.
     142
     143Invoking the script in order to create an SD card for FAT mode booting
     144is as follows:
     145
     146{{{
     147./sd_setup.sh FAT <device>
     148}}}
     149
     150The script simply sets up a primary partition on the SD card, marks
     151it as bootable, formats it as FAT16 and then transfers the MLO file
     152under ./build_BEAGLEBONEBLACK to the root directory of the primary
     153partition on the SD card.
     154
     155The following elaborates the sequence of steps on how exactly an SD
     156card is prepared for FAT Mode booting for the Beaglebone Black
     157to boot from.
     158
     159Assuming that the SD card has not been formatted yet...
     160
     161Just to be safe, clear out the partition table at the base of the SD
     162card to start fresh.
     163
     164{{{
     165dd if=/dev/zero of=<device> bs=1M count=1
     166}}}
     167
     168The next step is to create a primary partition with the filesystem
     169type set to FAT16.  This primary partition will be placed as an entry
     170in an MBR located in the first sector of the SD card.  Fortunately,
     171these intial steps are taken care of by the fdisk utility.
     172
     173To allocate a partition that will be formatted as FAT16 and to create
     174an entry for the partition in the MBR,
     175
     176{{{
     177fdisk <device>
     178}}}
     179
     180Suppose the SD card is registered under /dev as "sdc", this would be
     181
     182{{{
     183fdisk /dev/sdc
     184}}}
     185
     186fdisk will then present a command-line dialog.
     187
     188From here, a new partition must be created using 'n'.  This partition
     189must have a type of 0x06 for FAT16 which is set with 't' and with the
     190size allocated to the partition to be at least 3MB.  This size is the
     191minimum size required and is more than enough to hold a uMon image and
     192to allow for future expansion.  It is recommended that not all of the
     193sectors of the SD card are allocated to the FAT16 primary partition
     194in order to provide room for the possibility of storing user data or
     195perhaps a kernel.
     196
     197Once that is done, the next step is to mark the primary partition as
     198bootable.  This is done using the 'a' option.
     199
     200With all that in place, the partition can be verified before writing
     201it to the SD card with 'p'.  Once the partition has been verified,
     202it can be written to the SD card using 'w'.
     203
     204After using fdisk to set up the partition, the new partition can be
     205viewed under /dev.  So for example, if the base of the SD card is given
     206as /dev/sdc, then the newly created FAT16 partition will be given as
     207/dev/sdc1.
     208
     209The next step is to format this partition as FAT16:
     210
     211{{{
     212mkfs.fat -f 2 -F 16 -M 0xF8 -s 1 -S 512 <device>
     213}}}
     214
     215with <device> set to the primary partition of the SD card.
     216
     217The final step is to place the "MLO" file in the root directory
     218of the FAT16 primary partition.
     219
     220{{{
     221cd ~
     222mkdir mnt
     223mount <device> mnt
     224cp <path_to_umon>/ports/beagleboneblack/build_BEAGLEBONEBLACK/MLO mnt
     225umount mnt
     226rmdir mnt
     227}}}
     228
     229In the previous set of commands, <device> is set to the primary
     230partition of the SD card that was recently formatted as FAT16.
     231
     232The SD card is now ready.
     233
     234
     235'''eMMC:'''
     236
     237Booting uMon from the onboard eMMC requires a multiple-step procedure
     238that will be simplified in the future as the uMon port progresses.
     239
     240To transfer a uMon image into the onboard eMMC requires an SD card where
     241uMon is configured to boot in RAW mode from a known offset.
     242
     243With uMon configured to boot in RAW mode from a known offset in the
     244SD card, the next step is to determine the size of the uMon image in
     245512-byte blocks.
     246
     247With all of this in place, the sequence of uMon commands required to
     248transfer the uMon image are as follows:
     249
     250{{{
     251sd init
     252mmc init
     253sd read <destination in RAM> <SD sector address> <# of 512-byte blocks>
     254mmc write <source in RAM> <eMMC sector address> <# of 512-byte blocks>
     255}}}
     256
     257With these steps, the uMon image is first transferred into DDR3 RAM
     258and then written to the eMMC.  The reason for this appraoch is that
     259there is currently no supported mechanism to write the eMMC directly
     260from an SD card.
     261
     262The user must take care to transfer the uMon image in a location in
     263RAM not currently owned by the uMon image currently in execution.
     264
     265As for the final destination in the eMMC, the uMon image must be stored
     266in a locatation where the internal ROM-bootloader will be able to find
     267and boot this image.
     268
     269
     270'''UART:'''
     271
     272Unlike booting from SD, booting via UART does not require any GP
     273Header, Configuration Header TOC Structure, or both to be prepended to
     274the uMon image.  The uMon image that will be booted using UART is
     275boot.bin which is located in ./build_BEAGLEBONEBLACK.
     276
     277In order to boot from UART, a 3.3V USB-to-Serial cable is required,
     278e.g. the FTDI USB TTL Serial cable is a possible option.
     279
     280The last requirement is to have a terminal emulator
     281(e.g. minicom/picocom/etc.) set up to perform XMODEM transfers using
     2821K packets and 16-bit CRC.
     283
     284To initiate the UART booting procedure on the Beaglebone Black, ensure
     285that there is no uSD card inserted and then hold the boot switch down
     286while powering up the board.  Once the board is powered on, the boot
     287switch can be released.
     288
     289If a terminal emulator is set up already and connected to the serial
     290port of the Beaglebone Black, the character 'C' will be outputted
     291continuously.  This indicates that the UART booting procedure has
     292initiated and is waiting for an image to be transferred via UART.
     293
     294From here, the uMon image can now be transferred using the terminal
     295emulator.
     296
     297For more information on the UART boot procedure, please refer to the
     298AM335x TRM Section 26.1.8.5 "UART Boot Procedure".
     299
     300= Current Development Efforts =
     301
     3021. Ethernet functionality
     3032. Booting an application image using either TFS or TFS-less mechanisms
     3043. Integrating uMon into RSB
    22305
    23306= References =
    24307- [http://www.jariellecatbagan.com Blog]
    25308- [https://github.com/jrcatbagan/umon Github Repo]
    26