11 UTILITIES

This chapter contains the following sections:

Overview
artri
cctri
mktri
prtri
Preparing the Demo Files
Displaying Parts of an Object File
Option -h, display general file info
Option -s, display section info
Option -c, display call graph
Option -e, display external part
Option -g, display global type information
Option -d, display debug information
Option -i, display the section images
View an Object at Lower Level
Object Layers
The Level Option -ln
The Verbose Option -vn

11.1 Overview

The following utilities are supplied with the Cross-Assembler for the TriCore processor family which can be useful at various stages during program development.

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

cctri A control program for the TriCore tool chain.

mktri A utility program to maintain, update, and reconstruct groups of programs.

prtri An IEEE object reader that views the contents of files which have been created by a tool from the TASKING TriCore toolchain.

When you use a UNIX shell (Bourne shell, C-shell), arguments containing special characters (such as '( )' and '?') must be enclosed with "" or escaped. The -? option (in the C-shell) becomes: "-?" or -\?.

The utilities are explained on the following pages.

11.2 artri

Name

artri IEEE archiver and library maintainer

Synopsis

artri key_option [option]... library [object_file]...
artri -V
artri
-? ( UNIX C-shell : "-?" or -\? )

Description

With artri you can combine separate object modules in a library file. The linker optionally includes modules from a library when a specific module resolves an external symbol definition in one of the modules that has been read before. The library maintainer artri is a program to build library files and it offers the possibility to replace, extract or remove modules from an existing library.

key_option one of the main options indicating the action artri has to take. Key options may appear in any order, at any place.

option optional sub-options as explained on the next pages.

library is the library file.

object_file is an object module to be added, extracted, replaced or removed from the library.

Options

You may specify options with or without a leading '-'. Options may occur in random order. You may also combine options. So -xv is allowed. -V and -? however, must be the only option on the command line.

Key options:

-d Delete the named object modules from the library.

-m Move the named object modules to the end of the library, or to another position as specified by one of the positioning options.

-p Print the named object modules in the library on standard output.

The object is in binary format. The -p option is normally used with a redirection:

-r Replace the named object modules in the library if they exist. If they are not in the library, add them. If no names are given, only those object modules are replaced for which a file with the same name is found in the current directory. New modules are placed at the end.

-t Print a table of contents of the library. If no names are given, all object modules in the library are printed. If names are given, only those object modules are tabled.

-x Extract the named object modules from the library. If no names are given, all modules are extracted from the library. In neither case does x alter the library.

Other options:

-? Display an explanation of options at stdout.

-V Display version information at stderr.

-a posname
Append or move new object modules after existing module posname. This option can only be used in combination with the m or r option.

-b posname
Insert or move new object modules before existing module posname. This option can only be used in combination with the m or r option.

-c Create the library file without notification if the library does not exist.

-f file Read options from file file. '-' means stdin. You need to provide the EOF code to close stdin (usually Ctrl-Z or Ctrl-D on UNIX).

-o Reset the last-modified date to the date recorded in the library. It can only be used in combination with the x option.

-s Print a list of symbols. This option must be combined with -t.

-s1 Print a list of symbols. Each symbol is preceded by the library name and the name of the object file. This option must be combined with -t.

-u Replace only those object modules with the last-modified date later than the library file. It can only be used in combination with the r option.

-v Verbose. Under the verbose option, artri gives a module- by-module description of the making of a new library file from the old library and the constituent modules. It can only be used in combination with the d, m, r, or x option.

-wn Set warning level n.

Examples

1. Create library clib.a consisting of the modules cstart.obj, and demo.obj :

artri cr clib.a cstart.obj demo.obj

2. Extract all modules form library clib.a :

artri x clib.a

3. Print a list of symbols from library clib.a :

artri ts clib.a
cstart.obj
   symbols:
        _start
        _copytable
demo.obj
   symbols:
        _entry

4. Print a list of symbols from library clib.a in a different form:

artri ts1 clib.a
clib.a:cstart.obj:_start
clib.a:cstart.obj:_copytable
clib.a:demo.obj:_entry

5. Delete module demo.obj from library clib.lib :

artri d clib.a demo.obj

11.3 cctri

Name

cctri control program for the TriCore tool chain

Synopsis

cctri [ [option]... [control] ... [file]... ]...
cctri -V
cctri
-? ( UNIX C-shell : "-?" or -\? )

Description

The control program cctri facilitates the invocation of the various components of the TriCore family tool chain from a single command line. The control program accepts source files and options on the command line in random order.

Options are preceded by a '-' (minus sign). The input file can have one of the extensions explained below.

The control program recognizes the following argument types:

Normally, a control program tries to compile and assemble all source files to object files, followed by a link and locate phase which produces an absolute output file. There are however, options to suppress the assembler, linker or locator stage. The control program produces unique filenames for intermediate steps in the compilation process, which are removed afterwards.

Options

-? Display a short explanation of options at stdout.

-V The copyright header containing the version number is displayed, after which the control program terminates.

-Waarg
-Wcarg
-Wcparg
-Wplarg
-Wlkarg

-Wlcarg With these options you can pass a command line argument directly to the assembler (-Wa), C compiler (-Wc), C++ compiler (-Wcp), C++ pre-linker (-Wpl), linker (-Wlk) or locator (-Wlc). These options may be used to pass some options that are not recognized by the control program, to the appropriate program. The argument may be either directly appended to the option, or follow the option as a separate argument of the control program.

