14121

September 2008 Rev 2 1/31

UM0478User Manual

SPEAr® Plus Linux SDK, getting started

IntroductionThe 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.

www.st.com

http://www.st.com

Contents UM0478

2/31

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

UM0478 Contents

3/31

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

List of tables UM0478

4/31

List of tables

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

UM0478 List of figures

5/31

List of figures

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

Reference documentation UM0478

6/31

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.

UM0478 Introduction

7/31

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

Introduction UM0478

8/31

2.2 SDK contents summaryThe 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:

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

Table 1. Acronyms (continued)

Acronym Explanation

Table 2. SDK contents

Contents Type Notes

General scripts – PC/Linux shell scriptsUser-friendly procedures for software rebuild on Linux PC host.

Software documentation

– PDF documents See references [1,2,3,4,9,10].

Pre-built Flash images

– binary image filesBinary images corresponding to the runtime software as pre-flashed on the development boards.

Linux Kernel– source code– configuration and build

procedure

Open-source Linux Kernel, version 2.6.19.2 customized by ST for the SPEAr plus dev.board (SoC architecture and device drivers).

UM0478 Introduction

9/31

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).

Embedded root filesystem

– configuration and build procedure

The default tree that may be generated is optimized by ST for small footprint and includes: initialization scripts, BusyBox profile, support for RAM disk and Flash disk, device access configurations. The root filesystem may be easily extended by users according to their application requirements.

Resident monitor and bootloader

(U-Boot)

– source code– build procedure

Open source U-Boot, version 1.2.0, customized by ST for the SPEAr plus dev.board.

XLoader – source code– build procedure

ST-proprietary code, used as initial Flash bootloader before running U-Boot.

Tools – miscellaneous

Add-on tools. For instance, SDK 1.1 provides JTAG support scripts and programs to be used for reflashing XLoader and the U-Boot resident monitor in case of damage to the original pre-flashed version.

Table 2. SDK contents (continued)

Contents Type Notes

Introduction UM0478

10/31

2.3 Default configurationAs 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)

UM0478 Using the dev. board with pre-flashed software

11/31

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 shellThe 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 – OFF2 – OFF3 – OFF4 - OFFCheck that dip switch SW4 on the board is configured as follows: 1 - ON2 - ON3 - ON4 - ON5 - ON6 - ON

Using the dev. board with pre-flashed software UM0478

12/31

7 - OFF8 - 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 monitorThe 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 – OFF2 – ON3 – OFF4 – OFFCheck that dip switch SW4 on the board is configured as follows:1 - ON2 - ON3 - ON4 - ON5 - ON6 - ON7 - OFF8 - 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.

UM0478 Installing the development package

13/31

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 requirementsSoftware 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 toolchainThe 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.1Then, 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:$ exportPATH=$PATH:.:/opt/eldk/4.1/usr/bin:/opt/eldk/4.1/usr/armlinux/bin$ 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.

Installing the development package UM0478

14/31

4.3 Installing SPEAr Plus Linux SDKAssuming 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.pdflibc.pdfsplus_linux_sdk_1_1_emb_rootfs.pdfsplus_linux_sdk_1_1_getting_started.pdfsplus_linux_sdk_1_1_kernel_and_apis.pdfsplus_linux_sdk_1_1_release_notes.pdf

[flash]bootImage.shbootImage.binlinux_comp.uimglinux_comp_dbg.uimglinux_uncomp.uimglinux_uncomp_dbg.uimgrootfs_comp.uimgrootfs_uncomp.uimgrootfs_uncomp.flashuboot.uimgxloader166DDR.uimgxloader266DDR.uimg

[rootfs][bin][dev][etc]...

[src][linux-2.16.9.2]

Makefile[arch][block]...

[rootfs-1.1.A]busybox-1.10.2.tar

mkrootfs.shmkrootfs-custom.sh

[configs]BusyboxConfig

UM0478 Installing the development package

15/31

[uboot-1.2.0]Makefile[board][common]...

[xloader]Makefile[ddr][include]...

[tools][jtag]

