Serial download: s-record, binary (via Kermit)
Network download: tftp, bootp, dhcp, nfs
Flash management: copy, erase, protect, cramfs, jffs2
Memory utilities: copy, dump. crc, check
Boot from disk: raw block, ext2, fat, reiserfs
Interactive shell: choice of simple or "busybox" shell with many scripting features.

This file is a quick guide to getting started. For full details of u-boot features please refer to the README file and visit the website:

http://www.denx.de/wiki/view/DULG/UBoot

This release supports the following platforms:

Main CPU CORE	Device	Board name
ST40	STi5528	espresso
	STi5528	sti5528eval
	STm8000	st220eval
	STx7100	stb7100mboard
		stb7100ref_27 (27MHz SYSACLKIN)
		stb7100ref_30 (30MHz SYSACLKIN)
	STx7109	stb7100mboard
		stb7100ref_27 (27MHz SYSACLKIN)
		stb7100ref_30 (30MHz SYSACLKIN)
		stb7109eref
ST231	STi5301	sti5301mb390*
	STi5301	sti5301mb424
	STm8010	stm8010mboard
	STm8010	traviata

*Ethernet not supported in this release

ST40 memory system

When using u-boot on the ST40 it helps to have a basic understanding of the ST40 memory system. The ST40 supports 32 bits of address but uses the top 3 bits (bits 31-29) to partition memory into a number of regions with different properties:

Address	Name	Cacheable	Translatable	Usermode access
0x0000 0000	P0	yes	yes	yes
0x8000 0000	P1	yes	no	no
0xA000 0000	P2	no	no	no
0xC000 0000	P3	yes	yes	no
0xE000 0000	P4	no	no	store queue only

Note that memory regions P0 - P3 map to the same physical address. For example 0x84000000 and 0xA4000000 refer to the same physical address - using the 1st address the data can be cached but using the second address it cannot be cached. Within u-boot memory regions which need to be accessed un-cached (Peripherals and FLASH) will be accessed using P2 addresses and memory which can be cached (SDRAM) will be accessed using P1 addresses.

By default u-boot runs with memory translation disabled, instruction and data caches enabled but with the data cache in write-through mode (all writes are written to memory).

Using u-boot

U-boot provides a powerful command line interface which is accessed through a terminal emulator connected to the target boards serial port. For example type "help" at the command prompt will print a list of available commands:

STB7100-MBOARD> help
?       - alias for 'help'
askenv - get environment variables from stdin
autoscr - run script from memory
base    - print or set address offset
bdinfo - print Board Info structure
boot    - boot default, i.e., run 'bootcmd'
bootd   - boot default, i.e., run 'bootcmd'
bootm   - boot application image from memory
bootp   - boot image via network using BootP/TFTP protocol
cmp     - memory compare
coninfo - print console devices and information
cp      - memory copy
crc32   - checksum calculation
dhcp    - invoke DHCP client to obtain IP/boot params
diskboot- boot from IDE device
echo    - echo args to console
erase   - erase FLASH memory
exit    - exit script
ext2load- load binary file from a Ext2 filesystem
ext2ls- list files in a directory (default /)
flinfo - print FLASH memory information
fsinfo - print information about filesystems
fsload - load binary file from a filesystem image
go      - start application at address 'addr'
help    - print online help
ide     - IDE sub-system
iminfo - print header information for application image
imls    - list all images found in flash
itest   - return true/false on integer compare
loadb   - load binary file over serial line (Kermit mode)
loads   - load S-Record file over serial line
loop    - infinite loop on address range
ls      - list files in a directory (default /)
md      - memory display
mm      - memory modify (auto-incrementing)
mtest   - simple RAM test
mw      - memory write (fill)
nfs     - boot image via network using NFS protocol
nm      - memory modify (constant address)
ping    - send ICMP ECHO_REQUEST to network host
printenv- print environment variables
protect - enable or disable FLASH write protection
rarpboot- boot image via network using RARP/TFTP protocol
reset   - Perform RESET of the CPU
run     - run commands in an environment variable
saveenv - save environment variables to persistent storage
setenv - set environment variables
sleep   - delay execution for some time
test    - minimal test like /bin/sh
tftpboot- boot image via network using TFTP protocol
version - print monitor version
STB7100-MBOARD>

For help on an individual command type "help <command>". For example:

STB7100-MBOARD> help setenv
setenv name value ...
- set environment variable 'name' to 'value ...'
setenv name
- delete environment variable 'name'

Note you only need to provide enough of a commands name to distinguish it from all other commands. For example you can type "save" instead of "saveenv"

Command Line Editing

Simple command line editing and history is also provided:

Key	Function
^A	move to start of line
^E	move to end of line
^B or Left Arrow	move character left
^F or Right Arrow	move character right
^P or Up Arrow	previous command history
^N or Down Arrow	next command history
^K	erase to end of line
^U	erase line
^W	erase previous word
^Y	yank last erase
^C	break

U-boot Environment

U-Boot provides user configuration using Environment Variables which can be saved to Flash memory.

Environment Variables are set using "setenv", printed using "printenv", and saved to Flash using "saveenv". The value of environment variables can be used in commands (or scripts) by prefixing their name by a "$". To stop the evaluation of variables either proceed the "$"with "\" or quote the string with 's. Here are some examples of using environment variables:

STB7100-MBOARD> setenv targetname ben
STB7100-MBOARD> print targetname
targetname=ben
STB7100-MBOARD> echo $targetname
ben
STB7100-MBOARD> echo ${targetname}
ben
STB7100-MBOARD> echo \$targetname
$targetname
STB7100-MBOARD> echo '$targetname'
$targetname

Using "setenv" without a value can be used to delete a variable from the environment. As long as you don't save the environment you are working with an in-memory copy. If there is no valid environment In the Flash a default environment is provided.

