1 OVERVIEW

This chapter contains the following sections:

Introduction
Basic Assembly, Linking and Locating of a TriCore Program
Using EDE
Using the Control Program
Using the Makefile
Environment Variables
Temporary Files
Debugging with CrossView Pro
File Extensions
Preprocessing
Assembler Listing
Errors and Warnings
Command Line Processing
UNIX Scripts

1.1 Introduction

TASKING offers a complete toolchain for the Siemens TriCore Family of processors and their derivatives. This manual uses 'TriCore' as a shorthand notation for the Siemens TriCore Family of processors and their derivatives.

The TriCore family cross-assembler produces load files running on the TriCore family. The assembler astri accepts programs written according to the assembly language specification for the TriCore. The assembler aspcp accepts programs written according to the assembly language specification for the Peripheral Control Processor (PCP).

Both assemblers generate relocatable object files in the IEEE-695 object format. This file format specifies code parts as well as symbol definition and symbolic debug information parts. The locator optionally produces absolute output files in Motorola S-file format or Intel Hex format. You can load these formats into a PROM programmer.

The TriCore toolchain provides an environment for modular program development and debugging. The TriCore toolchain contains the following programs:

cctri A handy control program which activates the other programs depending on its input files.

astri The TriCore assembler which produces a relocatable object file from a given TriCore assembly file.

aspcp The PCP assembler which produces a relocatable object file from a given PCP assembly file.

lktri A linker combining several objects and object libraries into one target load file.

lctri A locator that links a number of linker output files to one absolute load file. This program can also produce Motorola S-file format, and Intel Hex format.

artri An IEEE archiver. This is a librarian facility, which can be used to create and maintain object libraries.

prtri An IEEE object reader. This utility dumps the contents of IEEE files which have been created by a tool from the TASKING TriCore family toolchain.

The following diagram shows the structure of the package.

Figure 1-1: TriCore family development flow

1.2 An Example TriCore Program

This section illustrates the use of the TriCore toolchain by building an example application. As a part of the installation a directory examples\xvw (examples/xvw for UNIX) is created depending on the place where you installed the package on your system. This example directory contains, among others, the following source files:

This program has been written for illustrative purposes only.

1.2.1 Using EDE

EDE stands for "Embedded Development Environment" and is the Windows oriented Integrated Development Environment you can use with your TASKING toolchain to design and develop your application.

To use EDE on the demo program in the subdirectory xvw in the examples subdirectory of the TriCore product tree follow the steps below.

How to Start EDE

You can launch EDE by double-clicking on the EDE shortcut on your desktop.

The EDE screen provides you with a menu bar, a toolbar (command buttons) and one or more windows (for example, for source files), a status bar and numerous dialog boxes.

How to Select a Toolchain

EDE supports all the TASKING toolchains. When you first start EDE, the correct toolchain of the product you purchased is selected and displayed in the title of the EDE desktop window.

If you have more than one TASKING product installed and you want to change toolchains, do the following::

1. From the Project menu, select Select Toolchain...

The Select Toolchain dialog appears.

2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and click OK.

If no toolchains are present, use the Browse... or Scan Disk... button to search for a toolchain directory. Use the Browse... button if you know the installation directory of another TASKING product. Use the Scan Disk... button to search for all TASKING products present on a specific drive. Then return to step 2.

How to Open an Existing Project

Follow these steps to open an existing project:

1. From the Project menu, select Set Current ->.

2. Select the project file to open. For the xvw demo program select the file demo.pjt in the subdirectory xvw in the examples subdirectory of the TriCore product tree. If you have used the defaults, the file demo.pjt is in the directory c:\ctri\examples\xvw.

How to Load/Open Files

The next two steps are not needed for the demo program because the files addone.asm and demo.c are already open. To load the file you want to look at.

1. From the Project menu, select Load Files...

The Choose Project Files to Edit dialog appears.

2. Choose the file(s) you want to open by clicking on it. You can select multiple files by pressing the <Ctrl> or <Shift> key while you click on a file. With the <Ctrl> key you can make single selections and with the <Shift> key you can select everything from the first selected file to the file you click on. Then click OK.

This launches the file(s) so you can edit it (them).

Check the directory paths

1. From the Project menu, select Directories....

The Directories dialog appears.

2. Check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.

3. Click OK.

How to Build the Demo Application

