UM0478

User Manual

SPEAr® Plus Linux SDK, getting started

Introduction
The SPEAr Plus Linux SDK (Software Development Kit) enables ST customers and third
parties to exploit a reference embedded software platform, based on Linux OS, on top of the
SPEAr Plus development board.
The SDK is application-neutral and may be used for:
● evaluating Linux-based software architectures and performances for both the Head600
and Plus600 SPEAr SoCs;
● custom software development before a final customer’s hardware platform is available.

September 2008 Rev 2 1/31

www.st.com
Contents UM0478

Contents

1 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 SDK contents summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Default configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Using the dev. board with pre-flashed software . . . . . . . . . . . . . . . . . . 11

3.1 Entering the Linux shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Entering the resident monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Installing the development package . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.1 Host requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Installing the arm cross-build toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Installing SPEAr Plus Linux SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.4 Setting up a TFTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.5 Setting up a NFS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Flash memory and boot loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.1 NOR Flash partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 Updating XLoader on Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3 Updating U-Boot on Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.4 U-Boot commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.5 Rebuilding the boot loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6 The cross-building toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

7 Other tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1 Defining system RAM usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.2 Enabling the FPGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.3 Flashing firmware by JTAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Appendix A Default U-Boot environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2/31
UM0478 Contents

8 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3/31
List of tables UM0478

List of tables

Table 1. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Table 2. SDK contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Table 3. U-Boot - information commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 4. U-Boot - memory commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 5. U-Boot - environment commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 6. U-Boot - other commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 7. Toolchain commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 8. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

4/31
UM0478 List of figures

List of figures

Figure 1. NOR Flash default partitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5/31
Reference documentation UM0478

1 Reference documentation

1. STMicroelectronics, SPEAr Plus – Linux SDK, getting started, SW Ver. 1.1

2. STMicroelectronics, SPEAr Plus – Linux SDK, kernel and device APIs, SW Ver. 1.1
3. STMicroelectronics, SPEAr Plus – Linux SDK, embedded root filesystem, SW Ver. 1.1
4. STMicroelectronics, SPEAr Plus – Linux SDK, Release Notes, SW Ver. 1.1
5. STMicroelectronics, SPEAr Plus Development Board, user manual
6. STMicroelectronics, SPEAr Head600 Datasheet, http://www.st.com
7. STMicroelectronics, SPEAr Plus600 Datasheet, http://www.st.com
8. BusyBox, http://www.busybox.net
9. Free Software Foundation, The GNU C Library reference manual, Edition 0.11,
December 2006, Ver 2.6, http://www.gnu.org/software/libc/manual/
10. Free Software Foundation, Using the GNU Compiler Collection, GCC Version 4.0.4,
2005, http://www.gnu.org/software/gcc/onlinedocs/gcc-4.0.4/gcc.pdf
11. Denx Software Engineering, ELDK 4.1, http://www.denx.de
12. O’Reilly, Understanding the Linux kernel, 3rd Edition, 2006.

6/31
UM0478 Introduction

2 Introduction

The SPEAr Plus Linux SDK (software development kit, referred as just “SDK” in the
following) enables ST customers and third parties to exploit a reference embedded software
platform, based on Linux OS, on top of the SPEAr plus development board [5].
The SDK is application-neutral and may be used for:
● evaluating Linux-based software architectures and performances for both the Head600
[6] and Plus600 [7] SPEAr SoCs
● custom software development before a final customer’s hardware platform is available
This document provides an overview of the software provided with the SDK and an
operational guide assisting the end user in performing most common practical tasks.
Technical details about specific software components may be found in corresponding
documents [2,3].

2.1 Acronyms
Table 1. Acronyms
Acronym Explanation

API Application programming interface

ARP Address resolution protocol
CRAMFS Compressed ROM file system
CRC Cyclic redundancy check
DMA Direct memory access
EHCI Enhanced host controller interface
ELDK Embedded linux development kit
FAT File allocation table
GCC GNU compiler collection
GPIO General purpose I/O
GPL General public license (GNU)
HAL Hardware abstraction layer
HW Hardware
I2C Inter-integrated circuit bus
IP Internet protocol
IPC Inter-process communication
ISR Interrupt service routine
LAN Local area network
MAC Media access control
MTD Memory technology device

7/31
Introduction UM0478

Table 1. Acronyms (continued)

Acronym Explanation

NFS Network file system

OHCI Open host controller interface
OS Operating system
RAM Random access memory
RTC Real-time clock
RTOS Real time operating system
SDK Software development kit
SoC System on chip
SPEAr Structured processor enhanced architecture
ST STMicroelectronics
SW Software
TFTP Trivial file transfer protocol
UART Universal asynchronous receiver-transmitter
USB Universal serial bus
VIC Vectored interrupt controller
WDT Watchdog timer

2.2 SDK contents summary

The SDK 1.1 package is delivered as a single compressed archive file named
splus_linux_sdk_1_1.tar.bz2 and includes the contents summarized in the following
table:

Table 2. SDK contents

Contents Type Notes

User-friendly procedures for software rebuild on

General scripts – PC/Linux shell scripts
Linux PC host.
Software
– PDF documents See references [1,2,3,4,9,10].
documentation
Binary images corresponding to the runtime
Pre-built Flash
– binary image files software as pre-flashed on the development
images
boards.

– source code Open-source Linux Kernel, version 2.6.19.2