Command Scripts

Command scripts can also be saved in environment variables and executed using the "run" command. The syntax for the scripts is similar to the "sh" shell. Commands return 0 if they ran successfully and 1 if they failed. The result of executing a command can be tested with condition commands:

if <list>; then <command list>; [ elif <list>; then <list>; ] ... [ else <list>; ] fi
while <list> ; do <list> ; done
until <list> ; do <list> ; done
for <name> in <word list> ; do <list> ; done

The following is an example script that boots a default kernel if the standard kernel is not available in flash - note the script is quoted with 's to defer the expansion of the environment variables until the script is executed:

STB7100-MBOARD> set doboot 'if iminfo ${vm_base}; then bootm ${vm_base}; else bootm ${vm_default_base}; fi'
STB7100-MBOARD> run doboot

## Checking Image at a0040000 ...
   Image Name:   Linux-2.6.11_31
   Image Type:   SuperH Linux Kernel Image (gzip compressed)
   Data Size:    1519264 Bytes = 1.4 MB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
## Booting image at a0040000 ...
   Image Name:   Linux-2.6.11_31
   Image Type:   SuperH Linux Kernel Image (gzip compressed)
   Data Size:    1519264 Bytes = 1.4 MB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
   Uncompressing Kernel Image ... OK

Note: commands need to to be typed on a single line. In some of the examples long commands will wrap over on to the following line - these must be entered on a single line

There are two commands provided for comparing values "test" and "itest".

To test the values of environment variables use "test". The syntax is the same as the shell command:

      ! EXPRESSION
             EXPRESSION is false
      EXPRESSION1 -a EXPRESSION2
             both EXPRESSION1 and EXPRESSION2 are true
      EXPRESSION1 -o EXPRESSION2
             either EXPRESSION1 or EXPRESSION2 is true
     -n STRING
             the length of STRING is nonzero
      -z STRING
             the length of STRING is zero
      STRING1 = STRING2
             the strings are equal
      STRING1 != STRING2
             the strings are not equal
      INTEGER1 -eq INTEGER2
             INTEGER1 is equal to INTEGER2
      INTEGER1 -ge INTEGER2
             INTEGER1 is greater than or equal to INTEGER2
      INTEGER1 -gt INTEGER2
             INTEGER1 is greater than INTEGER2
      INTEGER1 -le INTEGER2
             INTEGER1 is less than or equal to INTEGER2
      INTEGER1 -lt INTEGER2
             INTEGER1 is less than INTEGER2
      INTEGER1 -ne INTEGER2
             INTEGER1 is not equal to INTEGER2

The command "itest" allows values in memory to be tested. The syntax for "itest" is:

itest[.b,.w,.l,.s] [*]value1 <op> [*]value2

Where the the suffix means:

.b   byte
.w short
.l   long   (default)
.s string

value1 and value2 can be a constant or and address if preceded by a *
<op> can be one of:

       -lt      <       Less than
       -gt      >       Greater than
       -eq     ==       Equal
       -ne     !=    <> not equal
       -ge     >=       Greater Equal
       -le     <=       Less equal

Installing u-boot on the Host

There are a number of rpms for u-boot, the source rpm:

stlinux20-host-u-boot-1.1.2_st2.0-n*.noarch.rpm

* n is the release number for the rpm file (higher is newer).

a set of binary rpms - one for each board:

stlinux20-host-u-boot-sh4_espresso-2.0-n^*.noarch.rpm
stlinux20-host-u-boot-sh4_st220eval-2.0-n.noarch.rpm
stlinux20-host-u-boot-sh4_stb7100mboard-2.0-n.noarch.rpm
stlinux20-host-u-boot-sh4_stb7100ref_27-2.0-n.noarch.rpm
stlinux20-host-u-boot-sh4_stb7100ref_30-2.0-n.noarch.rpm
stlinux20-host-u-boot-sh4_sti5528eval-2.0-n.noarch.rpm
stlinux20-host-u-boot-st231_sti5301mb390-2.0-n.noarch.rpm
stlinux20-host-u-boot-st231_sti5301mb424-2.0-n.noarch.rpm
stlinux20-host-u-boot-st231_stm8010mboard-2.0-n.noarch.rpm
stlinux20-host-u-boot-st231_traviata-2.0-n.noarch.rpm

* n is the release number for the rpm file (higher is newer).

and a host tools rpm:

stlinux20-host-u-boot-tools-1.1.2_st2.0-n.i386.rpm

After installing the rpms the u-boot source tree can be found in:

/opt/STM/STLinux-2.0/devkit/u-boot/u-boot-1.1.2_st2.0

A set of pre-compiled u-boot files - one for each target can be found in the following directories:

/opt/STM/STLinux-2.0/devkit/u-boot/espresso-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/st220eval-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/stb7100ref_27-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/stb7100ref_30-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/sti5301mb424-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/sti5528eval-1.1.2_st2.0-n
/opt/STM/STLinux-2.0/devkit/u-boot/traviata-1.1.2_st2.0-n

and the host tool for creating u-boot images :

/opt/STM/STLinux-2.0/host/bin/mkimage

Each of the pre-build binary directories contains the following files:

LICENSE        - GPL License
README.ST    - Help file
kscript        - example Kermit scripts
localenv       - example u-boot env file
setupenv       - example u-boot env file
setupenv.ub    - " " " converted to u-boot image file
u-boot - compiled u-boot elf binary
u-boot.bin - compiled u-boot binary image
u-boot.map    - compiled u-boot map file
u-boot.srec - compiled u-boot srec image

After installing u-boot add the directory:

/opt/STM/STLinux-2.0/host/bin

to your "PATH" shell variable.

Installing u-boot & Linux Kernel on the target