The next step is to compile the file(s) together with its dependent files so you can debug the application.

Steps 1 and 2 are optional. Follow these steps if you want to specify additional build options such as to stop the build process on errors and to keep temporary files that are generated during a build.

1. From the Build menu, select Options...

The Build Options dialog appears.

2. Make your changes and press the OK button.

3. From the Build menu, select Scan All Dependencies.

4. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the ribbon bar.

If there are any unsaved files, EDE will ask you in a separate dialog if you want to save them before starting the build.

How to View the Results of a Build

Once the files have been processed you can inspect the generated messages.

1. In the Window menu select the Output menu item.

You can see which commands (and corresponding output captured) which have been executed by the build process in the Build tab:

TASKING program builder vx.y rz   Build nnn SN 00000000
Assembling "addone.asm"
Compiling "demo.c"
Assembling "demo.src"
Linking and locating to demo.out
Converting demo.out to demo.abs in IEEE-695 format
   .
   .
   .

How to Start the CrossView Pro Debugger

Once the files have been compiled, assembled, linked, located and formatted they can be executed by CrossView Pro.

To execute CrossView Pro:

1. Click on the Debug application button. The following button is the Debug application button which is located in the toolbar.

CrossView Pro is launched. CrossView Pro will automatically download the compiled file for debugging.

How to Load an Application

You must tell CrossView Pro which program you want to debug:

1. From the File menu, select Load Symbolic Debug Info...

The Load Symbolic Debug Info dialog box appears.

2. Click Load.

How to View and Execute an Application

To view your source while debugging, the Source Window must be open. To open this window:

1. From the View menu, select Source->Source lines.

The source window opens.

Before starting execution you have to reset the target system to its initial state. The program counter, stack pointer and any other registers must be set to their initial value. The easiest way to do this is:

2. From the Run menu, select Reset Target System.

To run your application step-by-step:

3. From the Run menu, select Animate.

The program demo.abs is now stepping through the high level language statements. Using the Accelerator bar or the menu bar you can set breakpoints, monitor data, display registers, simulate I/O and much more. See the CrossView Pro Debugger User's Guide for more information.

How to Start a New Project

When you first use EDE you need to setup a project space and add a new project:

1. From the File menu, select New Project Space...

The Create a New Project Space dialog appears.

2. Give your project space a name and then click OK.

The Project Properties dialog box appears.

3. Click on the Add new project to project space button.

The Add New Project to Project Space dialog appears.

4. Give your project a name and then click OK.

The Project Properties dialog box then appears for you to identify the files to be added.

5. Add all the files you want to be part of your project. Then press the OK button. To add files, use one of the 3 methods described below.

The new project is now open.

6. From the Project menu, select Load Files... to open the files you want on your EDE desktop.

EDE automatically creates a makefile for the project. EDE updates the makefile every time you modify your project.

1.2.2 Using the Control Program

1. Instead of invoking all the individual translation phases by hand, it is possible (and recommended) to use the control program cctri:

As you can see, you may enter multiple input files on the command line. Also, you may specify options and controls for the assembler, linker and locator together. The control program recognizes the options and controls and places them in the appropriate command when invoking the assembler, linker or locator. The control program is described in detail in Chapter 11, Utilities.

The -g option enables symbolic debug information.

The -o option specifies the name of the output file.

2. If you want to see how the control program calls the assembler, linker and locator, you can use the -v0 option or -v option. The -v0 option only displays the invocations without executing them. The -v option also executes them.

The control program shows the following command invocations without executing them (UNIX output):

demo.c:
+ ctri -e -g -o /tmp/cc2120b.src demo.c
+ astri /tmp/cc2120b.src -e -ghl -o demo.objaddone.asm:
+ astri addone.asm -e -ghl -o addone.obj
+ lktri -e demo.obj addone.obj -lc -lfpn -Ltc1 -o/tmp/cc2120c.out
+ lctri -e -M -dtri.dsc /tmp/cc2120c.out -odemo.abs

The -e option removes output files after errors occur. The -gsl option of the assembler specifies to pass HLL debug information and to generate local symbols debug information. The -lc and -lfpn option of the linker specify to link the appropriate C library and floating point library respectively. The -O option of the linker specifies the basename of the map file. The -d option of the locator specifies the name of the locator description file.