-c++ Specify that files with the extension .c are considered to be C++ files instead of C files. So, the C++ compiler is called prior to the C compiler. This option also forces the linker to link C++ libraries.

-cc
-cs
-c
-cl
-cm

-cp Normally the control program invokes all stages to build an absolute file from the given input files. With these options it is possible to stop after one of the stages or to skip the linker stage.
With the -cc option the control program stops after compilation of the C++ files and retains the resulting .c files. With the -cs option the control program stops after the C compiler or macro preprocessor, with as output file the assembly source file (.src).
With -c option the control program stops after the assembler, with as output an object file (.obj).
With the -cl option the control program stops after the link stage, with as output a linker object file (.lno).
With the -cm option the control program always also invokes the C++ muncher.
With the -cp option the control program always also invokes the C++ pre-linker.

-f file Read command line arguments from file. The filename "-" may be used to denote standard input. To get around the limits on the size of the command line, it is possible to use command files. These command files contain the options that could not be part of the real command line. Command files can also be generated on the fly, for example by the make utility.

1. It is possible to have multiple arguments on the same line in the command file.

2. To include whitespace in the argument, surround the argument with either single or double quotes.

3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:

a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.

b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.

Example:

or

or

4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.

Example:

5. It is possible to nest command line files up to 25 levels.

-elf
-ieee
-ihex
-srec

-tiof With these options you can specify the locator output format of the absolute file. The output file can be an ELF/DWARF1.1 (.elf), IEEE-695 file (.abs), Intel Hex file (.hex), Motorola S-record file (.sre) or TIOF-695 file (.abs). The default output is IEEE-695 (.abs).

-fptrap Use floating point library with trap handling (libfpt.a). Without this option a floating point library is selected which uses no trapping.

-nolib With this option the control program does not supply the standard libraries to the linker. Normally the control program supplies the default C and run-time libraries to the linker. Which libraries are needed is derived from the compiler options.

-o file Normally, this option is passed to the locator to specify the output file name. When you use the -cl option to suppress the locating phase, the -o option is passed to the linker. When you use the -c option to suppress the linking phase, the -o option is passed to the assembler, provided that only one source file is specified. When you use the -cs option to suppress the assembly phase, the -o option is passed to the compiler. The argument may be either directly appended to the option, or follow the option as a separate argument of the control program.

-tmp With this option the control program creates intermediate files in the current directory. They are not removed automatically. Normally, the control program generates temporary files for intermediate translation results, such as compiler generated assembly files, object files and the linker output file. If the next phase in the translation process completes successfully, these intermediate files will be removed.

-v When you use the -v option, the invocations of the individual programs are displayed on standard output, preceded by a '+' character.

-v0 This option has the same effect as the -v option, with the exception that only the invocations are displayed, but the programs are not started.

-wc++ Enable C and assembler warnings for C++ files. The assembler and C compiler may generate warnings on C output of the C++ compiler. By default these warnings are suppressed.

Environment Variables used by cctri

The control program uses the following environment variables:

TMPDIR This variable may be used to specify a directory, which the control programs should use to create temporary files. When this environment variable is not set, temporary files are created in the directory "/tmp" on UNIX systems, and in the current directory on other operating systems.

CCTRIOPT This environment variable may be used to pass extra options and/or arguments to each invocation of the control program. The control program processes the arguments from this variable before the command line arguments.

CCTRIBIN When this variable is set, the control program prepends the directory specified by this variable to the names of the tools invoked.

11.4 mktri

Name

mktri maintain, update, and reconstruct groups of programs

Syntax

mktri [option]... [target]... [macro=value]...
mktri -V
mktri
-? ( UNIX C-shell: "-?" or -\? )

Description

mktri takes a file of dependencies (a 'makefile') and decides what commands have to be executed to bring the files up-to-date. These commands are either executed directly from mktri or written to the standard output without executing them.

If no target is specified on the command line, mktri uses the first target defined in the first makefile.