There are a number of ways of setting up a target board. The simplest method uses the example Kermit scripts to automate the process of putting u-boot and the Linux kernel onto the target board. This is explained in the following section. (For details of how to set up a board manually see the section Manual install of u-boot and Linux kernel.)

Download using Kermit script

You need to connect to the serial port of the target board with the following parameters:

baud=115200, data=8, parity=n, Flow Control=none

First copy the file "localenv" from the pre-built binary directory for your board to a local directory and modify it with details of the target board. The unmodified file contains the following:

######## Modify these parameters for you environment
set ipaddr      # ipaddress of target
set targetname # network name of target
set netmask     # netmask
set gatewayip   # gateway ip address
set serverip    # ip address of nfs server for kernel & u-boot
### Add these if your board needs an Ethernet address
#set ethaddr
#set ethinit nwhwconf=device:eth0,hwaddr:${ethaddr}
####################################################

Next connect to you serial port with Kermit using the example initialisation script "kscript" found in the directory containing the pre-built u-boot binary (this adds some commands that will be used to download u-boot and the kernel). For example:

Kermit -y /opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-n/kscript

At the Kermit prompt connect to serial port of the target board - assuming the target board in connected to "/dev/ttyS0" then type "tty0" (which runs the function defined in the init script). If the target is not connected to "ttyS0" then modify kscript as appropriate.

In another window use either sh4gdb or st200gdb to load and run u-boot. e.g. for loading an stb7100mboard (mb411):

>sh4gdb
GNU gdb 5.3
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB. Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=sh-superh-elf".
(gdb) mb411bypass TARGET
The target is assumed to be little endian
The target architecture is assumed to be sh4
0xa0000000 in ?? ()
(gdb) load /opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-n/u-boot
Loading section .text, size 0x12b44 lma 0x85f00000
Loading section .rodata, size 0x444 lma 0x85f12b44
Loading section .rodata.str1.4, size 0x3a0c lma 0x85f12f88
Loading section .data, size 0xa10 lma 0x85f16994
Loading section .u_boot_cmd, size 0x420 lma 0x85f173a4
Start address 0x85f00000, load size 96196
Transfer rate: 769568 bits/sec, 19239 bytes/write.
(gdb) c
Continuing.

You should see something similar to this output on the serial port:

Board: STb7100-mboard

U-Boot 1.1.2 (May 17 2005 - 13:37:15) - st2.0-12

DRAM: 64 MB
Flash: 8 MB
*** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
Net:   Using MAC Address 00:80:E1:12:06:3E
STB7100-MBOARD>

You can now enter commands on the serial console for u-boot to execute. For a list of all the u-boot commands type:

STB7100-MBOARD>help

To initialise the board with u-boot and a pre-compiled Linux kernel simply return to the Kermit prompt (by typing "^\c") and type either:

Kermit>netsetupub

if the board is connected to Ethernet or:

Kermit>serialsetupub

To use the serial port to download u-boot and Linux kernel.

The following is example output from running "netseupub":

Kermit>netsetupub
Setting up stb7100mboard

STB7100-MBOARD> ######## Modify these parameters for you environment
STB7100-MBOARD> set ipaddr      164.129.15.90 # ipaddress of target
STB7100-MBOARD> set targetname ben # network name of target
STB7100-MBOARD> set netmask     255.255.248 # netmask
STB7100-MBOARD> set gatewayip   164.129.8.253 # gateway ip address
STB7100-MBOARD> set serverip    164.129.14.91 # ip address of nfs server for kenel & u-boot
STB7100-MBOARD> ### Add these if your board needs an ethernet address
STB7100-MBOARD> #set ethaddr
STB7100-MBOARD> #set ethinit nwhwconf=device:eth0,hwaddr:${ethaddr}
STB7100-MBOARD>
STB7100-MBOARD> loadb $loadaddr
## Total Size      = 0x00000eb3 = 3763 Bytes
## Start Addr      = 0x84000000
STB7100-MBOARD> autoscr $loadaddr
## Executing script at 84000000
Setting up uboot env
STB7100-MBOARD> save
Saving Environment to Flash...
.
Un-Protected 1 sectors
Erasing Flash...
. done
Erased 1 sectors
Writing to Flash... .done
.
Protected 1 sectors
STB7100-MBOARD> #
STB7100-MBOARD> run setup-nfs
Installing u-boot
Using MAC Address 00:80:E1:12:06:D1
File transfer via NFS from server 164.129.14.91; our IP address is 164.129.15.90Filename '/opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-13/u-boot.bin'.
Load address: 0x85000000
Loading: #########################
done
Bytes transferred = 125404 (1e9dc hex)
Using MAC Address 00:80:E1:12:06:D1
File transfer via NFS from server 164. 129.14.91; our IP address is 164.129.15.90Filename '/opt/STM/STLinux-2.0/devkit/kernel/kernel-sh4-stb7100mboard-2.6.11_stm20-31/vmlinux.ub'.
Load address: 0x84800000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #####################################
done
Bytes transferred = 1519328 (172ee0 hex)
Un-Protect Flash Sectors 0-0 in Bank # 1
. done
Copying uboot to flash
Erase Flash Sectors 0-0 in Bank # 1
. done
Copy to Flash... .done
Total of 125404 bytes were the same
done
Copying vmlinx to flash
Erase Flash Sectors 2-31 in Bank # 1
.............................. done
Copy to Flash... ............done
Total of 1519328 bytes were the same
done
STB7100-MBOARD> echo Done
Done
STB7100-MBOARD> #
Kermit>-MBOARD>

The target board should now have u-boot and a Linux kernel in flash. The environment variables and scripts from the "setupenv" file will saved in the flash u-boot environment. See Example u-boot Environment for details.

Manual install of u-boot and Linux kernel

The following sections show how to download u-boot and the kernel onto the target board without using the supplied Kermit script and u-boot scripts. This section will help to understand the various u-boot commands used by the example scripts.