3. In step 2, the tools use temporary files for intermediate results. If you want to keep the intermediate files you can use the -tmp option. The following command makes this clear.

This command produces the following output:

demo.c:
+ /usr/src/dolphin/dvl/linux/ctri/bin/ctri -e -g -o demo.src demo.c
+ /usr/src/dolphin/dvl/linux/ctri/bin/astri demo.src -e -ghl -o demo.obj
addone.asm:
+ /usr/src/dolphin/dvl/linux/ctri/bin/astri addone.asm -e -ghl -o addone.obj
+ /usr/src/dolphin/dvl/linux/ctri/bin/lktri -e demo.obj addone.obj -lc -lfpn -L/usr/src/dolphin/dvl/linux/ctri/lib/tc1 -odemo.out
+ /usr/src/dolphin/dvl/linux/ctri/bin/lctri -e -M -dtri.dsc demo.out -odemo.abs

As you can see, if you use the -tmp option, the assembly source files and linker output file will be created in your current directory also. See also section Temporary Files

Assuming the program assembles successfully, the assembler produces the relocatable output modules, demo.obj and addone.obj.

Linking and locating the program to absolute addresses is done by two programs: the linker combines objects into a relocatable file with the extension .out. The locator binds the program to absolute addresses. The linker takes a.out as the default name of the output file. If this name is not suitable, you can specify another filename with the -O option.

Besides the output file produced by the linker, the locator can take a so-called description file as input. This file contains a description of the virtual and physical addresses of the program. The chapter Locator discusses the exact contents and layout of a description file.

The result of the locator command is the absolute output file demo.abs. The file demo.abs can be loaded into the CrossView Pro debugger.

1.2.3 Using the Makefile

The subdirectories in the examples directory each contain a makefile which can be processed by mktri. Also each subdirectory contains a readme.txt file with a description of how to build the example.

To build the demo example follow the steps below. This procedure is outlined as a guide for you to build your own executables for debugging.

1. Make the subdirectory xvw of the examples directory the current working directory.

This directory contains a makefile for building the demo example. It uses the default mktri rules.

2. Be sure that the directory of the binaries is present in the PATH environment variable.

3. Compile, assemble, link and locate the modules using one call to the program builder mktri:

This command will build the example using the file makefile.

To see which commands are invoked by mktri without actually executing them, type:

This command produces the following output:

TASKING TriCore program builder   vx.yrz Build nnn
Copyright 1996-year Altium BV     Serial# 00000000
cctri -g -w303 -c demo.c
cctri -c -o addone.obj addone.asm
cctri -o demo.abs demo.obj addone.obj

To remove all generated files type:

1.3 Environment Variables

This section contains an overview of the environment variables used by the TriCore family toolchain.

Environment
Variable
Description
ASPCPIINC Specifies an alternative path for include files for the assembler aspcp.
ASTRIINC Specifies an alternative path for include files for the assembler astri.
CTRIINC Specifies an alternative path for #include files for the C compiler.
CTRILIB Specifies a path to search for library files used by the linker lktri. See also the section Library Search Path in the chapter Linker.
CCTRIBIN When this variable is set, the control program, cctri, prepends the directory specified by this variable to the names of the tools invoked.
CCTRIOPT Specifies extra options and/or arguments to each invocation of cctri. The control program processes the arguments from this variable before the command line arguments.
LM_LICENSE_FILE Identifies the location of the license data file. Only needed for hosts that need the FLEXlm license manager. Not needed for MS-Windows.
PATH Specifies the search path for your executables.
TMPDIR Specifies an alternative directory where programs can create temporary files. Used by ctri, cctri, astri, lktri, lctri, artri. See also next section.

Table 1-1: Environment variables

1.4 Temporary Files

The assemblers, linker, locator and archiver may create temporary files. By default these files will be created in the current directory. If you want the tools to create temporary files in another directory you can enforce this by setting the environment variable TMPDIR.

UNIX:

Bourne shell, Korn shell:

csh:

Note that if you create your temporary files on a directory which is accessible via the network for other users as well, conflicts in the names chosen for the temporary files may arise. It is safer to create temporary files in a directory that is solely accessible to yourself. Of course this does not apply if you run the tools with several users on a multi-user system, such as UNIX. Conflicts may arise if two different computer systems use the same network directory for tools to create their temporary files.

1.5 Debugging with CrossView Pro

