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 2 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1 2.2 2.3 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 SDK contents summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Default configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3
Using the dev. board with pre-flashed software . . . . . . . . . . . . . . . . . . 11
3.1 3.2 Entering the Linux shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Entering the resident monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4
Installing the development package . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1 4.2 4.3 4.4 4.5 Host requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Installing the arm cross-build toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Installing SPEAr Plus Linux SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Setting up a TFTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Setting up a NFS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5
Flash memory and boot loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1 5.2 5.3 5.4 5.5 NOR Flash partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Updating XLoader on Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Updating U-Boot on Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 U-Boot commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Rebuilding the boot loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6 7
The cross-building toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Other tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1 7.2 7.3 Defining system RAM usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Enabling the FPGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 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. Table 2. Table 3. Table 4. Table 5. Table 6. Table 7. Table 8. Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 SDK contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 U-Boot - information commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 U-Boot - memory commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 U-Boot - environment commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 U-Boot - other commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Toolchain commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 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. 2. 3. 4. 5. 6. 7. 8. 9. STMicroelectronics, SPEAr Plus Linux SDK, getting started, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Linux SDK, kernel and device APIs, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Linux SDK, embedded root filesystem, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Linux SDK, Release Notes, SW Ver. 1.1 STMicroelectronics, SPEAr Plus Development Board, user manual STMicroelectronics, SPEAr Head600 Datasheet, http://www.st.com STMicroelectronics, SPEAr Plus600 Datasheet, http://www.st.com BusyBox, http://www.busybox.net 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
Explanation Application programming interface Address resolution protocol Compressed ROM file system Cyclic redundancy check Direct memory access Enhanced host controller interface Embedded linux development kit File allocation table GNU compiler collection General purpose I/O General public license (GNU) Hardware abstraction layer Hardware Inter-integrated circuit bus Internet protocol Inter-process communication Interrupt service routine Local area network Media access control Memory technology device Acronym API ARP CRAMFS CRC DMA EHCI ELDK FAT GCC GPIO GPL HAL HW I2C IP IPC ISR LAN MAC MTD
7/31
Introduction Table 1. Acronyms (continued)
Explanation Network file system Open host controller interface Operating system Random access memory Real-time clock Real time operating system Software development kit System on chip Structured processor enhanced architecture STMicroelectronics Software Trivial file transfer protocol Universal asynchronous receiver-transmitter Universal serial bus Vectored interrupt controller Watchdog timer
UM0478
Acronym NFS OHCI OS RAM RTC RTOS SDK SoC SPEAr ST SW TFTP UART USB VIC WDT
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
Type PC/Linux shell scripts PDF documents Notes User-friendly procedures for software rebuild on Linux PC host. See references [1,2,3,4,9,10]. Binary images corresponding to the runtime software as pre-flashed on the development boards. Open-source Linux Kernel, version 2.6.19.2 customized by ST for the SPEAr plus dev.board (SoC architecture and device drivers).
Contents General scripts Software documentation Pre-built Flash images
binar y image files source code configuration and build procedure
Linux Kernel
8/31
UM0478 Table 2. SDK contents (continued)
Type Notes
Introduction
Contents
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. Open source U-Boot, version 1.2.0, customized by ST for the SPEAr plus dev.board. ST-proprietary code, used as initial Flash bootloader before running U-Boot. 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.
Resident monitor and bootloader source code build procedure (U-Boot) XLoader source code build procedure
Tools
miscellaneous
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 suppor t for 8 MB serial NOR Flash, with 5 pre-defined partitions suppor t 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 suppor t 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. 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. From the terminal emulator, open a connection on the selected serial port. 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
2.
3. 4.
11/31
Using the dev. board with pre-flashed software 7 - OFF 8 - ON 5.
UM0478
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. At this point, Linux commands may be interactively issued. For the list of default supported commands and the overall filesystem structure see [3].
6.
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. 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. From the terminal emulator, open a connection on the selected serial port. 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 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. 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.
2.
3. 4.
5.
6.
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. 2. On the Linux PC, from a "bash" shell, enter in the arm-2007-01-21 directory (top level of the ELDK tree). 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 Wait until the installation is completed (several minutes). 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-linuxNote that, in order to make persistent this configuration, commands should be also put in a bash shell initialization file.
3. 4.
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 [uboot-1.2.0] Makefile [board] [common] ... [xloader] Makefile [ddr] [include] ... [tools] [jtag] erase_nor.cmm flasher.elf init_ram.cmm init_ram.elf
Installing the development package
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 Figure 1. NOR Flash default partitions
UM0478
xloader.uimg uboot.uimg
XLoader U-Boot Kernel
Sector 0 (Max 64 KB) Sectors 1-4 (Max 256 KB)
linux.uimg
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 1. 2. 3. 4.
Flash memory and boot loaders 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. Assure that the TFTP server is running on the PC and copy the xloader.uimg file to the default TFTP server directory. 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. 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. 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.
5.
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. 2. 3. Connect the target board to a PC using both a null-modem serial cable (the UART0 DB9 connector must be used). 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. 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. 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.
4.
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 1. 2. 3. 4.
UM0478
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. Assure that the TFTP server is running on the PC and copy the uboot.uimg file to the default TFTP server directory. 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. 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. 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.
5.
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. 2. 3. Connect the target board to a PC using both a null-modem serial cable (the UART0 DB9 connector must be used). 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. 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. 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.
4.
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 Table 3. U-Boot - information commands
Flash memory and boot loaders
Command bdinfo coninfo flinfo iminfo imls version
Description Reports information about the development board. Repor ts information about the console device. Reports information about the NOR Flash memory. 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). Lists all the partitions found in Flash (except for the root filesystem and the R/W area that have no standard U-Boot image header). 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
Description Sets a memory offset (or returns current offset). Compares memory areas. Copies memory areas. Infinite loop on address range. Reads memory location(s). Writes memory location(s) with auto-increment. Writes memory location(s). Writes memory location(s) with constant address.
Command base cmp cp loop md mm mw nm
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
Description Lists all defined environment variables. Executes the contents of an environment variable, handling it as a script (sequence of U-Boot commands). Saves the current contents of environment variables to NOR Flash. Assigns a new value to an environment variable.
Command printenv run saveenv setenv
Other frequently used commands are finally listed in the following table.
21/31
Flash memory and boot loaders Table 6. U-Boot - other commands
Description Starts the execution of a program loaded in memory. Erases a range of NOR Flash sectors.
UM0478
Command bootm erase imi loadb ping protect tftp tftpboot
Verifies the correctness of a flashed partition (except for the root filesystem 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 Kermit protocol. Tests Ethernet connection between the board and the PC. 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 protocol. 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.
Package GCC
Toolchain commands
Version 4.0.0 gcov ar as gprof ld nm Code coverage Archiver Cross-assembler for ARM Profiling tool Cross-linker for ARM Lists symbols in object files Copies a binary file. Displays information from object files. Generates an index to speed access to archives. Displays the information about the contents of ELF format files Remove symbols and sections from files. Incremental build management Debugger Lists what shared libraries are used by given dynamicallylinked executables. Creates CRAMFS binary image from file tree. Creates a binary image suitable for flashing with U-Boot. Tool gcc Description C Cross-compiler for ARM
binutils
2.16.1
objcopy objdump ranlib readelf strip
GNU Make GDB n.a. n.a. n.a.
3.80 6.3.0 n.a. n.a. n.a.
make gdb ldd mkcramfs mkimage
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
7.1
Other tasks
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=M parameter passed to the kernel by UBoot. 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 UBoot 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) Connect the Lauterbach TRACE-32 device to PC USB port. Connect the Lauterbach TRACE-32 JTAG device to the development board's JTAG connector (J8). Connect the PC to the board with a null modem cable. Launch and configure Hyperterminal as usual. Launch the TRACE-32 software application. Switch on the TRACE-32 JTAG device. Switch on the board. Using TRACE-32 menu "CPU > System Settings", open the setting dialog box then set CPU to "ARM926EJS" and "JTAG" to 5 MHz.
2. 3. 4. 5. 6. 7. 8. 9.
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 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 0x130 0 0" 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 0x0 0 0000 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 0x130 0 0" 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 0x0 0 0001 Erasing Sector Nr 0x0 0 0002 Erasing Sector Nr 0x0 0 0003 Programming U-Boot to Flash U-Boot Programmed successfully press s to stop r to run again
Other tasks
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 0x80 0 0 xloader.uimg;protect off 1:0;erase 1:0;cp.b 0x80 0 0 0xF80 0 00 ${filesize};protect on 1:0;imi 0xF80 0 00;saveenv' setenv flash_xloader_uart 'loadb 0x80 0 0;protect off 1:0;erase 1:0;cp.b 0x80 0 0 0xF80 0 00 ${filesize};protect on 1:0;imi 0xF80 0 00;saveenv' setenv flash_uboot_eth 'tftp 0x80 0 0 uboot.uimg;protect off 1:14;erase 1:1-4;cp.b 0x80 0 0 0xF8010000 ${filesize};protect on 1:1-4;imi 0xF8010000;saveenv' setenv flash_uboot_uart 'loadb 0x80 0 0;protect off 1:1-4;erase 1:1-4;cp.b 0x80 0 0 0xF8010000 ${filesize};protect on 1:1-4;imi 0xF8010000;saveenv' setenv flash_linux_eth 'tftp 0x80 0 0 linux${dbg}.uimg;protect off 1:5-47;erase 1:5-47;cp.b 0x80 0 0 0xF8050000 ${filesize};protect on 1:5-47;imi 0xF8050000' setenv flash_linux_uart 'loadb 0x80 0 0;protect off 1:5-47;erase 1:5-47;cp.b 0x80 0 0 0xF8050000 ${filesize};protect on 1:547;imi 0xF8050000' setenv flash_root_eth 'tftp 0x80 0 0 rootfs.cram;protect off 1:48126;erase 1:48-126;cp.b 0x80 0 0 0xF81d0000 ${filesize};protect on 1:48-126;cmp.b 0xF81d0000 0x80 0 0 ${filesize}' setenv flash_root_uart 'loadb 0x80 0 0;protect off 1:48-126;erase 1:48-126;cp.b 0x80 0 0 0xF81d0000 ${filesize};protect on 1:48126;cmp.b 0xF81d0000 0x80 0 0 ${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.
Date 14-Nov-2007 1-Sep-2008
Document revision history
Revision 1 2 Initial release. Minor package upgrade, mainly extending DDR clock to 266 MHz and supporting Gigabit Ethernet Changes
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
|