Long filenames are supported when they are surrounded by double quotes ("). It is also allowed to use spaces in directory names and file names.

Options

-? Show invocation syntax.

-D Display the text of the makefiles as read in.

-DD Display the text of the makefiles and 'mktri.mk'.

-G dirname
Change to the directory specified with dirname before reading a makefile. This makes it possible to build an application in another directory than the current working directory.

-K Do not remove temporary files.

-S Undo the effect of the -k option. Stop processing when a non-zero exit status is returned by a command.

-V Display version information at stderr.

-W target Execute as if this target has a modification time of "right now". This is the "What If" option.

-d Display the reasons why mktri chooses to rebuild a target. All dependencies which are newer are displayed.

-dd Display the dependency checks in more detail. Dependencies which are older are displayed as well as newer.

-e Let environment variables override macro definitions from makefiles. Normally, makefile macros override environment variables. Command line macro definitions always override both environment variables and makefile macros definitions.

-f file Use the specified file instead of 'makefile'. A - as the makefile argument denotes the standard input.

-i Ignore error codes returned by commands. This is equivalent to the special target .IGNORE:.

-k When a nonzero error status is returned by a command, abandon work on the current target, but continue with other branches that do not depend on this target.

-m file Read command line information from file. If file is a '-', the information is read from standard input.

-n Perform a dry run. Print commands, but do not execute them. Even lines beginning with an @ are printed. However, if a command line is an invocation of mktri, that line is always executed.

-q Question mode. mktri returns a zero or non-zero status code, depending on whether or not the target file is up to date.

-r Do not read in the default file 'mktri.mk'.

-s Silent mode. Do not print command lines before executing them. This is equivalent to the special target .SILENT:.

-t Touch the target files, bringing them up to date, rather than performing the rules to reconstruct them.

-w Redirect warnings and errors to standard output. Without, mktri and the commands it executes use standard error for this purpose.

macro=value
Macro definition. This definition remains fixed for the mktri invocation. It overrides any regular definitions for the specified macro within the makefiles and from the environment. It is inherited by subordinate mktri's but act as an environment variable for these. That is, depending on the -e setting, it may be overridden by a makefile definition.

Usage

Makefiles

The first makefile read is 'mktri.mk', which is looked for at the following places (in this order):

- in the current working directory

- in the directory pointed to by the HOME environment variable

- in the etc directory relative to the directory where mktri is located

Example (PC):

Example (UNIX):

It typically contains predefined macros and implicit rules.

The default name of the makefile is 'makefile' in the current directory. If this file is not found on a UNIX system, the file 'Makefile' is then used as the default. Alternate makefiles can be specified using one or more -f options on the command line. Multiple -f options act as if all the makefiles were concatenated in a left-to-right order.

The makefile(s) may contain a mixture of comment lines, macro definitions, include lines, and target lines. Lines may be continued across input lines by escaping the NEWLINE with a backslash (\). If a line must end with a backslash then an empty macro should be appended. Anything after a "#" is considered to be a comment, and is stripped from the line, including spaces immediately before the "#". If the "#" is inside a quoted string, it is not treated as a comment. Completely blank lines are ignored.

An include line is used to include the text of another makefile. It consists of the word "include" left justified, followed by spaces, and followed by the name of the file that is to be included at this line. Macros in the name of the included file are expanded before the file is included. Include files may be nested.

An export line is used for exporting a macro definition to the environment of any command executed by mktri. Such a line starts with the word "export", followed by one or more spaces and the name of the macro to be exported. Macros are exported at the moment an export line is read. This implies that references to forward macro definitions are equivalent to undefined macros.

Conditional Processing

Lines containing ifdef, ifndef, else or endif are used for conditional processing of the makefile. They are used in the following way:

The if-lines and else-lines may contain any number of lines or text of any kind, even other ifdef, ifndef, else and endif lines, or no lines at all. The else line may be omitted, along with the else-lines following it.

First the macroname after the if command is checked for definition. If the macro is defined then the if-lines are interpreted and the else-lines are discarded (if present). Otherwise the if-lines are discarded; and if there is an else line, the else-lines are interpreted; but if there is no else line, then no lines are interpreted.

When using the ifndef line instead of ifdef, the macro is tested for not being defined. These conditional lines can be nested up to 6 levels deep.

Macros

Macros have the form `WORD = text and more text'. The WORD need not be uppercase, but this is an accepted standard. Spaces around the equal sign are not significant. Later lines which contain $(WORD) or ${WORD} will have this replaced by `text and more text'. If the macro name is a single character, the parentheses are optional. Note that the expansion is done recursively, so the body of a macro may contain other macro invocations. The right side of a macro definition is expanded when the macro is actually used, not at the point of definition.

Example:

`$(FOOD)' becomes `meat and/or vegetables and water' and the environment variable FOOD is set accordingly by the export line. However, when a macro definition contains a direct reference to the macro being defined then those instances are expanded at the point of definition. This is the only case when the right side of a macro definition is (partially) expanded. For example, the line

after the export line affects `$(FOOD)' just as the line

would do. However, the environment variable FOOD will only be updated when it is exported again.

You are advised not to use the double quotes (") for long filename support in macros, otherwise this might result in a concatination of two macros with double quotes (") in between.

Special Macros

MAKE This normally has the value mktri. Any line which invokes MAKE temporarily overrides the -n option, just for the duration of the one line. This allows nested invocations of MAKE to be tested with the -n option.

MAKEFLAGS
This macro has the set of options provided to mktri as its value. If this is set as an environment variable, the set of options is processed before any command line options. This macro may be explicitly passed to nested mktri's, but it is also available to these invocations as an environment variable. The -f and -d flags are not recorded in this macro.

PRODDIR This macro expands the name of the directory where mktri is installed without the last path component. The resulting directory name will be the root directory of the installed TriCore package, unless mktri is installed somewhere else. This macro can be used to refer to files belonging to the product, for example a library source file.

Example:

When mktri is installed in the directory /ctri/bin this line expands to:

SHELLCMD
This contains the default list of commands which are local to the SHELL. If a rule is an invocation of one of these commands, a SHELL is automatically spawned to handle it.

TMP_CCPROG
This macro contains the name of the control program. If this macro and the TMP_CCOPT macro are set and the command line argument list for the control program exceeds 127 characters then mktri will create a temporary file filled with the command line arguments. mktri will call the control program with the temporary file as command input file. This macro is only known by the PC version of mktri.

TMP_CCOPT
This macro contains the option for the control program which tells the control program to read a file as command arguments. This macro is only known by the PC version of mktri.

Example:

$ This macro translates to a dollar sign. Thus you can use "$$" in the makefile to represent a single "$".

There are several dynamically maintained macros that are useful as abbreviations within rules. It is best not to define them explicitly.

$* The basename of the current target.

$< The name of the current dependency file.

$@ The name of the current target.

$? The names of dependents which are younger than the target.

$! The names of all dependents.

The $< and $* macros are normally used for implicit rules. They may be unreliable when used within explicit target command lines. All macros may be suffixed with F to specify the Filename components (e.g. ${*F}, ${@F}). Likewise, the macros $*, $< and $@ may be suffixed by D to specify the directory component.

The result of the $* macro is always without double quotes ("), regardless of the original target having double quotes (") around it or not.
The result of using the suffix F (Filename component) or D (Directory component) is also always without double quotes ("), regardless of the original contents having double quotes (") around it or not.

Functions

A function not only expands but also performs a certain operation. Functions syntactically look like macros but have embedded spaces in the macro name, e.g. '$(match arg1 arg2 arg3 )'. All functions are built-in and currently there are five of them: match, separate, protect, exist and nexist.

The match function yields all arguments which match a certain suffix:

will yield

The separate function concatenates its arguments using the first argument as the separator. If the first argument is enclosed in double quotes then '\n' is interpreted as a newline character, '\t' is interpreted as a tab, '\ooo' is interpreted as an octal value (where, ooo is one to three octal digits), and spaces are taken literally. For example:

will result in

Function arguments may be macros or functions themselves. So,

will yield all object files the current target depends on, separated by a newline string.

The protect function adds one level of quoting. This function has one argument which can contain white space. If the argument contains any white space, single quotes, double quotes, or backslashes, it is enclosed in double quotes. In addition, any double quote or backslash is escaped with a backslash.

Example:

will yield

The exist function expands to its second argument if the first argument is an existing file or directory.

Example:

When the file test.c exists it will yield:

When the file test.c does not exist nothing is expanded.

The nexist function is the opposite of the exist function. It expands to its second argument if the first argument is not an existing file or directory.

Example:

Targets

A target entry in the makefile has the following format:

Any line which does not have leading white space (other than macro definitions) is a 'target' line. Target lines consist of one or more filenames (or macros which expand into same) called targets, followed by a colon (:). The ':' is followed by a list of dependent files. The dependency list may be terminated with a semicolon (;) which may be followed by a rule or shell command.

Special allowance is made on MS-DOS for the colons which are needed to specify files on other drives, so for example, the following will work as intended:

If a target is named in more than one target line, the dependencies are added to form the target's complete dependency list.

The dependents are the ones from which a target is constructed. They in turn may be targets of other dependents. In general, for a particular target file, each of its dependent files is 'made', to make sure that each is up to date with respect to it's dependents.

The modification time of the target is compared to the modification times of each dependent file. If the target is older, one or more of the dependents have changed, so the target must be constructed. Of course, this checking is done recursively, so that all dependents of dependents of dependents of ... are up-to-date.

To reconstruct a target, mktri expands macros and functions, strips off initial white space, and either executes the rules directly, or passes each to a shell or COMMAND.COM for execution.

For target lines, macros and functions are expanded on input. All other lines have expansion delayed until absolutely required (i.e. macros and functions in rules are dynamic).

Special Targets

.DEFAULT:
The rule for this target is used to process a target when there is no other entry for it, and no implicit rule for building it. mktri ignores all dependencies for this target.

.DONE: This target and its dependencies are processed after all other targets are built.

.IGNORE: Non-zero error codes returned from commands are ignored. Encountering this in a makefile is the same as specifying -i on the command line.

.INIT: This target and its dependencies are processed before any other targets are processed.

.SILENT: Commands are not echoed before executing them. Encountering this in a makefile is the same as specifying -s on the command line.

.SUFFIXES:
The suffixes list for selecting implicit rules. Specifying this target with dependents adds these to the end of the suffixes list. Specifying it with no dependents clears the list.

.PRECIOUS:
Dependency files mentioned for this target are not removed. Normally, mktri removes a target file if a command in its construction rule returned an error or when target construction is interrupted.

Rules

A line in a makefile that starts with a TAB or SPACE is a shell line or rule. This line is associated with the most recently preceding dependency line. A sequence of these may be associated with a single dependency line. When a target is out of date with respect to a dependent, the sequence of commands is executed. Shell lines may have any combination of the following characters to the left of the command:

@ will not echo the command line, except if -n is used.

- mktri will ignore the exit code of the command, i.e. the ERRORLEVEL of MS-DOS. Without this, mktri terminates when a non-zero exit code is returned.

+ mktri will use a shell or COMMAND.COM to execute the command.

If the '+' is not attached to a shell line, but the command is a DOS command or if redirection is used (<, |, >), the shell line is passed to COMMAND.COM anyway. For UNIX, redirection, backquote (`) parentheses and variables force the use of a shell.