To facilitate debugging, you can include symbolic debug information in the load file. During compilation of a high-level-language program, symbolic debug information must be retained that serves as input for the symbolic debugger (-g option). The compiler passes symbolic debug information to the astri assembler by generating SYMB assembler directives in the assembly source file. The astri assembler translates the SYMB directives to be included in the symbolic debug part of an IEEE-695 object file.

The CrossView Pro debugger accepts files with the IEEE-695 format. This is the default output format of the locator. So, you can directly load the file generated by the locator into the CrossView Pro debugger.

The simplest way to build this program ready for debugging is:

The result of this command is (output of -v0 option):

demo.c:
+ ctri -e -g -o /tmp/cc28309b.src demo.c
+ astri -e -gsl -o demo.obj /tmp/cc28309b.src
addone.asm:
+ astri -e -gsl -o addone.obj addone.asm
+ lktri -e demo.obj addone.obj -lc -lfpn -odemo.out
+ lctri -e -M -odemo.abs -dtri.dsc demo.out

The control program is described in detail in Chapter 11 , Utilities.

You can start the text version of the debugger for debugging the absolute file demo.abs with:

For more information on the debugger, see the TriCore CrossView Pro Debugger User's Guide.

The debugger examples are installed in the subdirectory xvw of the examples directory.

1.6 File Extensions

The extension .src or .asm is used as input file for the TriCore assembler astri. The extension .pcp is used as input file for the PCP assembler aspcp. Files with the extension .src are output files of a C compiler. Actually, the assemblers accept files with any extension (or even no extension), but by adding the extension .asm (for astri) or .pcp (for aspcp) to assembler source files, you can distinguish them easily.

If you do not provide a filename extension the aspcp assembler will try:

1. the filename itself

2. the filename with .pcp extension

If you do not provide a filename extension the astri assembler will try:

1. the filename itself

2. the filename with .asm extension

3. the filename with .src extension

So,

only has the same effect as

if the file text is not present. In this case, both these commands assemble the file text.asm and create a relocatable object module text.obj.

For compatibility with future TASKING Cross-Software the following extensions are suggested:

.asm input assembly source file for astri
.src output from the C compiler ctri / input for astri
.pcp input assembly source file for aspcp
.c C source file, input for the C compiler ctri
.cc C++ source file, input for the C++ compiler cptri
.ic temporary C source file, generated by the C++ compiler cptri

.obj
relocatable object file generated by the assembler
.a object library files, output from artri
.out relocatable output files from lktri
.dsc description file, input for lctri and CrossView Pro debugger
.abs
absolute locator output, object file from lctri
.hex absolute Intel Hex file
.sre absolute Motorola S-record file
.elf absolute ELF/DWARF object file

.lst assembler list file
.cal C functions call tree
.lnl linker map file
.map locator map file

1.7 Preprocessing

The assemblers have a built-in macro preprocessor. For a description of the possibilities offered by the macro preprocessor see the chapter Macro Operations.

1.8 Assembler Listing

The assembler does not generate a listing file by default. You can generate a listing file with the -l option. (See also the -L option, for the listing options). As a result of the command:

the listing file text.lst is created.

1.9 Errors and Warnings

Any errors detected by the assembler are displayed in the listing file after the actual line containing the error is printed. If no listing file is produced, error messages are still displayed to indicate that the assembly process did not proceed normally.

Three classes of messages can be reported depending on the severity of the error. Warning messages (W) are the least severe messages. Warnings do not terminate assembly. Error messages (E) appear when a user error situation occurs. These errors do not terminate assembly immediate. If one or more of these errors occur, assembly stops at the end of the active pass. Fatal error messages (F) cause the assembler to terminate immediately. Fatal errors are usually due to user errors or memory errors.

1.10 Command Line Processing

This section contains a description of the use of UNIX scripts. The use of Makefiles is explained in the chapter Utilities.

1.10.1 UNIX Scripts

Scripts are a facility within UNIX whereby one or more commands can be executed from within a file.

Assume that the following sequence of calls is frequently used:

The files ifile and outfile may vary from one call to the next. To reduce the number of calls you can make a script, for example, proj. The file should contain:

On invocation $1 and $2 will be replaced by the first and second parameters after the script file name. Using the name mentioned above (proj) and after you have set the execute bits of proj (chmod +x proj) the call becomes:


Copyright © 2002 Altium BV