Linux Kernel – configuration and build customized by ST for the SPEAr plus dev.board
procedure (SoC architecture and device drivers).

8/31
UM0478 Introduction

Table 2. SDK contents (continued)

Contents Type Notes

The default tree that may be generated is optimized

by ST for small footprint and includes: initialization
Embedded root – configuration and build scripts, BusyBox profile, support for RAM disk and
filesystem procedure Flash disk, device access configurations. The root
filesystem may be easily extended by users
according to their application requirements.
Resident monitor
Open source U-Boot, version 1.2.0, customized by
and bootloader – source code
– build procedure ST for the SPEAr plus dev.board.
(U-Boot)
– source code ST-proprietary code, used as initial Flash
XLoader
– build procedure bootloader before running U-Boot.
Add-on tools. For instance, SDK 1.1 provides JTAG
support scripts and programs to be used for
Tools – miscellaneous reflashing XLoader and the U-Boot resident monitor
in case of damage to the original pre-flashed
version.

It should be remarked that the SDK does not directly contain any cross-build ARM toolchain.
In order to use SDK 1.1 for custom software development, the open source ELDK 4.1
package, by Denx Software Engineering [11] must be used. This package (ISO image file)
may be downloaded free-of-charge from Denx Web site at following URL:
ftp://ftp.denx.de/pub/eldk/4.1/arm-linux-x86/iso/arm-2007-01-21.iso
An overview of the tools provided by the ELDK toolchain can be found in the corresponding
section of this document.
In this entire document, interactive commands are shown in courier bold font. The “#”
prompt is assumed for the Linux shell on the target board. The “$” prompt is assumed for
the Linux shell on the PC host. The “spearplus>” prompt is assumed for interaction with
the resident monitor (U-Boot).

9/31
Introduction UM0478

2.3 Default configuration

As originally delivered, SDK 1.1 is configured to operate under the following conditions:
● single ARM9 CPU enabled, 333 MHz clock
● support for 8 MB serial NOR Flash, with 5 pre-defined partitions
● support for all system RAM available on the board
● UART 0 serial port used for U-Boot and Linux console
● Gigabit Ethernet support enabled
● bootstrap from serial NOR Flash based on XLoader and U-Boot
● Linux kernel 2.6.19.2
● USB host stack and USB mass storage support statically linked with kernel
● USB device stack statically linked with kernel
● DMA, GPIO, I2C, RTC, UART device drivers statically linked with kernel
● embedded root filesystem based on BusyBox and GLIBC
● support for C++ applications not included in default configuration (while it may be
added by extending the root filesystem with additional runtime libraries at the cost of
about extra 300 KB)
● ELDK 4.1 cross-building ARM toolchain
● Linux PC host with x86 GNU toolchain (version 3.2 or higher) for software development
● Optional Windows PC for console interaction or TFTP file transfer
● 2 XLoader variants (266 and 166 MHz DDR)

10/31
UM0478 Using the dev. board with pre-flashed software

3 Using the dev. board with pre-flashed software

Using the SPEAr Plus development board with pre-flashed software may be initially useful to
get a first feeling about the target hardware platform and the embedded Linux environment.
This step does not actually require the installation of the toolchain and the SDK. Only
software documents need to be extracted from the SDK package.
Note: if, for any reason, the development board would have no pre-flashed Linux SDK 1.1 software
but there is at least a working U-Boot monitor available, then a Flash update is initially
required; see [2] and [3] to store on Flash the SDK 1.1 kernel and root filesystem
respectively; as a final step, XLoader and U-Boot must be updated as described later in this
document; U-Boot environment settings must also be configured and saved as reported in
Appendix A; if the development board would have no software at all, see Section 7.3 for the
JTAG-based flashing procedure.
Basic user interaction with the development board may be performed through a simple serial
host-target link. Either a Windows PC or a Linux PC may be used for this purpose. In case of
issues with the serial connection, the following aspects should be considered:
● Check that the PC-side serial port (real RS232 or USB adapter) is properly configured
as 115200 bps, 8-N-1 mode, no flow control.
● Try to change the double jumper J14, located close to UART 0 DB9 connector on the
development board, by a 90-degrees rotation

3.1 Entering the Linux shell

The following procedure has to be followed to boot the pre-flashed software up to the Linux
shell prompt:
1. Connect the target board to a PC using a null-modem serial cable (the UART0 DB9
connector must be used). If the PC has no serial port, a USB-to-serial adapter on PC
side may be used as well.
2. Start a terminal emulator on the PC host, such as minicom for Linux or HyperTerminal
for Windows. In both cases, the PC-side serial port (a real RS232 or a USB adapter)
must be set to 115200 bps, 8-N-1 mode, no flow control.
3. From the terminal emulator, open a connection on the selected serial port.
4. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – OFF
3 – OFF
4 - OFF
Check that dip switch SW4 on the board is configured as follows:
1 - ON
2 - ON
3 - ON
4 - ON
5 - ON
6 - ON

11/31
Using the dev. board with pre-flashed software UM0478