Download u-boot using serial port

Assuming you used Kermit to connect to the serial port and type:

STB7100-MBOARD> loadb $load_addr
## Ready for binary (Kermit) download to 0xA4000000 at 115200 bps...

Note: $load_addr is an environment variable containing the download address. This depends on the start of SDRAM for the board being used, see Memory Map.

Return back to Kermit (using Ctrl-\c) and send u-boot::

C-Kermit>robust
C-Kermit>send /opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-n^*/u-boot.bin
C-Kermit>c
Connecting to /dev/ttyS0, speed 115200
Escape character: Ctrl-\ (ASCII 28, FS): enabled
Type the escape character followed by C to get back,
or followed by ? to see other options.
----------------------------------------------------
## Total Size = 0x000177c4 = Bytes
## Start Addr = 0xA4000000
STB7100-MBOARD>

* n is the release number for the u-boot binary please use the latest (highest) release version.

Downloading u-boot using nfs over the network

To use the network functions you need to set up your boards IP address etc. This is done by setting the following environment variables:

STB7100-MBOARD> set ipaddr <board-ip-addr>
STB7100-MBOARD> set netmask <your-netmask>
STB7100-MBOARD> set serverip <your-server-ip>

Where "your-server-ip" is the address of you nfs/tftp server machine. To save changes to the environment into flash type "save".

Note: The " u-boot.bin" file needs to be in a directory exported by the nfs server accessible to the target board. In the following examples we assume the directory containing the pre-built u-boot binaries are exported.

You can now use the nfs command to copy the u-boot binary into memory:

STB7100-MBOARD> nfs $load_addr $serverip:/opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-n^*/u-boot.bin
Using MAC Address 00:80:E1:12:06:3E
File transfer via NFS from server 164.129.14.91; our IP address is 164.129.15.90
Filename '/opt/STM/STLinux-2.0/devkit/u-boot/stb7100mboard-1.1.2_st2.0-11/u-boot.bin'.
Load address: 0xa4000000
Loading: ##########################
done
Bytes transferred = 96196(177c4 hex)

* n is the release number for the u-boot binary please use the latest (highest) release version.

Note: some boards do not have their MAC address programmed into eeprom. In this case you will need to supply a unique mac address (See this page ) by adding an extra parameter to CONFIG_EXTRA_ENV_SETTINGS in include/configs/<board-name>.h. For example:

#define CONFIG_EXTRA_ENV_SETTINGS \
"ethaddr=XX:XX:XX:XX:XX:XX\0" \

Copying the u-boot image to flash

To copy u-boot into flash type:

STB7100-MBOARD>prot off 1:0
Un-Protect Flash Sectors 0-0 in Bank # 1
. done
STB7100-MBOARD>run update
Erase Flash Sectors 0-0 in Bank # 1
. done
Copy to Flash... .done
Protect Flash Sectors 0-0 in Bank # 1
. done
STB7100-MBOARD>

This executes this script held in the environment variable update:

erase 1:0;cp.b 0xa4000000 0xa0000000 20000;protect on 1:0

Note: If the stb7100mboard fails to boot from flash you must heck that SWITCH8 jumper 2 is set to Off on your board as this enables
the ST40 to boot from flash

Downloading the kernel image file

This image file can then be downloaded into memory using either serial or Ethernet. In this example we use the nfs command to download the image as this is very fast:

STB7100-MBOARD> nfs a4000000 $serverip:/export/u-boot/stb7100/vmlinux.ub
Using MAC Address 00:80:E1:12:06:3E
File transfer via NFS from server 164.129.14.91; our IP address is 164.129.15.90
Filename '/export/u-boot/stb7100/vmlinux.ub'.
Load address: 0xa4000000
Loading: #################################################################
#################################################################
#####################################
done
Bytes transferred = 850783 (cfb5f hex)
STB7100-MBOARD>

Copying the kernel image to flash

Next we can copy the Linux image to flash and check it is valid. In this example we are copying the Linux image into flash sectors 2-9 as the first two sectors are used by u-boot - the first contains the u-boot image and the second the u-boot environment.

STB7100-MBOARD> era 1:2-9
Erase Flash Sectors 2-9 in Bank # 1
........ done
STB7100-MBOARD> cp.b a4000000 a0040000 $filesize
Copy to Flash... done
STB7100-MBOARD> iminfo a0040000

## Checking Image at a0040000 ...
   Image Name:   Linux 2.6
   Image Type:   ST40 Linux Kernel Image (gzip compressed)
   Data Size:    850719 Bytes = 830.8 kB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
STB7100-MBOARD>

Booting the Linux Kernel

The environment variable "bootargs" is used to hold the parameter options passed to the Linux kernel (see "Documentation/kernel-parameters.txt" in the Linux source directory for details).

Typically the required set of kernel parameters are:

Console settings
Memory organisation
Location of root file system

Optionally the parameters also set:

Ethernet configuration
Flash mtd partition configuration
co-processor memory allocation

The example environment "setupenv" defines a number of scripts to set the "bootargs" depending on the location of the root partition:

##### Set default kernel parameters
# Console settings
set tty     console=ttyAS0,115200
# Memory and coprocessor allocation
set mem    'mem=64M coprocessor_mem=32m:16m,16m'
# Define mtd flash partitions
set set_mtd 'set mtd mtdparts=Onboard_Flash:${monitor_len}(uboot),${env_len}(params),${vm_len}(kernel),-(fs)'
set nfsroot '${stlinux}/${arch}/target'

##### Boot with ramdisk root filesystem
set bootargs_ram 'run set_mtd; set bootargs ${tty} ${mem} ${mtd} ramdisk_size=16384 root=/dev/ram0 ${extra}'