You can force mktri to execute multiple command lines in one shell environment. This is accomplished with the token combination ';\'.

Example:

The ';' must always directly be followed by the '\' token. Whitespace is not removed when it is at the end of the previous command line or when it is in front of the next command line. The use of the ';' as an operator for a command (like a semicolon ';' separated list with each item on one line) and the '\' as a layout tool is not supported, unless they are separated with whitespace.

mktri can generate inline temporary files. If a line contains '<<WORD' then all subsequent lines up to a line starting with WORD, are placed in a temporary file. Next, '<<WORD' is replaced with the name of the temporary file.

No whitespace is allowed between '<<' and 'WORD'.

Example:

The three lines between the tags (EOF) are written to a temporary file (e.g. "\tmp\mk2"), and the command line is rewritten as "lktri -o $@ -f \tmp\mk2".

Implicit Rules

Implicit rules are intimately tied to the .SUFFIXES: special target. Each entry in the .SUFFIXES: list defines an extension to a filename which may be used to build another file. The implicit rules then define how to actually build one file from another. These files are related, in that they must share a common basename, but have different extensions.

If a file that is being made does not have an explicit target line, an implicit rule is looked for. Each entry in the .SUFFIXES: list is combined with the extension of the target, to get the name of an implicit target. If this target exists, it gives the rules used to transform a file with the dependent extension to the target file. Any dependents of the implicit target are ignored.