erase_nor.cmmflasher.elfinit_ram.cmminit_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.

Installing the development package UM0478

16/31

4.4 Setting up a TFTP serverTFTP 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 serverNFS 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)

UM0478 Flash memory and boot loaders

17/31

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 partitionsOne 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.

Flash memory and boot loaders UM0478

18/31

Figure 1. NOR Flash default partitions

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 FlashAn 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:

Sector 0 (Max 64 KB)

R/W Area

Root Filesystem

Kernel

U-Boot

XLoader

Sectors 1-4 (Max 256 KB)

Sectors 5-47

Sectors 48-126

Sector 127 (Max 64 KB)

8 MB NOR Flash

xloader.uimg

uboot.uimg

linux.uimg

rootfs.cram


19/31

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 – OFF2 – ON3 – OFF4 - OFFThen switch on or just reset the target board.

5. From U-Boot prompt, execute the following command:spearplus> run flash_xloader_ethThis 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.


4. From U-Boot prompt, execute the following command:spearplus> run flash_xloader_uartU-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 FlashA 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:


20/31

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.


5. From U-Boot prompt, execute the following command:spearplus> run flash_uboot_ethThis 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.


4. From U-Boot prompt, execute the following command:spearplus> run flash_uboot_uartU-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 commandsThe 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:


21/31

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

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.

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

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.

iminfo Reports information about a binary image in a partition (except for the root filesystem and the R/W area that have no standard U-Boot image header).

imlsLists all the partitions found in Flash (except for the root filesystem and the R/W area that have no standard U-Boot image header).

version Displays the U-Boot version.

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.

Table 5. U-Boot - environment commands

Command Description

printenv Lists all defined environment variables.

runExecutes the contents of an environment variable, handling it as a script (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.


22/31

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 loadersThe 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

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.

imiVerifies the correctness of a flashed partition (except for the root filesystem and the R/W area that have no standard U-Boot image header).

loadb Transfers a binary file from the PC to the board using a serial cable and Kermit protocol.

ping Tests Ethernet connection between the board and the PC.

protect Turns on/off write-protection of a NOR Flash sector range.

tftpTransfers a binary file from the PC to the board using Ethernet and TFTP protocol.

tftpboot Used to boot the Linux kernel from PC using Ethernet and TFTP protocol.

UM0478 The cross-building toolchain

23/31

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 4.0.0gcc C Cross-compiler for ARM

gcov Code coverage

binutils 2.16.1

ar Archiver

as Cross-assembler for ARM

gprof Profiling tool

ld Cross-linker for ARM

nm Lists symbols in object files

objcopy Copies a binary file.

objdump Displays information from object files.

ranlib Generates an index to speed access to archives.

readelfDisplays the information about the contents of ELF format files

strip Remove symbols and sections from files.

GNU Make 3.80 make Incremental build management

GDB 6.3.0 gdb Debugger

n.a. n.a. lddLists what shared libraries are used by given dynamically-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.

The cross-building toolchain UM0478

24/31

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

UM0478 Other tasks

25/31

7 Other tasks

7.1 Defining system RAM usageThe 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 FPGAThe 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

Other tasks UM0478

26/31

7.3 Flashing firmware by JTAGA 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 **********

UM0478 Other tasks

27/31

u-> for Upgrade UBoot codex-> 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 Nr0x00000000Programming XLoader to FlashXLoader Programmed successfullyPress 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 Nr0x00000001Erasing Sector Nr0x00000002Erasing Sector Nr0x00000003Programming U-Boot to FlashU-Boot Programmed successfullypress 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.

Default U-Boot environment UM0478

28/31

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'

UM0478 Default U-Boot environment

29/31

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

Revision history UM0478

30/31

8 Revision history

Table 8. Document revision history

Date Revision Changes

14-Nov-2007 1 Initial release.

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

UM0478

31/31

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve theright to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at anytime, 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 noliability 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 thisdocument 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 productsor services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of suchthird 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 IMPLIEDWARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIEDWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWSOF 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, ORSEVERE 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 voidany warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, anyliability 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

14121

Documents