##### Boot with an nfs mounted root filesystem
# set Location of linux kernel
set stlinux     /opt/STM/STLinux-2.0/devkit
set arch    sh4
set nfsroot     ${stlinux}/${arch}/target
# script to set bootargs
set bootargs_nfs 'run set_mtd;set bootargs ${tty} ${mem} ${mtd} root=/dev/nfs nfsroot=${nfsroot} ${ethinit} rw ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${targetname}:eth0:off ${extra}'

##### Boot with a disk root filesystem
# set location of root partition
set rootpart   hda1
# script to set bootargs
set bootargs_hda 'run set_mtd;set bootargs ${tty} ${mem} ${mtd} root=/dev/${rootpart} ro ${extra}

##### Boot with a flash filesystem
set bootargs_jffs2 'run set_mtd;set bootargs ${tty} ${mem} ${mtd} root=/dev/mtdblock3 rootfstype=jffs2'

Note the script "set_mtd" is used to set the value of the environment "mtd" before "bootargs" is set. This is done to allow the environment variables refered to in the "set_mtd" script to be expanded at the point of running the boot script.

You can then "run" one of the scripts to set bootargs suitable for your system i.e.

run bootargs_ram for a ram disk based filesystem
run bootargs_nfs for an nfs mounted filesystem
run bootargs_hda for a hard disk based filesystem
run bootargs_jffs2 for a flash based filesystem

In this example we boot a kernel in flash with a nfs mounted filesystem:

STB7100-MBOARD> run bootargs_nfs
STB7100-MBOARD> bootm a0040000

## Booting image at a0040000 ...
   Image Name:   Linux-2.6.11_31
   Image Type:   SuperH Linux Kernel Image (gzip compressed)
   Data Size:    1519264 Bytes = 1.4 MB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
   Uncompressing Kernel Image ... OK

Starting kernel console=ttyAS0,115200 mem=64M coprocessor_mem=32m:16m,16m mtdparts=Onboard_Flash:0x00020000(uboot),0x00020000(params),0x003C0000(kernel),-(fs) root=/dev/nfs nfsroot=/opt/STM/STLinux-2.0/devkit/sh4/target rw ip=164.129.15.90:164.129.14.91:164.129.8.253:255.255.248:ben:eth0:off - 0x00000000 - 0 ...

....

Note: For ST40 targets you can speed up the boot from flash by providing a P1 (cacheable) address for the location of the kernel in Flash. i.e. for the example given above using "bootm 80040000".

Booting the kernel image on reset

On reset U-Boot runs the script held in the environment variable "bootcmd". This allows for any number of actions to be performed before finally booting the kernel. To simply boot the kernel image we have saved to flash set bootcmd as follows:

STB7100-MBOARD> set bootcmd 'bootm a0040000'
STB7100-MBOARD> save
Saving Environment to Flash...
.
Un-Protected 1 sectors
Erasing Flash...
. done
Erased 1 sectors
Writing to Flash... .done
.
Protected 1 sectors

To enable a delay before executing the boot command, to give the user a chance to halt the boot for example, set the "bootdelay" environment variable to the number of seconds of delay. See "doc/README.autoboot" for more details on the "autoboot" options.

Using mkimage

u-boot supports a number of different image formats that can be downloaded saved to flash and executed. The types of images include Linux kernels, script files, standalone binaries and ramdisk images. This section shows you how to create, download and save a Linux kernel image to flash.

First you need to make a u-boot image file containing the binary vmlinux kernel using "objcopy" followed by the "mkimage" tool. In this example we also compress the kernel as well:

>sh4linux-objcopy -O binary vmlinux vmlinux.bin
>gzip vmlinux.bin
>./tools/mkimage -A sh4 -O linux -T kernel -C gzip -a 0x84001000 -e 0x84002000 -n "Linux 2.6" -d vmlinux.gz vmlinux.ub
Image Name:   Linux 2.6
Created:      Fri May 20 10:29:23 2005
Image Type:   ST40 Linux Kernel Image (gzip compressed)
Data Size:    850719 Bytes = 830.78 kB = 0.81 MB
Load Address: 0x84001000
Entry Point: 0x84002000

The two arguments "-a" and "-e" depend of the target board:

espresso,stb7100mboard,stb7100ref,stb7100eref	-a 0x84001000 -e 0x84002000
st220eval	-a 0x88001000 -e 0x88002000
sti5301mb390, sti5301mb424	-a 0xc0000000 -e 0xc0002000

Alternatively you can create the u-boot kernel image directly when doing a kernel build by adding "uImage" as the target of a kernel build. e.g.

make ARCH=sh CROSS_COMPILE=sh4-linux- uImage

This will create a u-boot Linux kernel image: "arch/sh/boot/uImage"

Creating a ramdisk root filesystem

With u-boot you can store a ramdisk image in flash and use this as the root file system for the Linux kernel. The following example shows how to download a ramdisk image to flash an boot the kernel we previously saved in flash using this ramdisk image.

Creating the ramdisk image

Instructions for creating the ramdisk image see Booting with a ramdisk root file system in the user guide. Once this image file has been creating it needs to be converted into a u-boot image file:

mkimage -C none -A sh4 -O linux -T ramdisk -a 0x84800000^* -n "ST40 Linux ramdisk" -d initrd.img.AS0 /export/u-boot/stb7100/ramdisk.ub

^* Note: the address given for the "-a" argument must be above where the Linux kernel resides in SDRAM.

Downloading the ramdisk image

This u-boot image can then be downloaded to the target either using serial of nfs download. This example downloads the image using nfs:

STB7100-MBOARD> nfs $loadaddr ${serverip}:${rootpath}/ramdisk.ub
Using MAC Address 00:80:E1:12:06:3E
File transfer via NFS from server 164.129.14.91; our IP address is 164.129.15.90
Filename '/export/u-boot/stb7100/ramdisk.ub'.
Load address: 0xa4000000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         ########
done
Bytes transferred = 2368130 (242282 hex)

