View source for U-Boot Overview

{{todo|Finish and polish|Michael Welling|project=oe 4,oe 5,mw,InProgress}}

Das U-Boot is the bootloader used on the majority of EMAC's ARM-based systems. It is loaded by the processor boot-ROM or low-level bootstrap code and performs device initialization followed by loading and starting the OS. EMAC has made modifications to U-Boot to add additional features when necessary. While generally used to load Linux, EMAC also uses U-Boot to load Windows CE and other operating systems. This page provides an introduction to U-Boot and common commands. Complete U-Boot documentation can be found at http://www.denx.de/wiki/U-Boot/WebHome

== Accessing the U-Boot Console ==
By default, U-Boot is set up to automatically boot the OS after a set timeout. The following steps will interrupt the boot process and access the U-Boot prompt.
<ol>
<li>Configure a serial connection with the target board using the settings specified for the hardware. Refer to the [[EMAC OE Getting Started Guide]] or other documentation for more information.</li>
<li>After a serial connection has been established, reboot the board.</li>
<li>When initial boot messages are printed to the serial terminal, press Enter in the serial terminal application. This should bring up the U-Boot prompt as seen below:</li>
 U-Boot 2009.06-rc1-svn1357 (Jul 08 2010 - 13:31:57)
 
 EMAC Inc. SOM-9M10/G45M
 
 DRAM:  128 MB
 NAND:  256 MiB
 DataFlash:AT45DB321
 Nb pages:   8192
 Page Size:    528
 Size= 4325376 bytes
 Logical address: 0xC0000000
 Area 0: C0000000 to C00041FF (RO) Bootstrap
 Area 1: C0004200 to C00083FF      Environment
 Area 2: C0008400 to C0041FFF (RO) U-Boot
 Area 3: C0042000 to C0251FFF      Kernel
 Area 4: C0252000 to C041FFFF      FS
 In:    serial
 Out:   serial
 Err:   serial
 Net:   macb0
 macb0: Starting autonegotiation...
 macb0: Autonegotiation complete
 macb0: link up, 100Mbps full-duplex (lpa: 0x45e1)
 Hit any key to stop autoboot:  0
 U-Boot>
<li>U-Boot commands may be entered at this prompt. To see all available commands, type <code>help</code>. Individual command help can be accessed by passing the command name as an argument to the <code>help</code> command. Available commands may differ between systems depending on applicable features.</li>
</ol>

== The U-Boot Environment ==
The U-Boot environment is stored in a pre-determined area of non-volatile storage. This is generally the same device that stores the U-Boot image and Linux Kernel. On systems that use raw NAND flash as the primary storage device, there is generally a secondary storage device used for low-level boot images such as U-Boot, the U-Boot environment, and the Linux kernel due to the complexities of bad-block handling with NAND flash. Devices using NOR flash typically use a portion of the NOR flash to store the bootloader and kernel. The <code>flinfo</code> command can provide an idea of the storage layout on the device, see below for an example:
 U-Boot> flinfo
 DataFlash:AT45DB321
 Nb pages:   8192
 Page Size:    528
 Size= 4325376 bytes
 Logical address: 0xC0000000
 Area 0: C0000000 to C00041FF (RO) Bootstrap
 Area 1: C0004200 to C00083FF      Environment
 Area 2: C0008400 to C0041FFF (RO) U-Boot
 Area 3: C0042000 to C0251FFF      Kernel
 Area 4: C0252000 to C041FFFF      FS

=== Standard Environment Variables ===
U-Boot uses a set of environmental variables to control the operation of the system. There are standard variables that are used for specific purposes by the system. The user can also add and combine variables to customize the system operation. The <code>printenv</code> command is used to view the current environment, as shown below:
 U-Boot> printenv
 baudrate=115200
 stdin=serial
 stdout=serial
 stderr=serial
 ethact=macb0
 ethaddr=00:50:C2:C9:2B:D6
 bootdelay=1
 bootargs=console=ttyS0,115200 root=/dev/mtdblock0 mtdparts=atmel_nand:128M(root),-(aux) ro rootfstype=jffs2
 bootcmd=cp.b 0xC0042000 0x70000000 0x210000; bootm 0x70000000
 kernel_name=uImage-2.6.30
 rootfs_name=rootfs.jffs2
 filesize=130B194
 fileaddr=70000000
 ipaddr=10.0.2.24
 serverip=10.0.2.60
 
 Environment size: 771/16892 bytes