7 - OFF
8 - ON
5. Switch on the target board and wait until the Linux shell prompt (the # character) is
displayed on the terminal emulator console. The bootstrap with this pre-flashed
software configuration would take just few seconds.
6. At this point, Linux commands may be interactively issued. For the list of default
supported commands and the overall filesystem structure see [3].

3.2 Entering the resident monitor

The following procedure has to be followed to boot the pre-flashed software and enter the
bootloader/monitor (U-Boot) without running Linux:
1. Connect the target board to a PC using a null-modem serial cable (the UART0 DB9
connector must be used). If the PC has no serial port, a USB-to-serial adapter may be
used on PC side as well.
2. Start a terminal emulator on the PC host, such as minicom for Linux or HyperTerminal
for Windows. In both cases, the PC-side serial port (a real RS232 or a USB adapter)
must be set to 115200 bps, 8-N-1 mode, no flow control.
3. From the terminal emulator, open a connection on the selected serial port.
4. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – ON
3 – OFF
4 – OFF
Check that dip switch SW4 on the board is configured as follows:
1 - ON
2 - ON
3 - ON
4 - ON
5 - ON
6 - ON
7 - OFF
8 - ON
5. Switch on the target board and wait until the U-Boot prompt (spearplus>) is displayed
on the terminal emulator console. The bootstrap with this pre-flashed software
configuration would take less than one second.
6. At this point, U-Boot commands may be interactively issued. For a quick guide of
supported commands and functionality see the relevant section of this document.

12/31
UM0478 Installing the development package

4 Installing the development package

Developing custom software requires a full installation of the ARM cross-build toolchain
(ELDK 4.1) and the SPEAr Plus Linux SDK package. The installation is a pure PC-side
process, no development board or host-target link is required at this stage.

4.1 Host requirements

Software development with SDK 1.1 is supported on Linux PC hosts only. Most popular PC
Linux distributions are suitable, as soon as a standard x86 GNU toolchain (version 3.2 or
higher) is already installed.
There is no specific requirement on the availability of a Linux GUI environment. All
development tasks can be performed just using command line tools. However, in order to
use graphical Linux configuration tools, XWindow and GTK (or Qt ) are required.
A serial port is mandatory. If not available, a USB serial adapter may be used. An Ethernet
port is optional while recommended for fast host-target data transfer.

4.2 Installing the arm cross-build toolchain

The first installation phase is concerned with the ELDK 4.1 (GNU glibc version) toolchain
package. It is assumed here that the ISO image file arm-2007-01-21.iso has been
already downloaded from Denx site and extracted to a temporary directory. In alternative, an
equivalent CD-ROM version might be mounted on the Linux PC filesystem.
The procedure is the following:
1. On the Linux PC, from a “bash” shell, enter in the arm-2007-01-21 directory (top
level of the ELDK tree).
2. Execute the following commands:
$ mkdir /opt/eldk
$ mkdir /opt/eldk/4.1
$ ./install -d /opt/eldk/4.1
Then, answer 'y' to the confirmation request.
This will install the ELDK toolchain under /opt/eldk/4.1
3. Wait until the installation is completed (several minutes).
4. Configure the shell environment as follows:
$ export
PATH=$PATH:.:/opt/eldk/4.1/usr/bin:/opt/eldk/4.1/usr/armlinux/b
in
$ export CROSS_COMPILE=arm-linux-
Note that, in order to make persistent this configuration, commands should be also put
in a bash shell initialization file.

13/31
Installing the development package UM0478

4.3 Installing SPEAr Plus Linux SDK

Assuming that a properly working ELDK 4.1 installation is now available, the next phase is
the installation of the actual SDK. It is assumed here that the SDK archive file
splus_linux_sdk_1_1.tar.bz2 has been already obtained from ST’s CD-ROM or by
online download from ST Web site:
http://www.st.com/spear
The procedure is very straightforward. On the host Linux PC, just extract the SDK contents
to
/opt $ tar -xvjf splus_linux_sdk_1_1.tar.bz2 -C /opt
After installation (archive extraction) the structure of the SDK tree will look like the following:
[splus_linux_sdk_1_1]
build.sh
[doc]
gcc.pdf
libc.pdf
splus_linux_sdk_1_1_emb_rootfs.pdf
splus_linux_sdk_1_1_getting_started.pdf
splus_linux_sdk_1_1_kernel_and_apis.pdf
splus_linux_sdk_1_1_release_notes.pdf
[flash]
bootImage.sh
bootImage.bin
linux_comp.uimg
linux_comp_dbg.uimg
linux_uncomp.uimg
linux_uncomp_dbg.uimg
rootfs_comp.uimg
rootfs_uncomp.uimg
rootfs_uncomp.flash
uboot.uimg
xloader166DDR.uimg
xloader266DDR.uimg
[rootfs]
[bin]
[dev]
[etc]
...
[src]
[linux-2.16.9.2]
Makefile
[arch]
[block]
...
[rootfs-1.1.A]
busybox-1.10.2.tar
mkrootfs.sh
mkrootfs-custom.sh
[configs]
BusyboxConfig

14/31
UM0478 Installing the development package

[uboot-1.2.0]
Makefile
[board]
[common]
...
[xloader]
Makefile
[ddr]
[include]
...
[tools]
[jtag]
erase_nor.cmm
flasher.elf
init_ram.cmm
init_ram.elf

The build.sh shell script has to be used everytime a total or partial software rebuild is
required.
The [doc] folder includes all software-related documents in PDF format.
The [flash] folder contains pre-built binary images corresponding to the original software
pre-stored by ST in NOR Flash partitions for SPEAr Plus evaluation boards.
It also contains single bootImage.bin for flashing xloader, uboot, kernel and rootfilesystem
using single Image.By default Single Image is build using xloader at 266 MHz, uboot.uimg,
linux_uncomp.uimg and rootfs_uncomp.uimg. Single Image size is of 8 MB.
The [rootfs] folder is a predefined expanded root filesystem that can be used for mounting
through NFS.
Under the [src] subtree, the source code for all the main target components is found.
The [linux-2.16.9.2] source code tree contains the Linux kernel, including SPEAr Plus
specific extensions (e.g. device drivers) and adaptations.
The [rootfs-1.1.A] subtree provides all the required elements to configure and rebuild a root
filesystem, for both a flashed target (ext2) and the expanded version for NFS mounting.
The [uboot-1.2.0] source code tree contains the U-Boot loader and resident monitor,
including SPEAr Plus specific extensions and adaptations.
The [xloader] source code tree contains the ST-proprietary 1st-level boot loader called
XLoader.
The xloader can be build for DDR frequency 166 MHz as well as for 266 MHz.
The [tools] directory is intended to provide any other support tool. In SDK 1.1, a [jtag]
subtree is available containing scripts and ARM programs to support the flashing of boot
loaders using JTAG and the Lauterbach TRACE-32 toolset.

15/31
Installing the development package UM0478

4.4 Setting up a TFTP server

TFTP is a file transfer protocol running over an Ethernet host-target link. When working with
the SPEAr Plus evaluation board and the SDK, such protocol is very useful for many tasks
(updating the board Flash memory, dynamically loading applications to board’s RAM disk,
etc.) so the installation/configuration of a TFTP server on the PC host is highly
recommended.
No specific TFTP server is provided inside the SDK.
For Linux hosts, the TFTP daemon is usually configured as part of the general xinetd
daemon. Please consult the documentation of the specific PC Linux distribution for setup
details. In SDK documentation, it is assumed that the default top directory for the TFTP
daemon is configured as splus_tftp.
For Windows hosts, both commercial and shareware tools (such as TFTPD32, see
http://tftpd32.jounin.net) are available. Tool setup is automatic in this case and
the default path is specified from the user interface.
After TFTP server installation on either Linux or Windows, files to be uploaded to the target
board have just to be copied under TFTP server top directory.
When using TFTP to transfer files between the embedded Linux environment and the PC,
the tftp command is invoked from the board’s Linux shell (see [3] for details). TFTP may be
also used to boot the kernel through Ethernet (see [2] for details).

4.5 Setting up a NFS server

NFS is a client/server remote file system protocol running over an Ethernet host-target link.
NFS server installation and/or configuration is required only if it is planned to mount a root
filesystem from the network for development purposes.
Unlike TFTP, the NFS server usually requires a Linux-based PC host. Please consult the
documentation of the specific PC Linux distribution for setup details. In any case, the top
directory of the expanded root filesystem on the PC (as provided by the SDK) must be
specified to the NFS server by adding a line like the following in the /etc/exports file of
Linux host:
/opt/splus_linux_sdk_1_1/rootfs *(rw,no_root_squash,sync)

16/31
UM0478 Flash memory and boot loaders

5 Flash memory and boot loaders

Booting the Linux environment on SPEAr Plus development boards is performed through
multiple steps, each one carried out by a different software component. After the execution
of an on-chip firmware known as BootROM, control is given to the XLoader software.
XLoader is a very small program assumed to be stored in the first sector (zero) of the serial
NOR Flash. XLoader is mainly in charge of initializing internal clocks and RAM controller
settings. After this tasks, it loads a more sophisticated component (U-Boot) that will act as
real resident monitor as well as the final boot loader for the Linux environment. Like
XLoader, U-Boot is actually OS-agnostic. However, the SDK documentation will mainly refer
to U-Boot features and configurations that are relevant to Linux.
On the NOR Flash, sector range 1-4 is reserved to the U-Boot partition. Since each sector is
64 KB, the maximum size of the resident monitor is 256 KB. This size also takes into
account a storage area for saving U-Boot settings (the so-called environment variables) in a
persistent way.
It is very important to assure that the XLoader and the U-Boot partitions are restored to
write-protected mode after any Flash update. Any unexpected writing access to such Flash
partitions will usually led to a system bootstrap failure. In fact, besides software updates,
there is no other case where writing to this partition is required. Write-protection, anyway, is
already performed by ST-provided scripts as discussed in the next sections.

5.1 NOR Flash partitions

One major role of U-Boot is also to enable end users to update NOR Flash partitions. The
procedure to update the Linux kernel partition is described in [2]. The procedure to update
the embedded root filesystem partition is described in [3]. The procedures to update
XLoader and U-Boot partitions from U-Boot itself are described later inside this document.
When operating with U-Boot, it is important to understand the default map of the serial NOR
Flash as exploited by SDK 1.1. Such map is depicted in Figure 1.

17/31
Flash memory and boot loaders UM0478

Figure 1. NOR Flash default partitions

xloader.uimg Sector 0 (Max 64 KB)

XLoader
Sectors 1-4 (Max 256 KB)
uboot.uimg U-Boot

linux.uimg Kernel Sectors 5-47

8 MB NOR Flash

rootfs.cram Root Filesystem Sectors 48-126

R/W Area Sector 127 (Max 64 KB)

The default map has been designed to accommodate most common requirements. Of
course, such map may be modified according to different needs. However, this goal would
require a number of changes to various aspects of the entire solution:
● the linux-2.6.19.2\drivers\mtd\devices\spr_mtd_nor_partition.h
header file, where the partition table is statically defined (stwsf_par_info_primary
structure)
● the pre-defined U-Boot scripts that support flashing, for partitions where offset has
been modified (partition size is automatically managed)
Anyway, XLoader is basically fixed inside the single-sector 0. U-Boot size may be also
usually kept unmodified. Most likely changes will be related to enlarging or shrinking the
kernel and the root filesystem partitions, depending on specific applications and objectives.
Finally, the R/W partition could be removed at all, in case alternative solutions to writable
persistent storage (e.g. the on-board I2C EEPROM) are adopted.
Consult Appendix A of this document to fully restore default U-Boot settings in case of any
damage to them.

5.2 Updating XLoader on Flash

An Ethernet host-target link is the fastest way to support Flash updating.
A predefined U-Boot script (flash_xloader_eth) has been made available as predefined
on the development boards to minimize manual steps. In order to update the XLoader
partition with a new binary image using Ethernet, the following procedure has to be
performed:

18/31
UM0478 Flash memory and boot loaders

1. Connect the target board to a PC using both a null-modem serial cable (the UART0
DB9 connector must be used) and an Ethernet cross cable or an Ethernet hub/switch.
2. Assure that the TFTP server is running on the PC and copy the xloader.uimg file to
the default TFTP server directory.
3. Launch a terminal emulator (HyperTerminal, minicom, etc.) on the PC. The PC serial
port must be set to 115200 bps, 8-N-1 mode, no flow control.
4. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – ON
3 – OFF
4 - OFF
Then switch on or just reset the target board.
5. From U-Boot prompt, execute the following command:
spearplus> run flash_xloader_eth
This will first start transfer the file from PC to the board over Ethernet. After the transfer,
the command will automatically proceed by completing all required steps for flashing
and verification.
An alternative to Ethernet for Flash updating is the use of a serial link and the Kermit
protocol. This approach is slower but still useful when an Ethernet link is not available. In
fact, the XLoader image is very small (maximum 64 KB), so a serial transfer may be still
convenient. A predefined U-Boot script (flash_xloader_uart) has been made available
as predefined on the development boards to minimize manual steps. In order to update the
XLoader partition with a new binary image using the serial link, the following procedure has
to be performed:
1. Connect the target board to a PC using both a null-modem serial cable (the UART0
DB9 connector must be used).
2. Launch a terminal emulator with Kermit support (HyperTerminal, minicom, etc.) on the
PC. The PC serial port must be set to 115200 bps, 8-N-1 mode, no flow control.
3. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – ON
3 – OFF
4 - OFF
Then switch on or just reset the target board.
4. From U-Boot prompt, execute the following command:
spearplus> run flash_xloader_uart
U-Boot is now waiting for a Kermit file transfer from the PC terminal. The
xloader.uimg file must be selected from a PC directory.
After the transfer is started on the PC, the command will proceed by transferring (using
Kermit) the file over serial cable and completing all required steps for flashing and
verification.

5.3 Updating U-Boot on Flash

A predefined U-Boot script (flash_uboot_eth) has been made available as predefined
on the development boards to minimize manual steps. In order to update the U-Boot
partition with a new binary image using Ethernet, the following procedure has to be
performed:

19/31
Flash memory and boot loaders UM0478

1. Connect the target board to a PC using both a null-modem serial cable (the UART0
DB9 connector must be used) and an Ethernet cross cable or an Ethernet hub/switch.
2. Assure that the TFTP server is running on the PC and copy the uboot.uimg file to the
default TFTP server directory.
3. Launch a terminal emulator (HyperTerminal, minicom, etc.) on the PC. The PC serial
port must be set to 115200 bps, 8-N-1 mode, no flow control.
4. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – ON
3 – OFF
4 - OFF
Then switch on or just reset the target board.
5. From U-Boot prompt, execute the following command:
spearplus> run flash_uboot_eth
This will first start transfer the file from PC to the board over Ethernet. After the transfer,
the command will automatically proceed by completing all required steps for flashing
and verification.
A predefined U-Boot script (flash_uboot_uart) has been made available as predefined
on the development boards to minimize manual steps. In order to update the U-Boot
partition with a new binary image using the serial link, the following procedure has to be
performed:
1. Connect the target board to a PC using both a null-modem serial cable (the UART0
DB9 connector must be used).
2. Launch a terminal emulator with Kermit support (HyperTerminal, minicom, etc.) on the
PC. The PC serial port must be set to 115200 bps, 8-N-1 mode, no flow control.
3. Check that dip switch SW3 on the board is configured as follows:
1 – OFF
2 – ON
3 – OFF
4 - OFF
Then switch on or just reset the target board.
4. From U-Boot prompt, execute the following command:
spearplus> run flash_uboot_uart
U-Boot is now waiting for a Kermit file transfer from the PC terminal. The uboot.uimg file
must be selected from a PC directory.
After the transfer is started on the PC, the command will proceed by transferring (using
Kermit) the file over serial cable and completing all required steps for flashing and
verification.

5.4 U-Boot commands

The U-Boot resident monitor offers an interactive command-line interface that can be used
through the serial console. A full list of the available U-Boot commands may be obtained by
entering the help command (or by simply typing the “?” character). When help is followed
by a command name, a description of that specific command is displayed.
The following set of commands return various kind of general information about the system:

20/31
UM0478 Flash memory and boot loaders

Table 3. U-Boot - information commands

Command Description

bdinfo Reports information about the development board.

coninfo Reports information about the console device.
flinfo Reports information about the NOR Flash memory.
Reports information about a binary image in a partition (except for the root
iminfo
filesystem and the R/W area that have no standard U-Boot image header).
Lists all the partitions found in Flash (except for the root filesystem and the
imls
R/W area that have no standard U-Boot image header).
version Displays the U-Boot version.

Memory areas (including memory-mapped registers) may be read and written using the
following set of commands:

Table 4. U-Boot - memory commands

Command Description

base Sets a memory offset (or returns current offset).

cmp Compares memory areas.
cp Copies memory areas.
loop Infinite loop on address range.
md Reads memory location(s).
mm Writes memory location(s) with auto-increment.
mw Writes memory location(s).
nm Writes memory location(s) with constant address.

The most commonly used commands are md and mw, enabling manual access to hardware
register banks for testing purposes.
A specific subgroup of commands, very often invoked by end users, is related to the
management of environment variables. Such variables are string-type fields that may be
read and written, and may be also stored on Flash to guarantee their persistence across
system reboots. Some of these variables have a predefined purpose, but users may also
add their own custom variables.

Table 5. U-Boot - environment commands

Command Description

printenv Lists all defined environment variables.

Executes the contents of an environment variable, handling it as a script
run
(sequence of U-Boot commands).
saveenv Saves the current contents of environment variables to NOR Flash.
setenv Assigns a new value to an environment variable.

Other frequently used commands are finally listed in the following table.

21/31
Flash memory and boot loaders UM0478

Table 6. U-Boot - other commands

Command Description

bootm Starts the execution of a program loaded in memory.

erase Erases a range of NOR Flash sectors.
Verifies the correctness of a flashed partition (except for the root filesystem
imi
and the R/W area that have no standard U-Boot image header).
Transfers a binary file from the PC to the board using a serial cable and
loadb
Kermit protocol.
ping Tests Ethernet connection between the board and the PC.
protect Turns on/off write-protection of a NOR Flash sector range.
Transfers a binary file from the PC to the board using Ethernet and TFTP
tftp
protocol.
tftpboot Used to boot the Linux kernel from PC using Ethernet and TFTP protocol.

A detailed documentation about the described commands, as well as additional ones, may
be found in U-Boot specific documents.

5.5 Rebuilding the boot loaders

The boot loaders do not need to be typically rebuilt.
However, XLoader may be rebuilt after custom changes to its source code in order to use
different system clocks settings (ARM CPU core, AHB bus, APB bus). Such parameters are
defined in the following file:
/opt/splus_linux_sdk_1_1/src/xloader/include/splus_pll.h
Other changes may be required when rebuilding for custom boards, different from the
SPEAr Plus development board.
XLoader is then rebuilt using the following commands:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh xloader
The output of this operation will be an updated binary image located under:
/opt/splus_linux_sdk_1_1/flash/xloader.uimg
In case of customizations, U-Boot may be rebuilt using the following commands:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh uboot
The output of this operation will be a binary image located under:
/opt/splus_linux_sdk_1_1/flash/uboot.uimg
All generated .uimg files are already in the proper format to be used by U-Boot itself for
flashing. The following commands also rebuild everything including XLoader and U-Boot:
$ cd /opt/splus_linux_sdk_1_1
$ build.sh all

22/31
UM0478 The cross-building toolchain

6 The cross-building toolchain

Knowing the details about the ARM cross-building toolchain is not strictly required in case of
software development limited to changes of XLoader, U-Boot or Linux kernel components
(e.g. device drivers). In fact, the rebuild procedure predefined by the SDK (build.sh)
performs all required tasks (by internally invoking toolchain commands) in a transparent
way.
On the other hand, at least a base knowledge of cross-building tools is needed by
application developers. The ARM toolchain is a set of programs, running on the PC host but
targeting ARM-related output, with support for:
● cross-compilation of source code to generate native object code for the ARM CPU
core(s) provided by the SPEAr Plus SoC
● cross-linking of ARM object code to generate executable programs, shared libraries
and binary images
● managing object code archives, incremental rebuilding and other auxiliary tasks

A summary of the command-line tools provided by ELDK 4.1 ARM cross-development

toolchain is reported in the following table. For further details, please consult [10] as well as
ELDK documentation.

Table 7. Toolchain commands

Package Version Tool Description

gcc C Cross-compiler for ARM

GCC 4.0.0
gcov Code coverage
ar Archiver
as Cross-assembler for ARM
gprof Profiling tool
ld Cross-linker for ARM
nm Lists symbols in object files
binutils 2.16.1 objcopy Copies a binary file.
objdump Displays information from object files.
ranlib Generates an index to speed access to archives.
Displays the information about the contents of ELF format
readelf
files
strip Remove symbols and sections from files.
GNU Make 3.80 make Incremental build management
GDB 6.3.0 gdb Debugger
Lists what shared libraries are used by given dynamically-
n.a. n.a. ldd
linked executables.
n.a. n.a. mkcramfs Creates CRAMFS binary image from file tree.
n.a. n.a. mkimage Creates a binary image suitable for flashing with U-Boot.

23/31
The cross-building toolchain UM0478

Only a few commands are frequently used by application software developers. The most
important of them are the C cross-compiler and linker (gcc), the archiver (ar) and utilities like
make, strip and readelf.
After a correct toolchain installation as explained in Section 4.2, the search path for
executable will be properly set so that such commands may be directly invoked with the
arm-linux- or the ${CROSS_COMPILE} or prefix.
The following example compiles a single C-language source file (example.c) to an ARM
object file (example.o):
$ arm-linux-gcc –c example.c
Usually an optimization flag is also added as shown in the following:
$ arm-linux-gcc –O2 –c example.c
In order to generate an ARM executable program called “myprog” (in standard ELF
format), starting from one or more object files, a command like the following may be used:
$ arm-linux-gcc –o myprog file1.o file2.o ... fileN.o
If a shared library is needed instead of an executable program, then the command is
modified as follows:
$ arm-linux-gcc –o mylib.so –shared file1.o file2.o ... fileN.o
If a static library is needed instead of an executable program, then a command like the
following is used:
$ arm-linux-ar rcs mylib.a file1.o file2.o ... fileN.o
The strip command may be used to reduce the size of an executable program by
removing the symbol table:
$ arm-linux-strip –s myprog
The readelf command is sometimes useful to check the header information of an ARM
file, for instance:
$ arm-linux-readelf –h myprog

24/31
UM0478 Other tasks

7 Other tasks

7.1 Defining system RAM usage

The default configuration delivered with SDK 1.1 assumes the typical minimum system RAM
(64 MB) available on a SPEAr Plus development board. However, it is possible to force the
size of accessible RAM to different values through a Linux kernel parameter specified from
U-Boot. This approach is useful to emulate the actual RAM size of a planned product that
has less RAM than the development board or to use more than 64 MB RAM, if available.
The RAM size is specified through the mem=<size>M parameter passed to the kernel by U-
Boot. The following example shows how to change U-Boot settings to boot Linux with only
32 MB RAM:
# setenv bootargs console=ttyS0 quiet root=/dev/mtdblock3
rootfstype=ext2 mem=32M;saveenv
After resetting the board, Linux will use only 32 MB RAM ignoring the rest of physical
memory.
It should be remarked that setting RAM to too much low values may lead to a slower system
or to a solution that does not work at all.

7.2 Enabling the FPGA

The SPEAr Plus development board includes a FPGA where custom logic may be
programmed for specific purposes. For projects exploiting the FPGA, an additional
procedure is required for its initialization. This procedure is described here in terms of U-
Boot commands.
The default U-Boot environment already includes the settings to enable the FPGA device for
66 MHz clock:
init1=mw fca80054 06100612;mw fca80050 06100012;mw fca80054
06102613;mw fca80050 06100013
init2=mw fca80054 0610a613;mw fca80054 06102613;mw fca80050
06108013;mw fca80050 06100013
init3=mw fca80054 06102413
fpga66mhz=run init1;run init2;run init3
By default, the FPGA is not enabled and the boot command variable is set as follows:
bootcmd=bootm 0xF8050000
To enable the FPGA, change the boot command variable as follows, then reset the board:
spearplus> setenv bootcmd run fpga66mhz;bootm 0xF8050000
spearplus> savenv

25/31
Other tasks UM0478

7.3 Flashing firmware by JTAG

A JTAG host-target link is not required in typical operational scenarios. However, a JTAG
connection is needed in case the bootstrap firmware (XLoader and U-Boot) is no longer
properly working on the development board. In this case, the two corresponding partitions
on NOR Flash must be restored through JTAG tools.
The SDK provides the ARM code for flashing as well as some scripts to be used with JTAG
tools. Such scripts (.cmm) are compatible with the syntax of Lauterbach’s TRACE-32 JTAG
environment. Anyway, it would be very easy to adapt them to JTAG tools from other vendors.
The step-by-step procedure to restore system boostrap on NOR Flash is the following:
1. Copy the following files from splus_linux_sdk_1_1 SDK tree to a folder on a Windows
PC and change the working directory to that folder:
tools/jtag/erase_nor.cmm (script)
tools/jtag/init_ram.cmm (script)
tools/jtag/init_ram.elf (ARM exe)
tools/jtag/flasher.elf (ARM exe)
flash/xloader.uimg (flash image)
flash/uboot.uimg (flash image)
2. Connect the Lauterbach TRACE-32 device to PC USB port.
3. Connect the Lauterbach TRACE-32 JTAG device to the development board’s JTAG
connector (J8).
4. Connect the PC to the board with a null modem cable.
5. Launch and configure Hyperterminal as usual.
6. Launch the TRACE-32 software application.
7. Switch on the TRACE-32 JTAG device.
8. Switch on the board.
9. Using TRACE-32 menu "CPU > System Settings", open the setting dialog box then set
CPU to “ARM926EJS” and “JTAG” to 5 MHz.
10. Click on TRACE-32 menu "CPU > In target Reset"
11. Click on TRACE-32 menu "View > List Source", then check that firmware stopped at
address 0xFFFF0000
12. Click on TRACE-32 menu "File > Batchfile", then select the "erase_nor.cmm" script file.
This script will run for about 1 minute and will erase the entire NOR Flash.
13. Reset the development board.
14. Click on TRACE-32 menu "CPU > In target Reset"
15. Click on TRACE-32 menu "View > List Source", then check that firmware stopped at
address 0xFFFF0000
16. Click on TRACE-32 menu "File > Batchfile", then select the " init_ram.cmm" script file.
After about 10 seconds, check that program stopped.
17. Click on TRACE-32 menu "File > Load", then select the "flasher.elf" program file.
18. Click on TRACE-32 menu "Run > Go". The Hyperterminal console will show a textual
menu:
********** SPEArPlus U-Boot Upgrade **********

26/31
UM0478 Other tasks

u-> for Upgrade UBoot code

x-> for Upgrade XLoader code
19. Click on TRACE-32 menu "Run > Break"
20. Issue TRACE-32 command "D.LOAD xloader.uimg 0x1300000”
21. Click on TRACE-32 menu "Run > Go"
22. Press 'x' in the console, the following message will be shown:
Upgrading XLoader ....
Erasing Sector Nr
0x00000000
Programming XLoader to Flash
XLoader Programmed successfully
Press s to stop r to run again
23. Click on TRACE-32 menu "Run > Break"
24. Issue TRACE-32 command "D.LOAD uboot.uimg 0x1300000”
25. Click on TRACE-32 menu "Run > Go"
26. Press 'r' then ‘u’ in the console, the following message will be shown:
Upgrading U-Boot ....
Erasing Sector Nr
0x00000001
Erasing Sector Nr
0x00000002
Erasing Sector Nr
0x00000003
Programming U-Boot to Flash
U-Boot Programmed successfully
press s to stop r to run again
27. Press 's' in console, then disconnect the JTAG cable from the development board.
28. Reset the board and check for correct booting on Hyperterminal console.

27/31
Default U-Boot environment UM0478

Appendix A Default U-Boot environment

For the sake of convenience, the full list of commands to be invoked from U-Boot in order to
restore the original default environment is reported in the following.
This is particularly useful when flashing the contents the first time for new development
boards, as well as when upgrading the U-Boot partition on Flash (since environment
variables will be lost on rewriting).
This listing takes into account all settings and scripts documented in software user manuals
[1], [2] and [3].
Each setenv assignment must correspond to a single text line to be entered.
setenv bootcmd bootm 0xF8050000
setenv bootargs console=ttyS0 quiet mem=64M root=/dev/mtdblock3
setenv fboot'setenv bootargs console=ttyS0 quiet mem=64M
root=/dev/mtdblock3 rootfstype=ext2;saveenv'
setenv nboot'setenv bootargs console=ttyS0 quiet mem=64M
root=/dev/nfs
nfsroot=192.168.1.1:/opt/splus_linux_sdk_1_1/rootfs;saveenv'
setenv flash_xloader_eth 'tftp 0x800000 xloader.uimg;protect off
1:0;erase 1:0;cp.b 0x800000 0xF8000000 ${filesize};protect on
1:0;imi 0xF8000000;saveenv'
setenv flash_xloader_uart 'loadb 0x800000;protect off 1:0;erase
1:0;cp.b 0x800000 0xF8000000 ${filesize};protect on 1:0;imi
0xF8000000;saveenv'
setenv flash_uboot_eth 'tftp 0x800000 uboot.uimg;protect off 1:1-
4;erase 1:1-4;cp.b 0x800000 0xF8010000 ${filesize};protect on
1:1-4;imi 0xF8010000;saveenv'
setenv flash_uboot_uart 'loadb 0x800000;protect off 1:1-4;erase
1:1-4;cp.b 0x800000 0xF8010000 ${filesize};protect on 1:1-4;imi
0xF8010000;saveenv'
setenv flash_linux_eth 'tftp 0x800000 linux${dbg}.uimg;protect off
1:5-47;erase 1:5-47;cp.b 0x800000 0xF8050000
${filesize};protect on 1:5-47;imi 0xF8050000'
setenv flash_linux_uart 'loadb 0x800000;protect off 1:5-47;erase
1:5-47;cp.b 0x800000 0xF8050000 ${filesize};protect on 1:5-
47;imi 0xF8050000'
setenv flash_root_eth 'tftp 0x800000 rootfs.cram;protect off 1:48-
126;erase 1:48-126;cp.b 0x800000 0xF81d0000 ${filesize};protect
on 1:48-126;cmp.b 0xF81d0000 0x800000 ${filesize}'
setenv flash_root_uart 'loadb 0x800000;protect off 1:48-126;erase
1:48-126;cp.b 0x800000 0xF81d0000 ${filesize};protect on 1:48-
126;cmp.b 0xF81d0000 0x800000 ${filesize}'
setenv init1 'mw fca80054 06100612;mw fca80050 06100012;mw fca80054
06102613;mw fca80050 06100013'

28/31
UM0478 Default U-Boot environment

setenv init2 'mw fca80054 0610a613;mw fca80054 06102613;mw fca80050

06108013;mw fca80050 06100013'
setenv init3 'mw fca80054 06102413'
setenv fpga66mhz 'run init1;run init2;run init3’
setenv baudrate 115200
setenv ipaddr 192.168.1.10
setenv netmask 255.255.255.0
setenv serverip 192.168.1.1
saveenv

29/31
Revision history UM0478

8 Revision history

Table 8. Document revision history

Date Revision Changes

14-Nov-2007 1 Initial release.

Minor package upgrade, mainly extending DDR clock to 266
1-Sep-2008 2
MHz and supporting Gigabit Ethernet

30/31
UM0478

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the
right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any
time, without notice.
All ST products are sold pursuant to ST’s terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no
liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this
document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products
or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such
third party products or services or any intellectual property contained therein.

UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZE REPRESENTATIVE OF ST, ST PRODUCTS ARE NOT DESIGNED,
AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING APPLICATIONS,
NOR IN PRODUCTS OR SYSTEMS, WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY, DEATH, OR
SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE.

Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void
any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any
liability of ST.

ST and the ST logo are trademarks or registered trademarks of ST in various countries.

Information in this document supersedes and replaces all information previously supplied.

The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.

© 2008 STMicroelectronics - All rights reserved

STMicroelectronics group of companies

Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan -
Malaysia - Malta - Morocco - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America
www.st.com

31/31