Copying the ramdisk image to Flash

The image can then by copied to flash:

STB7100-MBOARD> era 1:45-63
Erase Flash Sectors 45-63 in Bank # 1
................... done
STB7100-MBOARD> cp.b $fileaddr A05A0000 $filesize
Copy to Flash... ..................done

There should now be a Linux kernel and ramdisk image in Flash:

STB7100-MBOARD> imls
Image at A0040000:
   Image Name:   Linux 2.6
   Image Type:   ST40 Linux Kernel Image (gzip compressed)
   Data Size:    850719 Bytes = 830.8 kB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
Image at A05A0000:
   Image Name:   ST40 Linux ramdisk
   Image Type:   ST40 Linux RAMDisk Image (uncompressed)
   Data Size:    2368066 Bytes = 2.3 MB
   Load Address: 84800000
   Entry Point: 84800000
   Verifying Checksum ... OK

Booting the Linux kernel with a ramdisk root filesystem

To use a ramdisk image when booting a kernel set the appropriate value for "bootargs" using the "bootargs_ram" script and add the address of the ramdisk image to the "bootm" command:

STB7100-MBOARD> run bootargs_ram
STB7100-MBOARD> bootm A04C0000 A05A0000
## Booting image at a04c0000 ...
   Image Name:   Linux 2.6
   Image Type:   ST40 Linux Kernel Image (gzip compressed)
   Data Size:    850719 Bytes = 830.8 kB
   Load Address: 84001000
   Entry Point: 84002000
   Verifying Checksum ... OK
   Uncompressing Kernel Image ... OK
   Image Name:   ST40 Linux ramdisk
   Image Type:   ST40 Linux RAMDisk Image (uncompressed)
   Data Size:    2368066 Bytes = 2.3 MB
   Load Address: 84800000
   Entry Point: 84800000
   Verifying Checksum ... OK
   Loading Ramdisk to 84dbd000, length 00242242 ... OK

Starting kernel console=ttyAS0,115200 mem=64M ramdisk_size=16384 root=/dev/ram0 - 0x00dbd000 - 2368066 ...

Booting the kernel from disk

Where supported U-Boot can load a kernel and initial ram disk from an IDE or SATA disk drive.

There are 2 options for booting from disk:

Booting from a dedicated boot partition.
Booting from an ext2 file system.

Booting from a dedicated partition

This assumes the disk has a dedicated partition big enough to hold the kernel and any initial ram disk - 32M should be plenty. The following example assumes the 1st partition on the 1st device (/dev/hda1 for IDE or /dev/sda1 for SATA) is available for U-Boot.

Copy the U-Boot kernel image (see Using mkimage) onto the disk either from the target Linux system using "dd", e.g. to copy the image onto partition hda1:

dd if=vmlinux.ub of=/dev/hda1

Or directly from U-Boot e.g. assuming "vmlinux.ub" image has been downloaded into memory at the U-Boot prompt type these commands to reset the ide device and find the starting sector for the partition:

STB7100-MBOARD> ide res

Reset IDE: Bus 0: OK
Device 0: Model: IBM-DTCA-24090 Firm: TC6OAB4A Ser#
            Type: Hard Disk
            Capacity: 3909.9 MB = 3.8 GB (8007552 x 512)
STB7100-MBOARD> ide part

Partition Map for IDE device 0 --   Partition Type: DOS

Partition     Start Sector     Num Sectors     Type
    1                   63          125937      83
    2               126000         7881552      83

Then write the U-Boot kernel image to the disk. Note that the start block (sector) number needs to be converted to hexadecimal and the length needs to be given in blocks also converted to hex. U-Boot does not check where you are writing to the disk so this must be done with care as it is very easy to write over the contents of the disk!

STB7100-MBOARD> ide write $loadaddr 3F B73

IDE write: device 0 block # 63, count 2931 ... 2931 blocks written: OK

Finally set the bootcmd to load the kernel image from the partition and boot the image:

STB7100-MBOARD> set bootcmd diskboot a4800000 0:1\; bootm a4800000
STB7100-MBOARD> save

Note the address used for the diskboot command is above where the kernel will reside once extracted by U-Boot.

Booting from an ext2 file system

This assumes this boot disk has an ext2 partition available to hold the boot image. In this example we use partition 1 (/dev/hda1).

Copy the U-Boot kernel image e.g. vmlinux.ub to a directory in an ext2 partition, e.g a small partition mounted as "/boot", using the target Linux system.

At the U-Boot prompt set up the bootcmd environment variable to load the file from the partition and boot the image:

STB7100-MBOARD> set bootcmd ext2load ide 0:1 a4800000 /vmlinux.ub\; bootm a4800000
STB7100-MBOARD> save

Using mtd flash partitions

The example u-boot environment "setupenv" adds the following to the kernel parameters

mtdparts=Onboard_Flash:${monitor_len}(uboot),${env_len}(params),${vm_len}(kernel),-(fs)

The syntax for the parameter is

mtdparts=<mtddef>[;<mtddef]
<mtddef> := <mtd-id>:<partdef>[,<partdef>]
<partdef> := <size>[@offset][<name>][ro]
<mtd-id> := unique name used in mapping driver/device (mtd->name)
<size> := standard linux memsize OR "-" to denote all remaining space
<name> := '(' NAME ')'

This defines the Flash organisation for the Linux kernel and allows access to the flash from user applications. To check the mtd partitions are set up correctly at the Linux prompt type :

root@: cat /proc/mtd
dev: size erasesize name
mtd0: 00020000 00020000 "uboot"
mtd1: 00020000 00020000 "params"
mtd2: 003c0000 00020000 "kernel"
mtd3: 00400000 00020000 "fs"

