The LEON Bare-C Cross-compiler system (BCC) v1.0.7

Contents

Introduction

BCC is a cross-compiler for LEON2 and LEON3 processors. It is based one the GNU compiler tools and the Newlib standalone C-library. The cross-compiler system allows compilation of sequential (non-tasking) C and C++ applications. It supports both hard and soft floating-point operations, as well as both V7 and V8 multiply and divide instructions. BCC consists of the following packages:

Installation

BCC is provided as a bzipped tar-file. It should be unpacked in the /opt directory of the host:

cd /opt
tar xjf bcc-linux-1.0.7.tar.bz2
After installation, add /opt/sparc-elf/bin to the PATH variable. Do not add any other path, and in particular not /opt/sparc/elf/sparc-elf/bin!

Technical support

Technical support for BCC can be obtained from Gaisler Research by purchasing a technical support contract. Please contact sales@gaisler.com for details.

Compiling applications

General development flow

Compilation and debugging of applications is typically done in the following steps:
  1. Compile and link program with gcc
  2. Debug program on a simulator or remote target
  3. Create boot-prom for a standalone application
BCC supports ordinary sequential C programs. Compiling and linking is done in the same manner as with a host-based gcc, and will not be explained here.

Gcc options

All gcc options are described in detail in the gcc manual. Some useful options are:
 Ordinary sequential C programs can be compiled without any particular switches to the compiler driver:

sparc-rtems-gcc -msoft-float -g -O2 hello.c -o hello.exe

The default load address is start of RAM, i.e. 0x40000000 for LEON. Any load address can be specified through the -Ttext option (see gcc manual).

Newlib C-library

Newlib is a posix compatible C-library with full math support. However, no file or other I/O related functions will work, with the exception of I/O to stdin/stdout. Stdin/stdout are mapped on UART A, accessible via the usual stdio functions.

At startup of a program, the LEON timer scaler is programmed to generate a tick every microsecond. The function clock() will return the time expired in microseconds. The gettimeofday(), time() and times() can also be used to get the time. The standard C-library has been extended to include interrupt support. The function to be used as interrupt handler is assigned through the catch_interrupt call:

extern void *catch_interrupt(void func(int irq), int irq);

The catch_interrupt() will only associate a function to an interrupt, unmasking and enabling of interrupts must be performed by the applications by programming certain LEON registers. catch_interrupt() will return a pointer with the address of the previous interrupt handler. Once an interrupt is taken, further interrupts are disabled until the interrupt handler returns. See the file c-irq.c for an example on how to handle interrupts in a LEON3 system.

Floating-point considerations

If the targeted LEON processor has no floating-point hardware, then all applications must be compiled (and linked) with the -msoft-float option to enable floating-point emulation. When running the program on the TSIM simulator, the simulator should be started with the -nfp option (no floating-point) to disable the FPU.

LEON SPARC V8 instructions

Both LEON2 and LEON3 processors can be configured to implement the SPARC V8 multiply and divide instructions. The BCC compiler does by default not issue those instructions, but emulates them trough a library. To enable generation of mul/div instruction, use the -mv8 switch during both compilation and linking. The -mv8 switch improves performance on compute-intensive applications and floating-point emulation.

LEON2 and LEON3 also supports multiply and accumulate (MAC). The compiler will never issue those instructions, they have to be coded in assembly. Note that the BCC assembler and other utilities are based on a modified version of GNU binutils-2.13 that supports the LEON MAC instructions.

Memory organization

The resulting executables are in elf format and have three main segments; text, data and bss. The text segment is by default at address 0x40000000 for LEON2 and LEON3, followed immediately by the data and bss segments. The stack starts at top-of-ram and extends downwards. The area between the end of bss and the bottom of the stack is used for the heap.

Making LEON boot-proms

To make a boot-prom that will run from the prom on a standalone LEON2 or LEON3 target, use the sparc-elf-mkprom utility. It will create a compressed boot image that will load the application to the beginning of ram, initiate various LEON registers, and finally start the application. sparc-elf-mkprom will set all target dependent parameters, such as memory sizes, waitstates, baudrate, and system clock. The applications do not set these parameters themselves, and thus do not need to be re-linked for different board architectures.

The example below creates a boot-prom for a system with 1 Mbyte RAM, one waitstate during write, 3 waitstates for rom access, and 25 MHz system clock. For more details see the mkprom manual.

sparc-elf-mkprom -ramsz 1024 -ramwws 1 -romws 3 -freq 25 hello.exe -o hello.prom