If a file that is being made has an explicit target, but no rules, a similar search is made for implicit rules. Each entry in the .SUFFIXES: list is combined with the extension of the target, to get the name of an implicit target. If such a target exists, then the list of dependents is searched for a file with the correct extension, and the implicit rules are invoked to create the target.

Examples

This makefile says that prog.out depends on two files prog.obj and sub.obj, and that they in turn depend on their corresponding source files (prog.c and sub.c) along with the common file inc.h.

LIB = -ls

prog.out:  prog.obj sub.obj
     lktri prog.obj sub.obj $(LIB) -o prog.out

prog.obj:  prog.c inc.h
     ctri  prog.c
     astri prog.src

sub.obj:   sub.c inc.h
     ctri  sub.c
     astri sub.src

The following makefile uses implicit rules (from mktri.mk) to perform the same job.

LDFLAGS = -ls
prog.out: prog.obj sub.obj
prog.obj: prog.c inc.h
sub.obj:  sub.c inc.h

Files

makefile Description of dependencies and rules.
Makefile Alternative to makefile, for UNIX.
mktri.mk Default dependencies and rules.

Diagnostics

mktri returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0.

11.5 prtri

Name

prtri IEEE object reader
Displays the contents of a relocatable object file or an absolute file

Synopsis

prtri [option]... file
prtri -V
prtri
-? ( UNIX  C-shell: "-?" or -\? )

Description

prtri gives you a high level view of an object file which has been created by a tool from the TASKING TriCore toolchain. Note that prtri is not a disassembler.

Options

Options start with a '-' sign and can be combined after a single '-'. There are options to print a specific part of an object file. For example, with option -h you can display the header part, the environment part and the AD/extension part as a whole. These parts are small, and you cannot display these parts separately. If you do not specify a part, the default is -hscegd0i0 (all parts, the debug part and the image part displayed as a table of contents).

Furthermore, there are some additional options by which you can control the output.

Input Control Option

-ffile Read command line information from file. If file is a '-', the information is read from standard input.

1. It is possible to have multiple arguments on the same line in the command file.

2. To include whitespace in the argument, surround the argument with either single or double quotes.

3. If single or double quotes are to be used inside a quoted argument, we have to go by the following rules:

a. If the embedded quotes are only single or double quotes, use the opposite quote around the argument. Thus, if a argument should contain a double quote, surround the argument with single quotes.

b. If both types of quotes are used, we have to split the argument in such a way that each embedded quote is surrounded by the opposite type of quote.

Example:

or

or

4. Some operating systems impose limits on the length of lines within a text file. To circumvent this limitation it is possible to use continuation lines. These lines end with a backslash and newline. In a quoted argument, continuation lines will be appended without stripping any whitespace on the next line. For non-quoted arguments, all whitespace on the next line will be stripped.

Example:

5. It is possible to nest command line files up to 25 levels.

Output Control Options

-H or -? Display an explanation of options at stdout.

-V Display version information at stderr.

-Wn Set output width to n columns. Default 128, minimum 78.

-ln Level control, see paragraph 11.5.3.

-ofile Name of the output file, default stdout.

-v Print the selected parts in a verbose form.

-vn Print level n verbose, see paragraph 11.5.3.

-wn Suppress messages above warning level n.

Display Options

-c Print call graphs.

-d Print all debug info except for the global types.

-d0 Print table of contents for the debug part.

-dn Print debug info from file number n.

-e Print variables with external scope.

-e1 Print variables with external scope and precede symbol name with name of the object file.

-g Print global types.

-h Print general file info.

-i Print all section images.

-i0 Print table of contents for the image part.

-in Print image of section n.

-s Print section info.

11.5.1 Preparing the Demo Files

There are three files which are used in this chapter to show how you can use prtri. These files are:

If you want to try the examples yourself, prepare these files by copying the calc example files to a working directory. Be sure that the TriCore tools can be found via a search path. Make the files with the following command:

11.5.2 Displaying Parts of an Object File

11.5.2.1 Option -h, display general file info

The -h option gives you general information of the file. The invocation:

Gives the following information:

This output speaks for itself. You may combine the -h switch with the verbose option:

The output is extended with more general information of less importance:

The table gives you the file offsets and the length of the main object parts.

11.5.2.2 Option -s, display section info

With the -s option, you can obtain the section information from an object module. The section contents can be obtained with the -i option, see 11.5.2.7.

Note that the section information is not available any more in a located file. Once located, the separate sections are combined to new clusters. For an absolute file 'prtri -s' will give the cluster information:

The locate map shows you which section is located in which cluster. Of course, you can also use the verbose option to see all section information available:

Section Size Address Align PgSize Mau Attributes
----------------------------------------------------------------------------------------
.startup_vector 0x000002 0x000000 0x001 - - ReadOnly Execute ZeroPage Space 1
Abs Separate
.startup 0x000063 - 0x001 - - ReadOnly Execute ZeroPage Space 1
Cumulate
.watchdog_vector 0x000002 0x000004 0x001 - - ReadOnly Execute ZeroPage Space 1
Abs Separate
.watchdog 0x000001 - 0x001 - - ReadOnly Execute ZeroPage Space 1
Cumulate
.text 0x00002d - 0x001 - - ReadOnly Execute ZeroPage Space 1
Cumulate
.data 0x000003 - 0x001 - - Write Space 2 Initialized Cumulate
.zdata 0x000001 - 0x001 - - Write Space 2 Cleared Cumulate

