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
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
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.
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.
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.
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.
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.
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).
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.
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.
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 . . .
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.
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.
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.
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. Instead of invoking all the individual translation phases by hand, it is possible (and recommended) to use the control program cctri:
cctri -g demo.c addone.asm -o demo.abs
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.
cctri -g demo.c addone.asm -o demo.abs -v0
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.
cctri -g demo.c addone.asm -o demo.abs -v0 -tmp
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.
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:
mktri
This command will build the example using the file makefile.
To see which commands are invoked by mktri without actually executing them, type:
mktri -n
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:
mktri clean
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
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:
TMPDIR=/tmp ; export TMPDIR
csh:
setenv TMPDIR /tmp
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.
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:
cctri -g demo.c addone.asm
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:
xfwtri demo.abs
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.
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,
astri text
only has the same effect as
astri text.asm
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
The assemblers have a built-in macro preprocessor. For a description of the possibilities offered by the macro preprocessor see the chapter Macro Operations.
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:
astri -l text.src
the listing file text.lst is created.
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.
This section contains a description of the use of UNIX scripts. The use of Makefiles is explained in the chapter Utilities.
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:
cctri -c ifile.asm -o outfile.obj
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:
cctri -c $1.asm -o $2.obj
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:
proj ifile outfile