This shows the organisation of flash as seen by the Linux kernel. You can then modify partitions directly using the mtd-tools:

flash_erase MTD_DEVICE [start] [count] [unlock]
flash_eraseall MTD_DEVICE
flash_unlock MTD_DEVICE
flash_lock <mtd device> <ofs in hex> <num of sectors in decimal or -1 for all sectors>

For example to update the kernel image held in flash:

flash_eraseall /dev/mtd2
dd if=vmlinux.ub of=/dev/mtd2

Another example is provided in the script "STM/examples/update-uboot.sh" for updating u-boot from a running kernel.

Accessing the u-boot environment from Linux

Two programs are provided which allow access to the u-boot environment from Linux:

fw_setenv name [value]
fw_printenv [name]

To use these programs a configuration file "/etc/fw_env.config" must be set up. For example the configuration file for the stb7100mboard looks like this:

# MTD device name Device offset Env. size Flash sector size
/dev/mtd1 0x00000000 0x00010000 0x20000

The device offset is always 0, the size of the environment for the target board is given in section Memory Map and the sector size is the same as the "erasesize" shown in "/proc/mtd".

Compiling u-boot

To configure and build u-boot for a board "cd" to or copy the source tree to somewhere local and type:

make distclean
make <board>_config
make

Where <board> is one of the board names given above. This will create

u-boot         - elf file
u-boot.bin    - binary file
u-boot.map    - map file
u-boot.srec    - srec

Modifying u-boot

This section gives a quick overview of the structure of the u-boot code.

Configuration files

The important configuration info is defined in:

include/configs/<target-board-config>.h

For example espresso board default configuration file is:

include/configs/espresso.h

This defines such things as the memory layout, default baudrate, what u-boot features will be included in the build etc. Please refer to the README file for a description of the options defined in the configuration file.

Memory Map

This table show the default locations in FLASH and RAM used by u-boot:

Board	FLASH¹		RAM²
	u-boot code	u-boot env	memory start	u-boot base
espresso	0xA0000000-0xA003FFFF	0xA0040000-0xA003FFFF	0x84000000	0x85F00000
sti5528eval	0xA0000000-0xA003FFFF	0xA0040000-0xA003FFFF	0x84000000	0x85F00000
stb7100mboard	0xA0000000-0xA001FFFF	0xA0020000-0xA002FFFF	0x84000000	0x85F00000
stb7100ref_*	0xA0000000-0xA001FFFF	0xA0020000-0xA002FFFF	0x84000000	0x85F00000
stb7109eref	0xA0000000-0xA001FFFF	0xA0020000-0xA002FFFF	0x84000000	0x85F00000
sti5301mb390	0x7FFE0000-0x7FFFFFFF	0x7F800000-0x7F80FFFF	0xC0000000	0xC1F00000
sti5301mb424	0x7FFC0000-0x7FFFFFFF	0x7F800000-0x7F80FFFF	0xC0000000	0xC1F00000
traviata	0x00000000-0x0002FFFF	0x007F0000-0x007F7FFF	0x80000000	0x81F00000

¹ Flash addresses are given as P2 (unchached) addresses for ST40
²Ram addresses are given as P1 (cached) addresses for ST40

Code organisation

The target specific code in held in the following directories:

include/configs/<board-config>.h -- board config header file
board/<board>                     -- board files
cpu/<cpu>                         -- cpu files
cpu/<cpu>/<soc>                   -- soc files
lib_<arch>                        -- arch support files
include/asm-<arch>                -- arch headers

e.g. for the espresso board:

include/configs/espresso.h -- board config header file
board/espresso/ -- board files

config.mk         -- defines base address for u-boot in mem
espresso.c        -- board specific initialisation
Makefile
sconsole.c        -- used if no physical serial port
sconsole.h
u-boot.lds        -- linker script
init-espresso.S -- memory/soc configuration table

cpu/sh4_1xx -- cpu files

config.mk         -- cpu make flags
cpu.c             -- cpu functions
interrupts.c     -- interrupt routines (not needed for sh4)
Makefile
start.S           -- main cpu entry point
init-st40common.S -- common configuration code

cpu/sh4_1xx/sti5528 -- soc files

Makefile
sti5528.c -- soc specific functions e.g. reset

lib_sh4 -- arch support files

board.c           -- generic board initialisation code
cacheops.S
io.c
io_generic.c
linkage.h
memchr.S
memcpy.S
memmove.S
memset.S
sh4_linux.c    -- code for booting sh4 linux kernel
strlen.S
time.c           -- generic code for reading TMU

include/asm-sh4 -- arch headers

Porting U-boot to a new board

The process of porting u-boot to a new board is as follows:

Choose an existing board which is most similar to the new board
Copy the following files and directories using the name of the new board:
board/<existing-board> -> board/<new-board>
include/configs/<exiting-board>.h -> include/configs/<new-boad>.h
Rename the files in "board/<newboard>" to match the name of the new board
Modify "board/Makefile" to match the name of the new board
Modify the memory initialisation file: "board/init-<new-board>.S"
Modify the board initialisation file: "board/<new-board>.c"
Modify the config file "include/configs/<new-board>.h" to match the memory organisation and peripherals of the new board.
Modify the value of TEXT_BASE in "board/stb7100mboard/config.mk" which defines the SDRAM load address.

Modifying the memory initialisation file

Very early in the boot sequence the function "init_ram" is called which configure all the critical SOC and board devices to allow u-boot to be copied from Flash to SDRAM and start executing. This function is normally defined in the file: "board/init-<boardname>.S".

For ST40 targets the structure of this file is typically:

#define _SH4REG_ASM_

/* Include some register definitions for this device */
#include "asm/stb7100reg.h"

/*
Include the common memory initialisation code for this SOC.
This file contains the "init_ram" function which will use the
__memory_setup_tabe defined bellow do the appropriate memory setups.
*/