The first two columns give you the section name and the section size. The column 'Address' gives you the section address, or a '-' if the section is still relocatable. The section alignment is always 1 for the TriCore. The page size is valid only for the short sections. MAU is the minimum addressable unit of an address space (in bits). There are two main groups of section attributes, the allocation attributes, used by the locator and the overlap attributes, used by the linker:

Allocation attributes
Write Must be located in ram
ReadOnly May be located in rom
Execute May be located in rom
Space num Must be located in addressing mode num
Abs Already located by the assembler
Cleared Section must be initialized to '0'
Initialized Section must be copied from ram to rom
Scratch Section is not filled or cleared

Table 11-1: Allocation attributes

Overlap attributes
MaxSize Use largest length encountered
Unique Only one section with this name allowed
Cumulate Concatenate sections with the same name to one bigger section
Overlay Sections with the name name@func must be combined to one section name, according to the rules for func obtained from the call graph.
Separate Sections are not linked.

Table 11-2: Overlap attributes

11.5.2.3 Option -c, display call graphs

The call graph is used by the linker overlaying algorithm. Once a file is linked and overlaying is done, the call graph information is removed from the object file. If you try to see the call graph in calc.out you will get the message 'No call graph found'.

The file calc.obj is not yet linked. You can use this file to see what a call graph looks like:

Because the calc example does not contain any sections which need to be overlaid you will again get the message 'No call graph found'. The following is just an example of what a call graph could look like:

Each call graph consists of a function (main in graph 0), followed by a list of functions and/or other graphs, which are called by the first function. The functions and call graphs called by this function are indented by two spaces. If a function calls other functions, those functions are listed again with another indentation of two spaces.

As you can see, there are references from one call graph to another. Call graph 1 even calls itself!! This means that function find_legal_row() is a recursive function. If you use the verbose switch the output is somewhat nicer:

The function find_legal_row from call graph 1 is a static function. In order to avoid name conflicts, the source name is added to this function name.

If you want a call graph with resolved call graph references, you can use the linker to generate one:

Option -M tells the linker to generate a .lnl file. This file contains the call graph in the verbose layout. Option -c causes the linker to generate a .cal file. This file contains also the (same) call graph, but in the compact (non verbose) layout. Option -r tells the linker that this is an incremental link.

11.5.2.4 Option -e, display external part

In the external part of an object file, you can find all symbols used at link time. These symbols have an external scope. With the -e option (or -e0) prtri displays the external symbols:

With option -e1 also the name of the output object file is displayed.

The first column contains the name of the symbol. In general, this symbol is a high level symbol with an 'F' added at the front. The next column gives you the symbol status. This can be I for a defined symbol, and X for a symbol which is referred to, but which is not yet defined. In the last column you can find the symbols address. If this address is still relocatable, the section offsets are printed in the form 'section + offset'. If a symbol has already received an absolute address, this address is printed. Symbols that are not yet defined (marked with a X) have a dash printed as address, indicating unknown.

You can add the verbose option as usual. With verbose on more information is printed:

Variable    S   Type Attrib  MAU   Amod   Address/Size
--------------------------------------------------------------
_start_cpt  I   -    -       8     1      .startup + 0x00
_START      I   -    -       8     1      .startup + 0x00
_exit       I   -    -       8     1      .startup + 0x20
_copytable  I   -    -       8     1      .startup + 0x22
_main       I   -    -       8     1      .text + 0x20
_lc_es      X   -    -       8     2      -
_lc_cp      X   -    -       8     2      -

Four additional columns appear. The Type column gives you the symbol type, if available. You can find the meaning of the types in the global type part, section 11.5.2.5. The global types are used to type check the symbols during linking. The Attribute column specifies the attribute of the symbol, if available. For example, the attribute value 0x0020 indicates that the symbol is generated by the assembler. The MAU colomn indicates the minimum addressable unit in bits. So, MAU 8 means the symbol is 8-bit addressable. The Amod column lists the addressing mode of the symbol.

11.5.2.5 Option -g, display global type information

The linker uses the global type information to check on type mismatches of the symbols in the external part. This information is always available, unless you explicitly suppress the generation of these types with option -gn at compile time. Of course, type checking can only be done if the types are available. The global types in calc.out:

In this example you will get the message 'No global types available'. The following is just an example of what the global type information could look like:

In the first column you find the type index. This is the number by which the type is referred to. This number is always a hexadecimal number. Numbering starts at 0x101, because the indices less than 0x100 are reserved for, so-called, 'basic types'. The second column contains the type mnemonic. This mnemonic defines the new 'high level' type. In the Name column you will find the name for the type, if any.

The last column contains type parameters. They tell you which (basic) types a high level type is based on and give other parameters such as modes and sizes. Types are preceded by a T. So, in the example above, type 105 is based upon type 2 (T2 in the parameter list) and type 103 is based upon type 1 and type 104.

In the next table you can find an overview of the basic types:

Type index Type Meaning
1 void -
2 char 8 bits signed
3 unsigned char 8 bits unsigned
4 short 16 bits signed
5 unsigned short 16 bits unsigned
6 long 32 bits signed
7 unsigned long 32 bits unsigned
10 float 32 bit floating point
11 double 64 bit floating point
16 int 16 bits signed
17 unsigned int 16 bits unsigned