Table 1 below defines many of the standard variables shown above.
{| class="wikitable"
|-
! Variable Name !! Purpose
|-
| <code>buadrate</code> || Serial console baud rate
|-
| <code>stdin</code> || The device to use for the console standard input
|-
| <code>stdout</code> || The device to use for the console standard output
|-
| <code>stderr</code> || The device to use for the console standard error outout
|-
| <code>ethact</code> || Defines the Ethernet device
|-
| <code>bootdelay</code> || The number of seconds to wait after loading before running the command stored in <code>bootcmd</code>
|-
| <code>bootargs</code> || Kernel command line passed to Linux on boot
|-
| <code>bootcmd</code> || Commands to run to boot the system. This is generally used to load and boot the OS.
|-
| <code>filesize</code> || Automatically set to the size of the last file loaded on the system
|-
| <code>fileaddr</code> || Automatically set to the logical address used for the last file loaded to the system
|-
| <code>ipaddr</code> || The static IP address to use for network communications
|-
| <code>serverip</code> || The IP address of the TFTP server on the local network to use for file transfer
|}

=== Accessing Variables ===
To access the value of a variable, use the variable name enclosed in <code>${}</code>. For example, <code>printenv ${bootcmd}</code> will print the current value of the <code>bootcmd</code> variable.

=== Setting Variables ===
The <code>setenv</code> command is used to set the value of a new or existing variable. For example, the following command will set the <code>ipaddr</code> variable to a value of 192.168.2.1:
 U-Boot> setenv ipaddr 192.168.2.1

When U-Boot loads, it loads the current environment from flash into RAM. Using <code>setenv</code> only changes the volatile copy of the environment but does not commit the change to flash. If a change needs to be committed to non-volatile memory, the <code>saveenv</code> command must be used to save the current environment. This will allow changes to be preserved for the next time that U-Boot is loaded. 
{{mbox | type = notice | text = Note that <code>saveenv</code> commits the entire environment to flash in its current state, not only the most recent change.}}

=== Important Variables ===
Some of the U-Boot variables need special attention as they effect the Linux kernel boot process.
==== bootargs ====
The <code>bootargs</code> variable contains parameters used by the Linux kernel during boot. It specifies the boot partition, serial console for the boot messages, and other possible boot parameters. 

For example, here is the bootargs string on the SoM-9G45:
 bootargs=console=ttyS0,115200 mtdparts=atmel_nand:128M(root),-(aux) root=/dev/mtdblock0 rootfstype=jffs2 ro video=LG

Everything after the first equals sign is contained within the <code>bootargs</code> variable. The following explains each of the variables in the bootargs:
{| class="wikitable"
! colspan="2"|Table 1: bootargs parameters
|-
! Parameter !! Description
|-
| console || The UART device node and baud rate for the boot messages.
|-
| mtdparts || The size of the NAND flash partitions.  '''NOTE: This could use more information'''
|-
| root || Sets which MTD partition to mount as the root file system.
|-
| rootfstype || The file system formatting used on the root partition. 
|-
| ro || Mounts the root partition read-only.
|-
| video || Sets the video mode for the display.
|}

{| class="wikitable"
! colspan="2"|Table 2: video parameter values
|-
! Value !! Description
|-
| LG || 4.3" LCD distributed with the SoM-200, SoM-210, and SoM-212 carriers.
|-
| PRIMEVIEW || 7" LCD distributed with the SoM-250ES (PPC-E7+)
|-
| AMPIRE || 10" LCD distributed with the SoM-250ES (PPC-E10)
|}
==== bootcmd ====
The <code>bootcmd</code> variable is a set of instructions used to relocate and boot the Linux kernel. This command will vary from machine to machine based on Flash and RAM types.
[[Category:Bootloaders]]