#include "../../cpu/sh4_2xx/stb7100/init-stb7100common.S"

.balign 32

__memory_setup_table:

/* Define memory config table

  POKE_LONG(STB7100_CLOCKGENA_LOCK, 0xc0de)
  OR_LONG(STB7100_CLOCKGENA_PLL0_CFG, 0x00100000)
  UPDATE_LONG(STB7100_CLOCKGENA_PLL0_CFG, 0xfff7ffff, 0)
  UPDATE_LONG(STB7100_CLOCKGENA_PLL0_CFG, 0xfff80000, 0x06 | (0x3b << 8) | (0x0 << 16))
  OR_LONG(STB7100_CLOCKGENA_PLL0_CFG, 0x00080000)
  WHILE_NE(STB7100_CLOCKGENA_PLL0_STATUS, 0x00000001, 0x00000001)
  UPDATE_LONG(STB7100_CLOCKGENA_PLL0_CFG, 0xffefffff, 0)
  POKE_LONG(STB7100_CLOCKGENA_LOCK, 0x0)

...

END_MARKER

The initialisation of the configuation registers is done using the "__memory_setup_table" this defines a sequence of memory operations which will be executed in order with a suitable time delay between each operation. The memory operation currently supported are:

Operation	Function
POKE_LONG(A, V)	(long)(A) = V;
POKE_SHORT(A, V)	(short)(A) = V;
POKE_CHAR(A, V)	(char)(A) = V;
OR_LONG(A, V)	(long)(A) \|= V;
UPDATE_LONG(A, MASK, V)	(long)(A) = ((long)(A) & MASK) \| V;
POKE_UPDATE_LONG(A1, A2, MASK, SHIFT, V)	(long)(A1) = (((long)(A2) & MASK) << SHIFT) \| V;
WHILE_NE(A, MASK, V)	while ( ((long)(A1) & MASK) != V) {;}
IF_DEVID(V)	If the device id config register matches V then do the following memory operations until the next ELSE or ENDIF otherwise execute the operations between the next ELSE and ENDIF Currently supported for 710X targets only
IF_NOT_DEVID(V)	If the device id config register does NOT match V then do the following memory operations until the next ELSE or ENDIF otherwise execute the operations between the next ELSE and ENDIF Currently supported for 710X targets only
ELSE
ENDIF
END_MARKER	marks end of table

It should be a matter or modifying this table to match the target SOC target board combination.

The ST200 memory setup is very similar to the ST40 expect it has an extra table "_xpu_mmu_setup_table" which sets up the MMU which may also require changing.

Modifying the board initialisation file

After u-boot has been relocated to SDRAM the initial bootstrap code will set up a stack and call the C function "start_<cpu>boot " (see lib_<cpu>/board.c). This function then calls a number of initialisation functions including the function "board_init" defined in the file "board/<boardname>/<boardname>.c".

This file contains a number of functions which must be modified to match the target board. Typically these functions set up PIO pins for serial ports, do any EPLD programming, reset devices and provide functions for enabling/disabling writes to flash.

Example scripts and u-boot Environment

A number of scripts and an example u-boot environment is also provided either in the STM directory in the u-boot source tree or in the prebuilt u-boot binary directory.

Build Scripts

STM/builduboot <arch>
Builds all the variants for an architecture (sh4 or st200). The built files will be placed in BUILT/u-boot/<board>-stm20

STM/buildenv <arch>
Builds standard environments for installing onto u-boot targets. The built files will be placed in BUILT/u-boot/<board>-stm20. Each board directory will contain a text version and a u-boot image file.

STM/mkenv <board> <outfile>
Writes a standard environment for board to outfile.

STM/mklinux -t <arch> -v <vmlinux> -n <image name> -t <tagefile>
Wrapper script for creating a u-boot Linux image file.

kscript

This is a set of kermit functions for setting up u-boot on a board:

sendcmd <cmd>
- send a single command <cmd> to u-boot via serial port
sendfile <file>
- send a script file to u-boot via u-boot
sendub
- copy u-boot.bin from current directory to target via serial port and copy it to flash
sendenv
- send the env script file from installed u-boot target board directory and save to flash.
serialsetupub
- send, via serial port, both u-boot and linux kernel from installed u-boot directory and save to flash.
- If "setupenv" exists in local directory then will send that as well.
netsetupub
- send, via network, both u-boot and Linux kernel from installed u-boot directory and save to flash.
- If "setupenv" exists in local directory then will send that as well.

Example environment "setupenv"

This contains a number of scripts for managing u-boot and kernel images:

update
copies the u-boot image from $load_addr to flash

setup-serial
Loads u-boot and Linux kernel image into flash via serial port
setup-nfs
Loads u-boot and Linux kernel image into flash via network

getub
Get u-boot image, via nfs, form u-boot directory on server into memory
getvm
Get kernel image, via nfs, from kernel directory on server into memory
getrd
Get ramdisk image, via nfs, from kernel directory on server into memory

sgetub
Get u-boot image, via serial, form u-boot directory on server into memory
sgetvm
Get kernel image, via serial, from kernel directory on server into memory

cpub
Copy u-boot image downloaded into memory using getub/sgetub into flash
cpvm
Copy kernel image downloaded into memory using getvm/sgetvm into flash
cprd
Copy ramdisk image downloaded into memory using getvm/sgetvm into flash

boot_ram
Boot Linux kernel from flash using ramdisk filesystem image
set boot_nfs
Boot Linux kernel from flash using nfs mounted filesystem
set boot_hda
Boot Linux kernel from flash using disk mounted filesystem
set boot_disk
Boot Linux kernel from dedicated disk partition using disk mounted filesystem
set boot_ext2
Boot Linux kernel from ext2 disk partition using disk mounted filesystem

Previous Contents Next