Table 11-3: Basic types

The type mnemonics define the class of the newly created type. The next table shows the type mnemonics with a short description:

Mnemonic Description Parameters
G generalized structure size, [member, Tindex, offset, size ]...
N enumerated type [name, value ]...
n pointer qualifier Tindex, memspace
O small pointer Tindex
P large pointer Tindex
Q type qualifier q-bits, Tindex
S structure size, [member, Tindex, offset ]...
T typedef Tindex
t compiler generated type Tindex
U union size, [member, Tindex, offset ]...
X function x-bits, Tindex, 0, nbr-arg, [ Tindex ]...
Z array Tindex, upper-bound
g bit type sign, nbr-of-bits

Table 11-4: Type mnemonics

The Tindex for mnemonic n, O, P, Q, T, t and Z are the types upon which the new type is built. The Tindex for the union and the structures are the type indices for the members. For the function type, the first Tindex is the return type of the function. The second Tindex is repeated for each parameter, and gives the type of each parameter. The value -1 (0xffffffff) always means 'unknown'. This can occur with a function type if the number of parameters is unknown, or with an array if the upper bound in unknown. The sizes and offset for the generalized structure are in bits. The first size is the size of the structure, the second size is the size for the member.

The type information obtained with the -g switch has no verbose equivalent.

11.5.2.6 Option -d, display debug information

The -d switch has two variants. With -d0 you get a table of contents:

Now, you can use -dn to examine a single (linked) file. For instance, -d3 shows you only the debug info of calc.obj. It is also possible to see all debug info, by using option -d without a value.

The -d switch without the verbose option -v shows you only local variables and procedure information. If you combine the -d switch with the verbose switch -v, also local type info, line numbers, stack update information and more procedure information is displayed.

In the example you are using the verbose switch. Where required, the remark 'Only with verbose on' will be given.

The object reader starts with a header, followed by the local type information:

This type info is only printed if you use the verbose option -v. The information found in this table is exactly the same as the information explained for the global type information, see 11.5.2.5.

After the local types, you will find the local symbols.

The value for the symbol status in the external part was an I or an X. Here, you can see a new letter. The N stands for a local symbol. Other possible entires can have the letter G or S. They are no symbols, but procedures. These procedures are printed at this place in order to define their relative position. The actual procedure information is given in the next block of information. Here you can find the additional procedure information. The procedure block is printed only if you use the verbose switch:

The following is an example of some procedures:

Name               S     Additional information
-----------------------------------------
main               G     0x00, 0x00, T101, QUEENS_PR + 0x00, 
                         ( QUEENS_PR + 0x49 ) - 0x01
find_legal_row     S     0x00, 0x00, T120, QUEENS_PR + 0x49, 
                         ( QUEENS_PR + 0x156 ) - 0x01
display_board      S     0x00, 0x00, T10a, QUEENS_PR + 0x156, 
                         ( QUEENS_PR + 0x2a4 ) - 0x01
display_field      S     0x00, 0x00, T121, QUEENS_PR + 0x2a4, 
                         ( QUEENS_PR + 0x302 ) - 0x01
display_status     S     0x00, 0x00, T103, QUEENS_PR + 0x302, 
                         ( QUEENS_PR + 0x31d ) - 0x01

The first two columns are the same as those in the local variable table. The G stands for an external (global) function, the S for a static (local) function.

Each function has 5 parameters with the following meaning:

param #1 Frame type, not used

param #2 Frame size, the distance from the stack pointer before the function call to the stack position just after the local variables.

param #3 The type of the function

param #4 The start address of the function. In a relocatable object the syntax 'section + offset' is used.

param #5 The last function address. See also param #4.

Next in the debug info is the line number information and the stack information. Both items are only printed if you had turned the verbose switch on:

Lines include/stdarg.h:
=======================
No line info available

Lines include/stdio.h:
======================
No line info available

Lines queens.c:
===============

Address | Line Address | Line Address ...
--------------------------- --------------------------- ---------------
QUEENS_PR + 0x000000 | 52 QUEENS_PR + 0x0000c2 | 90 QUEENS_PR + ...
QUEENS_PR + 0x000000 | 53 QUEENS_PR + 0x0000d9 | 101 QUEENS_PR + ...
QUEENS_PR + 0x000006 | 55 QUEENS_PR + 0x0000d9 | 103 QUEENS_PR + ...
. . .
. . .
. . .
QUEENS_PR + 0x0000bd | 98 QUEENS_PR + 0x00018e | 133 QUEENS_PR + ...
QUEENS_PR + 0x0000c0 | 99 QUEENS_PR + 0x000190 | 136 QUEENS_PR + ...
QUEENS_PR + 0x0000c2 | 100 QUEENS_PR + 0x00019f | 137

Stack info include/stdarg.h:
============================
No stack info available

Stack info include/stdio.h:
===========================
No stack info available

Stack info queens.c:
====================
No stack info available

The stack info gives the actual stack position for each executable address. This value is measured from the start position, just after the functions local variables to the actual stack position. If you push one byte on stack, the delta will be increased by one.

The debug info per module ends with a block for each function. Within this block the local variables per function are displayed:

11.5.2.7 Option -i, display the section images

As with the -d option, you can ask a table with available section images by specifying option -i0:

You can select the image to display by specifying the image number:

It is also possible to get the section offsets or absolute addresses by specifying the verbose flag:

Section .text:
==============