Note that sparc-elf-mkprom creates ELF files. To create an SRECORD file for a prom programmer, use objcopy:

sparc-elf-objcopy -O srec hello.prom hello.srec

Creating applications that run in prom

 BCC supports applications that run in prom, but have data and stack in ram. A prom application is created in two steps:

1. Compile the application into on or more object file, but do not link:

sparc-elf-gcc -msoft-float -c -g -O2 hello.c

2. Create final prom image with mkprom, listing all object files on the command line:

sparc-elf-mkprom -freq 40 -rmw hello.o -msoft-float

A prom application has it code (.text segment) in prom, and data (.data & .bss) in ram. At start-up, the .data segment is copied from the prom to the ram, and the .bss segment is cleared. A prom application is linked to start from address 0x0. The data segment is by default linked to 0x40000000, but can be changed by giving the -Tdata=<address> option of gcc to mkprom. Note that if no FPU is present, the -msoft-float option must also be given to mkprom in this case since it is needed during the final linking. When debugging prom applications with GRMON or gdb, only hardware breakpoints (hbreak command) can be used.

Simple examples

Following example compiles the famous `hello world' program and creates a boot-prom in SRECORD format:

$ sparc-elf-gcc -g -O2 hello.c -o hello
$ mkprom3 hello -o hello.exe
 
MKPROM3 boot-prom builder v1.0

section: .text at 0x2000000, size 31040 bytes
section: .data at 0x2007940, size 1904 bytes
 
$ sparc-rtems-objcopy -O srec hello.exe hello.srec

Several example C programs can be found in src/examples.

Execution and debugging

GRMON simulator and debug monitor

To debug LEON applications on either a simulator or target hardware, use the GRMON debug monitor. The LEON applications can be executed on the built-in LEON simulator (LEON2 only at this time), or on target hardware using the processor debug interface (LEON2 and LEON3). In all cases, gdb can be connected to GRMON to perform source-level symbolic debugging.

Running on the simulator

To execute an application on the LEON2 simulator in GRMON, start GRMON with the -sim switch, use the load command to load the binary, and finally use the run command to execute the application:

$ grmon -sim

 GRMON - The LEON multi purpose monitor v1.0.7

 Copyright (C) 2004, Gaisler Research - all rights reserved.
 For latest updates, go to http://www.gaisler.com/
 Comments or bug-reports to grmon@gaisler.com


 LEON SPARC simulator backend, version 1.0.6 (professional version)

 Copyright (C) 2001, Gaisler Research - all rights reserved.
using 64-bit time
serial port A on stdin/stdout
allocated 4096 K RAM memory, in 1 bank(s)
allocated 2048 K ROM memory
icache: 1 * 4 kbytes, 16 bytes/line (4 kbytes total)
dcache: 1 * 4 kbytes, 16 bytes/line (4 kbytes total)

grmon[sim]> load hello.exe

section: .text at 0x40000000, size 35120 bytes
section: .data at 0x40008930, size 2080 bytes
section: .jcr at 0x400091b4, size 4 bytes
total size: 37204 bytes (in <1 sec)
read 110 symbols
entry point: 0x40000000

grmon[sim]> run

resuming at 0x40000000
Hello world!

Program exited normally.
grmon[sim]>

Debugging with GDB

To debug an application with gdb, start grmon with the -gdb option (or issue the gdb command inside grmon). Note that GRMON listens on port 2222 for a gdb connection. This can be changed to any port using the grmon -port switch at start-up.

$ grmon -sim -gdb

 GRMON - The LEON multi purpose monitor v1.0.7

 Copyright (C) 2004, Gaisler Research - all rights reserved.
 For latest updates, go to http://www.gaisler.com/
 Comments or bug-reports to grmon@gaisler.com


 LEON SPARC simulator backend, version 1.0.6 (professional version)

 Copyright (C) 2001, Gaisler Research - all rights reserved.
using 64-bit time
serial port A on stdin/stdout
allocated 4096 K RAM memory, in 1 bank(s)
allocated 2048 K ROM memory
icache: 1 * 4 kbytes, 16 bytes/line (4 kbytes total)
dcache: 1 * 4 kbytes, 16 bytes/line (4 kbytes total)
gdb interface: using port 2222

Then, start gdb in a separate shell, load the application to the target, add optinal breakpoints, and finally execute the application using the gdb run command:

$ sparc-elf-gdb hello.exe
GNU gdb 5.3
Copyright 2002 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=i686-pc-linux-gnu --target=sparc-tsim-elf"...
(gdb) tar extended-remote localhost:2222
Remote debugging using localhost:2222
0x00000000 in ?? ()
(gdb) load
Loading section .text, size 0x8930 lma 0x40000000
Loading section .data, size 0x820 lma 0x40008930
Loading section .jcr, size 0x4 lma 0x400091b4
Start address 0x40000000, load size 37204
Transfer rate: 297632 bits in <1 sec, 275 bytes/write.
(gdb) break main
Breakpoint 1 at 0x40001384: file hello.c, line 4.
(gdb) run
The program being debugged has been started already.
Start it from the beginning? (y or n) y
Starting program: /home/jiri/samples/hello.exe

Breakpoint 1, main () at hello.c:4
4               printf("Hello world!\n");
(gdb)


To re-execute the application, first re-load it to the target using the gdb load command and the issue run again.

Debugging on target hardware

To connect GRMON to a LEON2 system, start GRMON with -dsu. To connect to a LEON3/GRLIB system, start GRMON with -grlib. In both cases, GRMON will connect to the processor debug support unit (DSU) using a serial port. See the GRMON manual for how to connect via PCI or ethernet. Once connected, the application can be downloaded and executed using the same procedure as when the simulator is used:

$ grmon -grlib -u

 GRMON - The LEON multi purpose monitor v1.0.7

 Copyright (C) 2004, Gaisler Research - all rights reserved.
 For latest updates, go to http://www.gaisler.com/
 Comments or bug-reports to grmon@gaisler.com


 GRLIB DSU Monitor backend 1.0.1  (professional version)
 using port /dev/ttyS0 @ 115200 baud

 initialising .........

 Component                            Vendor
 Leon3 SPARC V8 Processor             Gaisler Research
 AHB Debug UART                       Gaisler Research
 Ethernet DSU interface               Gaisler Research
 LEON2 Memory Controller              European Space Agency
 AHB/APB Bridge                       Gaisler Research
 Leon3 Debug Support Unit             Gaisler Research
 Generic APB UART                     Gaisler Research
 Multi-processor Interrupt Ctrl       Gaisler Research
 Modular Timer Unit                   Gaisler Research

 Use command 'info sys' to print a detailed report of attached cores

grmon[grlib]> load hello.exe
section: .text at 0x40000000, size 35120 bytes
section: .data at 0x40008930, size 2080 bytes
section: .jcr at 0x400091b4, size 4 bytes
total size: 37204 bytes (99.4 kbit/s)
read 110 symbols
entry point: 0x40000000

grmon[grlib]> run
Hello world!

Program exited normally.
grmon[grlib]>

Connecting GDB to GRMON when attached to a real LEON target is done in the same way as when using the simulator.

Using the DDD graphical front-end to GDB

DDD is a graphical front-end to gdb, and can be used regardless of target. DDD must be started with the --debugger switch to select the sparc debugger, rather than the native gdb:

    ddd --debugger sparc-rtems-gdb --attach-window

Note that DDD is not provided with BCC, and must be downloaded and installed separately. See the DDD home page for details.

Building BCC from sources

Libio low-level routines

The Libio low-level routines handles I/O related functions such as UART communication and clock handling. The routines are provided in full source code under GNU GPL in directory src/libio. The routines can be built and re-installed by doing 'make install' in the libio directory.

Mkprom prom builder

The sources to sparc-elf-mkprom are provided in src/mkprom. The prom builder can be built and re-installed by doing 'make install' in the mkprom directory.

Gcc, binutils and Newlib

It is fairly straight-forward to build BCC from sources, although it requires some experience with building GNU tools in general. Building the complete tool-chain is done in 4 steps:

1. Binutils

Download and install the GNU binutils. Configure and build with: --target=sparc-elf --prefix=/opt/sparc-elf

2. Gcc + Newlib

Download and unpack gcc-3.2.3  and newlib-1.12. In the gcc-3.2.3 directory, create a link to newlib-1.12/newlib. Configure with --target=sparc-elf --prefix=/opt/sparc-elf --enable-languages=c,c++ . Build as usual.

3. Libio

Compile and install libio by doing a 'make install' in the src/libio directory

4. Mkprom

Compile and install mkprom by doing a 'make install' in the src/mkprom directory.


Test the final compiler by compiling a test application and run it on the simulator.



Jiri Gaisler.
Copyright 2004 Gaisler Research. Comments or bug reports to jiri@gaisler.com.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.