000000 02 32 05 e3 ce 00 01 c4 f8 b0 cf 88 f3 f0 50 b4 .2............P.
000010 cf d8 ce a1 51 d8 ce e1 cf 00 b1 cc a9 01 cf f8 ....Q...........
000020 rr rr rr rr rr rr rr rr rr rr rr rr rr .............

The dump always shows the hexadecimal byte value per address. Sometimes however, this is not possible. First of all, it is possible that a certain byte cannot be determined because it is not yet relocated. In this case the byte is represented as rr.

Secondly, it is possible that there is no section image allowed. This is for instance the case for sections that are cleared during startup. After the invocation (verbose on) the reader prints:

Section .zdata:
===============

No image allowed, cleared during startup

It is possible that you read an absolute file. In the absolute file it is possible to combine different sections to new clusters. These clusters do not have the same attributes as the sections and the reader does no longer know where the overlay area is positioned:

Section rom:
============

000000 00 53 f9 ss 00 02 02 00 f0 00 00 00 00 00 00 00 .S..............
000010 01 01 00 f0 01 00 00 b6 00 00 00 03 00 ss ss ss .......2........
000020 ss ss ss ss ss ss 02 32 05 e3 ce 00 01 c4 f8 b0 ....P.....Q.....
000030 cf 88 f3 f0 50 b4 cf d8 ce a1 51 d8 ce e1 cf 00 ................
....

As you see, the reader only prints bytes that it actually can read from the object file. The ss in the dump means scratch memory. It may or may not be initialized by the start-up code. This information is not available anymore to the reader. The start-up code can use a locator generated table to get the information. See the Locator chapter.

11.5.3 Viewing an Object at Lower Level

11.5.3.1 Object Layers

As with the well known OSI layer model for communication, you can also distinguish layers in an object file. The object file is a medium for the compiler which lets the compiler communicate with the debugger or the target board. The lowest level can be classified as mass storage, mostly the disc. The lowest viewable level for the readers concern are the raw bytes.

prtri knows this layer as level 0.

Of course, the bytes in level 0 have a meaning. Because the object format is a format according to IEEE 695, the object file is a collection of MUFOM commands. The general idea is, that an object producing tool sends commands to a object consuming tool. These commands are described in detail by the official IEEE standard (IEEE Trial Use Standard for Microprocessor Universal Format for Object Modules (IEEE std. 695), IEEE Technical Committee on Microcomputers and Microprocessors of the IEEE Computer Society, 1990) . The raw bytes from level 0 appear to be encoded MUFOM commands. The MUFOM commands are interpreted in a layer just above the raw bytes layer.

prtri knows this layer as level 1.

The next layer is the MUFOM environment, the type and section tables are built, values are assigned, attributes are set just by performing the MUFOM commands. The IEEE document describes also some predefined meanings about scope, section attributes naming conventions for MUFOM variables. This knowledge is available in the highest MUFOM layer.

prtri knows this layer as level 2.

With these first layers, the compiler and debugger/target board have a perfect communication channel. The next layers (not supported by the reader at this moment) define a protocol between compiler and debugger about target and language specific information.

In the next sections you can find some examples about the use of the reader at lower levels. Until now, you used the default level of the reader, level 2.

11.5.3.2 The Level Option -ln

Level 1

Switching to another level is simple. You can use the -l option with the level you want to see. As an example, the section part of calc.out at level 1:

If you are not familiar with the MUFOM commands, you can use the verbose switch. The abbreviated commands such as AS, SA or ST are expanded to Assignment, Section alignment and Section type:

The Ln and Sn MUFOM variables are defined as the address and the size of section n. At level 2 you saw (refer to section 11.5.2.2) that the level 2 view did not mention the L and S variables, because at level 2 the meaning of the L and S variables are known!

Level 0

Switching to level 0 is accomplished by using -l0 (as you expected):

The bytes are printed in the MUFOM command structure. It should be easy to find the encoding for the used MUFOM commands. You can use the verbose switch if you want to see file offsets:

0000b3 e6 01 d2 d8 c1 da d3 0f 2e 73 74 61 72 74 75 70 5f .........startup_
76 65 63 74 6f 72 vector
0000ca e2 cc 01 81 00 .....
0000cf e2 d3 01 02 ....
....
00013c e6 07 d7 c2 d9 02 c3 06 2e 7a 64 61 74 61 .........zdata
00014a e2 d3 07 01 ....

Viewing Mixed Levels

You can also mix the levels. It is for instance possible to see level 0 and 1 together by specifying option -l01 (equivalent to -l10 or -l0 -l1):

And of course, you can turn on the verbose switch. The switch between level 0 and level 1 is done per MUFOM command. This is because a MUFOM command is the smallest unit at level 1.

If you should display level 1 and 2, the switch is made per object part, because the object parts are the smallest units at level 2. It is not possible to show the results of all section related commands before all these commands are executed:

11.5.3.3 The Verbose Option -vn

As you have read in section 11.5.3.2, you can switch to a lower level with the level switch -ln. If you want a verbose printout, you can use the -v option.

It is also possible to specify -v0 to see a verbose output of level 0, option -vn is a shorthand for options -v -ln (or -vln). The new notation has the advantage that if you want a mixed level output, you are able to choose the verbose option per level. You may specify -l0 -v1, and you get a non verbose level 0 and a verbose level 1:

The general verbose switch -v (without a number) makes all selected levels verbose. The verbose switch -vn selects level n and makes only level n verbose.


Copyright © 2002 Altium BV