Intel i960 User Manual

Download

i960 Processor Compiler User's Guide

Order Number: 651230-002

Revision Revision History Date

-001 Original Issue. 02/96

-002 Revised for release 5.1 01/97

In the United States, Intel literature may be obtained by writing:

Literature Distribution Center Intel Corporation P.O. Box 7641 Mt. Prospect, IL 60056-7641

Or you can call the following toll-free number:

1-800-548-4725 In locations outside the United States, contact your local Intel sales office. Intel Corporation makes no warranty of any kind with regard to this material, including, but not limited to, the implied

warranties of merchantability and fitness for a particular purpose. Intel Corporation assumes no responsibility for any errors that may appear in this document. Intel Corporation makes no commitment to update nor to keep current the information contained in this document.

Intel Corporation assumes no responsibility for the use of any circuitry other than circuitry embodied in an Intel product. No other circuit patent licenses are implied.

Intel software products are copyrighted by and shall remain the property of Intel Corporation. Use, duplication or disclosure is subject to restrictions stated in Intel's Software License Agreement, or in the case of software delivered to the government, in accordance with the software license agreement as defined in FAR 52.227-7013.

No part of this document may be copied or reproduced in any form or by any means without prior written consent of Intel Corporation.

Intel Corporation retains the right to make changes to these specifications at any time, without notice. Contact your local sales office or distributor to obtain the latest specifications before placing your order.

* Other brands and names are the property of their respective owners.

printed on

recycled paper

Contents

Chapter 1 The CTOOLS Compilation System

Features........................................................................1-1

Compatibility and Conformance to Standards....................1-2

About this Manual..............................................................1-4

Audience Description.....................................................1-6

Licensing and Copyrights..............................................1-6

UNIX and Windows Conventions...................................1-6

Customer Service...............................................................1-7

Where Do You Go From Here?..........................................1-7

Chapter 2 gcc960 Compiler Driver

Controlling the Compilation System with gcc960 ...............2-1

Invoking the Compiler with gcc960................................2-2

gcc960 Sample Command Lines...................................2-3

gcc960 Linker Options...................................................2-5

gcc960 and Predefined Macros.....................................2-6

gcc960 and File Use ..........................................................2-8

Input Files......................................................................2-8

Include Files..................................................................2-9

Output Files...................................................................2-9

.GLD Files..........................................................................2-11

gcc960 Options..................................................................2-13

Option Arguments and Syntax...........................................2-15

iii

i960 Processor Compiler User's Guide

Chapter 3 ic960 Compiler Driver

Controlling the Compilation System with ic960...................3-1

Invoking the Compiler with ic960...................................3-2

ic960 Sample Command Lines......................................3-3

ic960 Linker Options......................................................3-4

ic960 and Predefined Macros........................................3-6

ic960 and Environment Variables..................................3-8

ic960 and File Use .............................................................3-11

Input Files......................................................................3-11

Include Files ..................................................................3-11

Temporary Files .............................................................3-12

Output Files...................................................................3-12

ic960 Options.....................................................................3-15

Option Arguments and Syntax ...........................................3-17

Chapter 4 Program-wide Analysis and Optimization

Introduction ........................................................................4-1

Individual and Program-wide Optimizations...................4-1

About Profiling...............................................................4-2

Creating Program-wide and Module-local Optimizations ....4-2

Specifying the Program Database Directory..................4-2

Compiling for Program-wide Optimization with the fdb

Option............................................................................4-3

Global Decision Making and Optimization Using the

gcdm Option..................................................................4-3

Selecting Modules for Optimization with Substitution

Specifications ................................................................4-4

Contents

Profiling Your Program.......................................................4-5

Compiling for Profile Instrumentation with -fprof............4-5

Collecting a Profile.........................................................4-5

Building Self-contained Profiles with gmpf960...............4-6

Using Profiles During Global Decision Making and

Optimization with -gcdm,iprof ........................................4-7

Obtaining Program Coverage Analysis with gcov960 ....4-7

Using make To Perform Program-wide Optimizations........4-7

Adapting Makefiles for Program-wide Optimization.......4-8

Using Makefiles with Program-wide Optimizations for

Common Development Tasks .......................................4-10

Runtime Support for Profile Collection...............................4-15

Profile Initialization.........................................................4-15

Chapter 5 Profile Data Merging and Data Format (gmpf960)

Merging Profile Data ..........................................................5-1

gmpf960 Invocation............................................................5-2

Profile Format Specification ...............................................5-4

Profile Data Structures ..................................................5-4

default.pf File Format.....................................................5-4

Creating a Runtime Report with gmpf960..........................5-6

Chapter 6 gcdm Decision Maker Option

gcdm Option Syntax...........................................................6-1

gcdm Option Arguments ....................................................6-2

Substitution Controls .....................................................6-2

Whole-program Optimization Option (Category 1).........6-3

Module-local Optimization Options (Category 2)...........6-3

Miscellaneous Substitution Options (Category 3)..........6-5

External Reference Controls .........................................6-7

i960 Processor Compiler User's Guide

Inline Level Control........................................................6-7

Input Profile Control.......................................................6-8

Fast Memory Controls ................................................... 6-8

Dryrun Control ...............................................................6-9

Report Controls .............................................................6-9

Module-set Specification....................................................6-13

Chapter 7 Language Implementation

Data Representation..........................................................7-1

Scalars...........................................................................7-1

Aggregates....................................................................7-4

Other Type Keywords....................................................7-14

Calling Conventions ...........................................................7-14

Definitions......................................................................7-15

Parameter Assignment to Registers..............................7-17

Argument Blocks ...........................................................7-17

Return Values................................................................7-18

Compiler Implementation...............................................7-18

Object Module Section Use................................................7-19

Pragmas.............................................................................7-20

#pragma align [for gcc960 driver]..................................7-20

#pragma align [for ic960, or for gcc960 with

ic960 option]..................................................................7-22

#pragma cave................................................................7-26

#pragma compress........................................................ 7-30

#pragma i960_align [for gcc960 and ic960]...................7-31

#pragma inline...............................................................7-31

#pragma interrupt..........................................................7-32

#pragma isr....................................................................7-34

Contents

#pragma optimize..........................................................7-34

#pragma pack................................................................7-35

#pragma pure................................................................7-37

#pragma section............................................................7-38

#pragma system............................................................7-38

Language Extensions ........................................................7-39

Statements and Declarations Inside of Expressions .....7-40

Naming an Expression’s Type.......................................7-40

Referring to a Type with typeof......................................7-41

Generalized Lvalues......................................................7-42

Conditional Expressions with Omitted Middle

Operands.......................................................................7-44

Arrays of Length Zero....................................................7-44

Non-lvalue Arrays Can Have Subscripts........................7-45

Arithmetic on Pointers to void and Pointers to

Functions.......................................................................7-45

Non-constant Initializers................................................7-46

Constructor Expressions ...............................................7-46

Declaring Attributes of Functions...................................7-47

Inquiring about Alignment..............................................7-48

Inline Functions Are as Fast as Macros.........................7-48

Controlling Names Used in Assembly Code..................7-50

Specifying Registers for Local Variables.......................7-51

Alternate Keywords .......................................................7-51

Inline Assembly Language.................................................7-52

Introduction....................................................................7-52

Resource Usage............................................................7-52

asm Statements ............................................................7-53

asm Functions...............................................................7-70

vii

i960 Processor Compiler User's Guide

Chapter 8 gcc960/ic960 Compatibility

char and short Parameters............................................8-1

enum Variable Byte Count.............................................8-1

char Types.....................................................................8-2

Identifying Architectures ................................................8-2

#pragma align................................................................8-3

mic3.0-compat Option....................................................8-3

mic2.0-compat Option....................................................8-3

Chapter 9 Position Independence and Reentrancy

Position-independent Code and Data ................................9-1

Position-independent Data............................................9-1

Position-independent Code...........................................9-2

Example: Position-independent ROM Code.................9-3

Guidelines for Writing Relocatable Programs................9-5

Reentrant Functions...........................................................9-6

Designing Reentrant Functions .....................................9-6

Chapter 10 Initializing the Execution Environment

Startup Code......................................................................10-1

RAM-based Initialization................................................10-4

ROM-based Initialization................................................10-4

Linker Configuration Files...................................................10-5

RAM-based Configuration File.......................................10-6

ROM-based Configuration File ......................................10-6

Chapter 11 Optimization

viii

Optimization Categories and Mechanisms.........................11-1

Constants and Expression Evaluation................................11-3

Common Sub-expression Elimination............................11-3

Constant Expression Evaluation (Constant Folding) ..... 11-4

Dead-code Elimination...................................................11-5

Identity Collapsing.........................................................11-5

Constant Propagation....................................................11-6

Contents

Calls, Jumps, and Branches ..............................................11-9

Branch Optimizations ....................................................11-9

Branch Prediction..........................................................11-10

Identification of Leaf Functions......................................11-11

Inline Function Expansion .............................................11-11

Tail-call Elimination........................................................11-12

Loop Optimizations ............................................................11-14

Movement of Loop-invariant Code ................................11-14

Induction Variable Elimination.......................................11-14

Loop Unrolling...............................................................11-15

Memory Optimizations........................................................11-15

Global Alias Analysis.....................................................11-15

Variable Shadowing ......................................................11-16

Local Variable Promotion ..............................................11-17

Instruction Selection and Sequencing................................11-18

Code Compression........................................................11-18

Code Scheduling...........................................................11-18

Specialized-instruction Selection...................................11-20

Program-level Optimization................................................11-20

Inter-module Function Inlining.......................................11-20

Superblock Formation ...................................................11-21

Profile-based Branch-prediction Bit Setting...................11-22

Chapter 12 Caveats

Aliasing Assumptions.........................................................12-1

Alignment Assumptions......................................................12-3

Volatile Objects..................................................................12-4

Known Problems Using the Compiler.................................12-6

Type Promotion.............................................................12-6

Prototype Scope............................................................12-6

i960 Processor Compiler User's Guide

longjmp and Volatile Data..............................................12-7

Incorrect debug information generated for arrays with

unspecified bounds........................................................12-7

C Version Incompatibilities.................................................12-8

String Constants Read-only...........................................12-8

No Macro Argument Substitution in Strings...................12-8

External Variables and Functions in Blocks ...................12-8

Combining long with typedef Names .............................12-9

Using typedef Names in Function Parameters .............. 12-9

Whitespace in Compound Assignment Operators.........12-9

Flagging Unterminated Character Constants.................12-10

Disguised varargs or stdarg Routines ............................12-10

Troubleshooting .................................................................12-10

Undefined References...................................................12-10

C Interrupt Service Routine Failures ..............................12-11

Preventing Structure Padding........................................12-12

Breakpoints Inside Interrupt Handlers ........................... 12-15

Chapter 13 Messages

Messages on the Standard Error Device.......................13-2

Messages in the Listing File ..........................................13-3

Index Figures

7-1 Natural Alignment......................................................7-8

7-2 User-constrained Alignment ......................................7-9

7-3 Optimal Natural Alignment of std_struct.................... 7-12

7-4 Backward-compatible Natural Alignment of

std_struct...................................................................7-13

7-5 #pragma noalign Alignment of std_struct..................7-13

7-6 #pragma align Alignment of std_struct......................7-14

9-1 Memory for Hypothetical Position-independent

Application.................................................................9-4

11-1 Superblock Formation Process..................................11-21

Contents

Tables

1-1 Compiler Limits..........................................................1-3

1-2 Chapter Descriptions.................................................1-4

2-1 Linker Options Accepted by gcc960..........................2-6

2-2 Intermediate Inputs and Outputs...............................2-10

2-3 gcc960 Option Summary...........................................2-15

2-4 Mcore Supported Architectures.................................2-41

3-1 Linker Options Accepted by ic960.............................3-5

3-2 Intermediate Inputs and Outputs...............................3-13

3-3 ic960 Option Summary..............................................3-17

3-4 Gcore Supported Architecures..................................3-37

3-5 Stop-after Option Phases and Output.......................3-59

6-1 gcdm Option Arguments............................................6-1

7-1 Scalar Data Types.....................................................7-2

7-2 Example Offset Values..............................................7-36

7-3 Return Value Class Matching....................................7-75

7-4 Argument Category to Parameter Class Matching

and Coercion.............................................................7-75

7-5 C Data Types and asm Classes................................7-78

8-1 Architecture Macros and Compatibility......................8-2

level

11-1 Optimizations and O

Settings ............................11-2

11-2 Examples of Constant Expression Evaluation...........11-4

11-3 Examples of Identity Collapsing................................11-6

The CTOOLS Compilation System

This manual provides operating instructions and other information on the CTOOLS compilation system. This system consists of a compiler and two drivers that provide the user interface to the compiler, gcc960 and ic960. These two interface drivers allow backward compatibility with software developed using GNU/960 and CTOOLS960 respectively.

Features

The compiler lets you use the following features to develop applications:

• Use of either the gcc960 or ic960 compiler driver to invoke and

control translation and linking.

• Creation of a run-time performance profile of your application.

Optimizations based on this profile include inter-module optimizations and preferential use of fast memory regions for variables that are heavily used. For an overview of the program-wide optimization process, including profile-driven optimization, see Chapter 4. For descriptions of other optimizations, refer to Chapter 11.

• Calling

text, or including in-line assembly language in your C program.

• Stopping the compilation process to examine intermediate results after

syntax checking, preprocessing, compilation, assembly, or incremental linking. (See Chapters 2 and 3.)

• Using a single command to translate and link modules into a complete

ROM-able or executable program. (See Chapters 2 and 3.)

functions written in i960 processor assembly language source

1-1

i960 Processor Compiler User's Guide

• Using the CAVE pragma to compress functions, thus reducing code

size. During program execution, these functions are decompressed when called. For more information on the CAVE and other pragmas, see Chapter 7.

• Creating blended code with the new

options. With these options, you can generate code that is compatible with multiple i960 processor types. For more information, see Chapters 2 and 3.

-mcore0-3 and -Gcore0-3

Compatibility and Conformance to Standards

The compiler runs on a UNIX* or a Windows* 95/NT* host system and generates object code for any i960 commercial processor. The translation and code generation phases use the instruction set for the i960 processor that you specify.

The compiler's implementation of C conforms to the ANSI standard for the C language (X3.159-1989). One exception is static pointer initialization in applications using position-independent code or data (described in Chapter 9). Additionally, the compiler allows use of in-line assembly language in the C source text.

1-2

The ANSI standard specifies that a conforming implementation of a C compiler must meet minimum requirements for certain translation limits. In all cases, the compiler exceeds ANSI limits. Table 1-1 lists the tested levels for each translation limit and compares them to ANSI minimum requirements. Available memory determines actual limits in a host system.

The CTOOLS Compilation System

Tested

Minimum

128

1024

4096

128

4096

65535

1024

512

2048

128

Table 1-1 Compiler Limits

Limit

Control structure nesting levels 15 Conditional compilation nesting levels 6 Declarator modifiers 12 Declaration parenthesis nesting levels 31 Parenthesis nesting levels 32 Significant characters for internal identifier 31 Name length for external identifier 6 Identifiers in a single block 127 Macros simultaneously defined 1024 Parameters per function call 31 Characters in a logical line 509 Characters in a string 509 Bytes in an object 32767 Include file nesting levels 8 Case labels in a switch 257 Members in one structure or union 127 Enumeration constants in one enumeration 127 Structure nesting levels 15 External identifiers per file 511 Parameters per macro 31

ANSI Minimum

1-3

i960 Processor Compiler User's Guide

About this Manual

This manual contains the following chapters:

Table 1-2 Chapter Descriptions

Chapter Number Title Description

1. The CTOOLS Compilation System

2. gcc960 Compiler Driver

3. ic960 Compiler Driver

4. Program-wide Analysis and Optimization

5. Profile Data Merging and Data Format (gmpf960)

6. gcdm Decision Maker Option

Introduces the compiler and provides information on using this manual.

Teaches you how to use the gcc960 command-line interface and provides a complete list of command line options.

Teaches you how to use the ic960 commandline interface and provides a complete list of command line options.

Tells you how to use some of CTOOLS most powerful optimization features:

• individual module optimizations

• program-wide optimizations

• run-time profiling

Explains how to use gmpf960 to merge the execution profile data you collected in Chapter 4. You also learn how to use gmpf960 to create a report that shows how many times each basic block was “hit” or run during program execution.

Describes the gcdm option, which invokes the gcdm960 global optimization decision maker during the link process. The decision maker then invokes the compiler and linker as necessary to perform program-wide optimizations.

1-4

continued

☛

The CTOOLS Compilation System

Table 1-2 Chapter Descriptions (continued)

Chapter Number Title Description

7. Language Implementation

Describes data representation, register use, object file format use, and pragmas for modifying code generation.

8. gcc960 / ic960 Compatibility

9. Position Independence and Reentrancy

10. Initializing the Execution Environment

11. Optimization Describes the different ways in which the

12. Caveats This chapter provides useful programming

Describes the incompatibilities between ic960 and gcc960.

Provides information on writing i960 processor applications that require positionindependent or reentrant programs.

Describes the initialization process for the i960 processor execution environment, including the startup assembly-language routine, configuration files, and associated options.

compiler can optimize your program and explains ways to control optimization.

tips on:

• Aliasing assumptions

• Alignment assumptions

• Volatile object

• Known problems

• C version incompatibilities

• Troubleshooting

13. Messages Describes the diagnostic messages that the

compiler produces.

1-5

i960 Processor Compiler User's Guide

Audience Description

This manual assumes that you are familiar with the i960 processor architecture, C and assembly language programming, and your host computer's operating system.

Licensing and Copyrights

Refer to the i960 Software Tools License Guide for licensing and copyright statements.

UNIX and Windows Conventions

This manual tells you how to use the compiler in both UNIX and Windows 95/NT systems. This manual uses the following conventions:

• Command-lines appear without a preceding prompt.

• Paths use the UNIX forward slash (

backslash (

• Command-line option examples use the UNIX dash (

than the Windows forward slash (

• Environment variables are referenced using the UNIX dollar-sign

(e.g.,

\) for pathnames.

$I960BASE), not the Windows % character.

/) rather than the Windows

-) prefix rather

/) prefix.

1-6

NOTE. In UNIX, only the dash (-) is accepted as a prefix for a command-line option. In Windows, both the ( as a prefix for a command-line option.

-) and the (/) are accepted

The CTOOLS Compilation System

Customer Service

If you need service or assistance with CTOOLS, see your Getting Started with the i960 Processor Development Tools manual.

Where Do You Go From Here?

If you installed the CTOOLS GNU interface, go to Chapter 2 for information on using the gcc960 compiler driver. If you installed the CTOOLS/960 interface, go to Chapter 3 for information on using the ic960 compiler driver. Once you are familiar with the compiler driver interface, you are ready to read Chapters 4 through 6, where you learn how to use some of the more advanced features of the compilation system, including whole program optimizations, profiling, and using the gcdm global decision maker program.

1-7

gcc960 Compiler Driver

This chapter describes how to use the gcc960 driver program to control the compilation system. Topics include:

• running the compilation system

• sample command lines

• predefined macros

• command line options and their modifiers

Controlling the Compilation System with gcc960

gcc960-style translation and linking requires use of the gcc960 driver, preprocessor, compiler, assembler, and linker.

The gcc960 compiler driver ( controls the preprocessor ( the compiler ( invoke the assembler, linker, and gcdm960 optimization decision maker.

Command-line options and environment variables allow you to control the compilation.

gcc960 controls preprocessing, compilation, assembly and linking.

• Filenames ending in

compiled.

• Filenames ending in

compiled.

• Compiler output files plus any input files with names ending in

assembled.

• Input files with names ending in

then assembled. (UNIX only.)

cc1.exe in Windows, cc1.960 on Unix). It can also

gcc960.exe in Windows, gcc960 on Unix)

cpp.exe in Windows, cpp.960 on Unix) and

.c are taken as C source to be preprocessed and

.i are taken as preprocessor output to be

.s are

.S (uppercase) are preprocessed and

2-1

i960 Processor Compiler User's Guide

• The resulting object files, plus any other input files, are passed to the

linker to produce an executable.

• Program-wide and profile-directed optimizations can be performed

during the link step. For an overview of this capability, see Chapter 4.

Invoking the Compiler with gcc960

The gcc960 command-line syntax is:

gcc960 [-

option

]... [

path/]filename

... [@

response-file

]

gcc960

option

is the compiler driver executable filename. is a compiler option. Case is significant in

options and their arguments. Multiple singlecharacter options cannot be grouped: different from options contradict each other, the right-most option in the command line takes precedence. For example, the following command line sets the value of the symbol

gcc960 -DL=80 -DL=132 proto.c

Note that the gcc960 compiler driver does not check the command line options for validity. Invalid options are ignored without producing a warning message.

On UNIX, the compiler recognizes a letter preceded by a hyphen ( Windows, the compiler recognizes a letter preceded by either a hyphen ( an option. For example, Architecture option for UNIX or Windows. However, on a Windows system, specifies the architecture option.

-d -r. When two or more

L to 132:

-) as an option. In

-) or a slash (/) as

-A specifies the

-dr is

/A also

2-2

gcc960 Compiler Driver

path

NOTE. Although Windows pathnames require backslashes (\), this manual shows paths using the forward slash required by UNIX (

filename

response-file

identifies the directory containing the file named by

filename

directory. Each directory requires a separate

is the name of a source, preprocessed source, assembly-language, or other file (e.g., linker directive file) to be processed by the compilation system. The gcc960 command line allows specification of more than one

[

path/]filename

Open the named response file and read in its contents as if they had been typed on the command line. Response files are a convenient way to store commonly-used command line options, and a way to get around the 128character limit in Windows command lines.

. Not specifying

causes gcc960 to search in the current

filename

path

for a

not in the current

path

specification.

Response files can contain comments. Lines whose first non-whitespace character is treated as comment lines, and ignored.

# are

gcc960 Sample Command Lines

This section provides examples of how the compiler is commonly invoked. All these examples assume that you have C source files named

t2.c and that you are generating code for the i960 CA architecture.

t1.c and

2-3

i960 Processor Compiler User's Guide

Preprocessing a Source File

To preprocess a source file, use the command:

gcc960 -E t1.c

-E

informs the compiler to preprocess the source

file and echo the output to stdout.

Generating Assembly Code

To generate assembly code for the i960 CA architecture, use the following command.

gcc960 -S -ACA t1.c

-S

instructs the compiler to generate assembly code.

-A specifies the i960 CA architecture.

Generating an Object Module with Debug Information

To generate a object module with debug information, use the following command.

gcc960 -c -g -ACA t1.c

2-4

-g

instructs the compiler to generate debug

information.

-c instructs the compiler to generate an object file.

Generating an Executable

To generate an absolute module (executable file) for a Cyclone board with a CA processor, use the following command.

gcc960 -ACA -Tmcycx -g -O t1.c t2.c -o test

The above command compiles the modules t1.c and t2.c and links them with appropriate libraries to generate an absolute module targeted for a Cyclone i960 Cx evaluation board.

-Tmcycx instructs the compiler that you are targeting a

Cyclone i960 Cx evaluation board.

gcc960 Compiler Driver

-O causes the compiler to perform some basic

optimizations on the generated code.

-o instructs the compiler to name the generated

executable test.

gcc960 Linker Options

When you do not specify a target with the T not attempt to link programs for a specific target board. Unless otherwise specified, following linker command is issued:

gld960 -AKB $G960BASE/lib/crt960.o

To link for a different target, you can change the crt (startup) file and add board and monitor support libraries.

To link for another environment, the options gcc960 from including the default C startup files or libraries in the link, allowing them to be fully specified by the user. For example:

gcc960 -crt -nostdlib mycrt.o

You can invoke gcc960 to create object files in either the b.out, COFF or ELF object module format. The compilation system accepts the option to generate COFF and the Felf option to generate ELF; these options override the gcc960 driver's default format option, which is

Fbout.

For more detailed information, see the following discussions of compiler invocation and options.

.c and .s files are compiled and/or assembled, and the

target

file.

option, gcc960 does

file

.o... -lqf -lc -lm

crt and nostdlib prevent

o... -lc -lmylib

Fcoff

2-5

i960 Processor Compiler User's Guide

Table 2-1 lists the linker options that gcc960 passes directly to the linker.

Table 2-1 Linker Options Accepted by gcc960

Option Name Description

e Entry point defines entry point other than default for

beginning execution of program.

gcdm Decision Maker invokes gcdm960 decision maker. l Archive file specifies an archive file as input. L Library search adds directories to search for libraries,

configuration files, and startup object files.

r Relocation retains relocation information in the output

object file.

s Strip strips line-number entries and symbol-table

entries from the linker's COFF output file.

u Unresolved

Symbol

introduces an unresolved symbol, causing the linker to search symbol tables for resolution of the reference.

2-6

X | x Compress X removes all symbols from the output symbol

table; x removes only local symbols.

y Trace symbol traces a symbol; indicates object files where it

appears; provides other information.

z Time stamp suppresses COFF time stamp in linker output

file.

gcc960 and Predefined Macros

Predefined macros within a program can act as constants during execution or as values in conditional-compilation statements. Predefined macros include ANSI-standard macros and macros specific to the i960 processor architecture. The macros but not ANSI-standard macros.

U (Undefine) option removes i960 processor-specific

gcc960 Compiler Driver

The following macros are available in accordance with the ANSI standard for C, as described in the book, C: A Reference Manual:

__DATE__ __FILE__ __LINE__ __TIME__ __STDC__

The following macros are predefined by the compilation system when invoked with the gcc960 driver program:

__GCC960_VER is defined to a decimal number that can be used

to check the version number of the compiler. The number is expressed in decimal as

MmmPPPP mm

is the minor version number, and internal version number that is used to track the patch level. So, for example, R5.0 patch level 4032 have

5004032.

__i960 indicates the i960 processor environment. The

compiler defines macro can be used to identify the parts of a program specific to the i960 processor.

, where M is the major version number,

PPPP

is an

__GCC960_VER defined to be

__i960 automatically. This

__i960

__PIC indicates that the generated code is position-

__PID indicates that the generated data is position-

indicates the i960 processor instruction set in use. The compiler automatically defines the

__i960 CF, JA, JF, JD, HA, HD, HT, or RP. Definition of

instruction set specified by the option.

independent. The (Generate-for-position-independent-code) option causes the

independent. The (Generate-for-position-independent-data) option causes the

macro. The xx is SA, SB, KA, KB, CA,

depends on the specific i960 processor

A (Architecture)

mpic

__PIC macro to be defined.

mpid

__PID macro to be defined.

2-7

i960 Processor Compiler User's Guide

__i960_BIG_ENDIAN__ indicates that the generated code is arranged for

__STRICT_ANSI__ indicates that C constructs not conforming to the

__CHAR_UNSIGNED__ indicates that the plain char type are treated like

gcc960 and File Use

The compiler, assembler, and linker all use filenames specified on the gcc960 command line to find and create input and output files. In addition, translation and linking require temporary work files.

Input Files

big-endian address space. The option causes this macro to be defined.

ANSI standard should be flagged. The (ANSI) option causes these macros to be defined.

the

unsigned char type. This is the default.

G (Big-endian)

ansi

2-8

The gcc960 command line allows filename inputs that support specification of assembly-language files, preprocessed source files, C source files, object files, and libraries. The compiler driver determines the type of each input file by the filename extension, as follows:

filename

filename filename filename

.c indicates a C source file that can contain macros

and preprocessor directives.

.i indicates a preprocessed C source file. .s indicates an assembly-language source file. .S indicates an assembly-language source file that

can contain preprocessor macros and directives.

gcc960 Compiler Driver

The driver passes any other filename to the linker. The linker then determines whether the file is an object file, library, or configuration file.

Input files not needed for processing are not processed. For example, if you specify an assembly-language (

S (Assembly) compile into assembly code option, gcc960 takes no action

on the assembly-language file.

filename

.s) file and also specify the

Include Files

The gcc960 command line allows insertion of text from include files. The

#include preprocessor directive causes text insertion.

The I, I- and I. options affect the directories that are searched for the file specified in the #include directive. These options are described in detail in the Option Arguments and Syntax section. In the absence of the gcc960 searches the current directory for #include “file” and

G960BASE/include directory for #include <file>.

I option,

Output Files

Specifying the options -E, -S, or -c causes the compilation system to produce output of the last phase that completes for each primary input file. Output can be preprocessed source, an assembly-language file, or an unlinked object file. If no errors occur during processing, the output files created by these options are usable as input to a future gcc960 invocation. Table 2-2 lists the compilation phases and their inputs and outputs.

Specifying the separate list file for each primary C source file. The list file is named by replacing the .c or .I extension with .L.

Specifying the for a make tool describing the dependencies of each source file. The

clist and -M options are described in detail in the Option Arguments

and Syntax section.

clist option generates a listing. gcc960 produces a

-M option causes the preprocessor to output rules suitable

2-9

i960 Processor Compiler User's Guide

Table 2-2 Intermediate Inputs and Outputs

Last Phase Completed Option Inputs Outputs

preprocessing M, E C source files display on standard

compilation S C source files

preprocessed files

assembly c C source files

preprocessed files assembly files

linking (default) C source files

preprocessed files assembly files unlinked object files relinkable object files libraries configuration files

output assembly-language file

listing files unlinked object files

listing files

list files executable file relinkable object file

2-10

When specifying only one primary input file, the o (Output) option names a single output file. Specifying multiple primary input files, or not specifying an output filename, causes gcc960 to use the primary input filenames to derive corresponding default output filenames with the form

filename.e filename

, where:

is the primary input filename without its extension.

is a single-letter extension indicating the contents of a file, as follows:

s indicates an assembly-language file

from the

o indicates an object file from the c

S option.

option.

L indicates a listing file from the

clist option.

gcc960 Compiler Driver

Unless otherwise specified, the destination directory for any output file is the current working directory. If destination directory, the compilation system overwrites the existing file.

filename.e

already exists in the

.GLD Files

The filename from the linker, in the absence of an Output option when the compilation proceeds all the way to the link step. For ELF files, the default is and for bout files, the default is b.out.

The following examples illustrate the creation and use of output filename extensions:

• The command

produces the object files proto.o and proto1.o and the listing files

proto.L and proto1.L.

• The command

produces the object file proto_v1.o and the listing file proto.L.

• The command

executable file

The .GLD files provide a convenient mechanism for specifying default options to the compiler and linker. It also provides a mechanism for specifying the startup file and the libraries to be linked in. These files are meant to be used with the gcc960 interface to the tools (GLD is an acronym for gcc960 linker directive file even though it can be used to pass options to the compiler as well).

a.out is the default for the executable COFF object file

e.out

gcc960 -c -clist s proto.c proto1.i

gcc960 -c -o proto_v1.o -clist s proto.c

gcc960 -ACA -Tmcycx proto.c produces the

b.out.

By default, the installation program places several directory [ Cyclone evaluation boards. To illustrate, the sample below is tailored for the Cyclone i960 Cx processor-based evaluation board.

$G960BASE]/lib. These files have been tailored to the

.GLD files in the

.GLD file given

2-11

i960 Processor Compiler User's Guide

Example 2-1 Sample .gld File

gcc:-ACA

crt:%{!crt:%[~]/lib/%{mpid:%{G:crt960_e.o}%{!G:crt960_p.o}} %{!mpid:%{G:crt960_b.o}%{!G:crt960.o}}}

ld:%{!Ttext:-Ttext 0xA0008000}%{*: -defsym _heap_size=0x20000;_heap_base=(_end+0xf)&~0xf;_heap_end=_heap_base+_heap_size1;_stackbase=(_heap_end+0x40)&~0x3f -defsym fpem_CA_AC=0x100}

lib:%{!nostdlib:-lmn -lll}

In the .GLD file, you can place any options that the tools accept on the command line. For example, in the see options for the gcc960 compiler driver and linker.

.GLD file shown in Example 2-1, you

The command in the gcc960 compiler driver. This setting is then used throughout the compilation process. The options following fashion as if they were specified on the gcc960 invocation line.

The commands in the component built into them so that options could be included in a conditional fashion. These sections determine the startup code, linker options and the libraries that are passed on to the linker.

The

crt: section is used to specify the startup code. In the example

given above, if the line, then the compiler driver uses the following for the startup code.

[G960BASE]/lib/crt960_e.o if both -mpid and -G options are on [G960BASE]/lib/crt960_p.o if -mpid option is on -G is off [G960BASE]/lib/crt960_b.o if -mpid option is off and -G is on [G960BASE]/lib/crt960.o if both -mpid and -G options are off

gcc: section defines the architecture setting for the

gcc: are treated in the same

crt:, ld:, and lib: sections have a conditional

-crt option has not been specified on the compile

2-12

gcc960 Compiler Driver

The ld: section contains options that are passed to the linker. This example includes commands to place the

0xA0008000, and defines various symbols that are used to setup the heap and

stack locations sample file, see the i960 Processor Software Utilities User’s Guide.

lib: section in the above example is used to specify that the

The compiler driver should pass on the options if

-nostdlib option is off. This causes the linker to include the monitor

and the low-level libraries in its search path to lookup unresolved symbols.

gcc960 Options

This section describes the gcc960 compiler driver options that allow control of various aspects of compilation:

.text section in at address

. For more information on the linker directives used in this

-lmn and -lll to the linker

Input processing The and output They stop the translation and linking process

Specifying included The source text prepend and find include files of C source text.

Defining macros The

c, E, n, P, Q, and S are the Stop-after options.

after the preprocessing, syntax checking, compilation, or assembly phase. A Stop-after option causes the compilation system to save the intermediate output of the last phase to execute.

The

C (Keep-comments) and M (Mix) options

affect the contents of the output file. The (Output) option allows specification of the output filename.

i (Preinclude) and I (Searchinclude) options

D (Define) and U (Undefine) options allow

specification of macros for conditional compilation.

2-13

i960 Processor Compiler User's Guide

Control contents The A (Architecture), Fcoff | Felf (Object- of generated object format), code

Assembler and The linker support preprocessor, compiler, assembler, and linker. In

G (Generate), and O (Optimization-level) options

control the instruction set, object format, debug information, and optimization level.

addition, gcc960 recognizes some options as linker options rather than compiler options. Table 2-1 lists the options that are relayed to the linker without the Pass option. For more detailed information on linker options, see the i960 Processor Software Utilities User's Guide.

F (Fine-tune), f (Optimize), g (Debug),

W (Pass) option relays options to the

Whole-program The optimizations (Instrumentation), and gcdm (Decision Maker)

Provide Information The on the compiling affect messages the compiler produces about process C syntax and semantics. The

fdb (Program Database), fprof

options allow for creation and use of information necessary for advanced optimizations involving multiple modules and optional execution profiles. See Chapter 4 for an overview of whole-program and profile-driven optimization.

w (Diagnostic) and a (ANSI) options

z (List) and Z

(Listname) options specify the contents and name of the listing file. The (Version), and v960 (Version-exit) options display information about preprocessor, compiler, assembler, and linker options. The Version option displays the versions of each compilation component and the host operating system. The control of the level of warnings emitted.

W (Warnings) option allows fine

v (Verbose), V

2-14

gcc960 Compiler Driver

Option Arguments and Syntax

Some compiler driver options take arguments. Case is significant in options and arguments. A few options allow whitespace between the option and its argument; this whitespace is shown in Table 2-3.

The options and arguments have default settings. In most cases, the option is "off," that is, not in effect. Default settings of options and arguments are summarized in Table 2-3 and further discussed in the detailed description of the option. Some option defaults are affected by environment variables, which are described in the Getting Started manual.

This chapter uses the following notation:

[

item

] Square brackets indicate that the enclosed item is

optional.

. . . Horizontal ellipses indicate that you can use

multiple instances of the preceding item.

Table 2-3 gcc960 Option Summary

Option Name Purpose Default

arch

ansi ANSI Detect non-ANSI source. off C Comments Keep comments in preprocessor output. off c Create Object Stop after creation of object file. off

arg

clist crt Startup Do not use standard startup file. Use default D

[= d E Preprocess Preprocess source; terminate. Do not stop

... Create listing Create a listing. off

macro

value

]

arg

Architecture Select the instruction set. AKB

Define Define

Definitions Control macro processing. off

macro

value

continued

☛

2-15

i960 Processor Compiler User's Guide

Table 2-3 gcc960 Option Summary (continued)

Option Name Purpose Default

Fbout | Fcoff | Felf

fdb Database Build program database directory (PDB). No database fprof Instrument Compile with instrumentation; build PDB. No instru-

arg

f[no-]

G Big-endian Generate big-endian code. off

level

] Debug Include debug information in objects. No debug info

arg...

gcdm, h[elp] Help Display invocation help; terminate. off

directory

I I- | I. I-dash, I-dot Control include-file search order. off ic960 iC-960 Accept iC-960 source dialect. off imacros

filename

include

filename

Format Generate b.out, COFF or ELF object

format.

Fine-Tune Enable or disable an option. Varies with

Decision-maker Invoke gcdm960 decision-maker. off

Searchinclude Search

Macros File Specify macros file for preinclusion. off

Preinclude Prepend text to source files. off

directory

for include files. off

Fbout

mentation

option

2-16

directory

M | MD | MM | MMD

string

nostdinc No Standard

Library Directory

Make Generate make tool output. off

Machine Machine-specific options. Varies with

Include

Specify directory for library search. off

option

Exclude standard include (header) files. off

continued

☛

gcc960 Compiler Driver

Option

nostdlib

O [

level

]

filename

pedantic

[-errors]

save-temps

file

.gld

traditional

trigraphs

macro

v960

W [no-]

arg

directory

Table 2-3 gcc960 Option Summary (continued)

Name Purpose Default

No Standard Libraries

Optimize Specify optimization level. O0 Output Name output file. Varies with

Preprocess Output

Pedantic Controls ANSI error and warning

Assembly Stop after assembly-language output. off Save

Intermediate Target Specify configuration file. off Traditional Allow traditional C. off Trigraphs Support ANSI trigraphs. off Undefine Undefine Version Display version information. No display Version-exit Display version information and exit. off Verbose Display invocation information. No display Warnings Enable/disable a warning. Varies No Warnings Inhibits warnings. off Program

database

Excludes standard libraries. off

Preprocessor output control. off

generation.

Save intermediate files. Do not save

macro

. off

Specify location of program database directory (PDB).

object format

off

G960PDB specifies PDB

2-17

i960 Processor Compiler User's Guide

A (Architecture)

Selects instruction set.

architecture

SA, SB, KA, KB, CA, CF, JA, JD, JF, HA, HD, HT, or RP

is one of:

Default

By default, the compiler uses the i960 KB architecture.

Discussion

Use the A (Architecture) option to specify the target instruction set. See also the generate code that is compatible with multiple i960 processor types.

Note that with release 5.1 using the compatible with current and proposed future variations on the i960 RP architecture.

You can use predefined macros in your source text to conditionally compile code for the selected architecture. The compiler defines a preprocessor macro indicating the selected architecture. The preprocessor macro takes the form:

_ _i960

-mcore0, -mcore1, -mcore2, and -mcore3 options that let you

-ARP option generates code that is

is SA, SB, KA, KB, CA, CF, JA, JD, JF, HA, HD, HT, or

RP. The compiler selects the value of

according to the architecture you specify.

2-18

The

_ _i960 macro is defined for all architecture selections. Use

_ _i960 to identify parts of your program specific to the i960 architecture

but not necessarily specific to a particular processor.

gcc960 Compiler Driver

In addition, for compatibility with earlier releases, macros of the forms:

i960, _ _i960_ _, _ _i960

When you link object modules compiled with incompatible architectures, the linker displays the following warning message:

file

: architecture i960:XX incompatible with output

i960:

xx_ _

and _ _i960_

xx_ _

are defined.

file

ansi (ANSI)

Disable non-ANSI features.

Disables features of gcc960 that are incompatible with ANSI C, such as the

I80960. ansi also enables the ANSI trigraph feature.

See the table shown under the macros defined when the

The alternate keywords continue to function even if you specify ansi. You would not want to use them in an ANSI C program, of course, but it can be useful to put them in header files that might be included in compilations done with

is the first file containing incompatible instructions the linker encounters.

is one of the two-letter architecture abbreviations.

asm, inline and typeof keywords, and nonstandard macros such as

traditional option for a summary of the

ansi or traditional options are used.

_ _asm_ _, _ _inline_ _ and _ _typeof_ _

ansi.

ansi does not cause non-ANSI programs to be rejected with errors. For

that, the

pedantic-errors option is required in addition to ansi.

2-19

i960 Processor Compiler User's Guide

The macro _ _STRICT_ANSI_ _ is predefined when the ansi option is used. Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ANSI standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things.

C (Comments)

Keep comments.

Directs the compiler not to discard comments, and to pass them through to the preprocessor output file. Comments in arguments of a macro call are copied to the output before expansion of the macro call. Used with the option.

c (Create Object)

2-20

Stop after creation of object file.

Directs the compilation system to stop after creating the object file(s). Object files are named by replacing the input filenames. If you specify an object file as input, the compiler does nothing with the file.

clist (Listing)

Creates a listing.

clist

.c, .i, .S, or .s with .o at the end of

arg...

gcc960 Compiler Driver

Generates a listing of the types described below. The list file has the name

filename

arguments are allowed.

s lists the primary source text, that is, source text

i adds source text from included files to the

o adds the assembly language generated by the

m adds expanded preprocessor lines to the primary

c adds conditionally noncompiled source text to

crt (Startup)

.L where filename is the name of the original .C file. Multiple

arg

is one of the following letters:

from files named on the command line.

primary source text listing.

compiler to the listing file.

source text listing.

the primary source text listing.

Omit standard startup file.

Do not use the standard C startup file when linking. A replacement crt file should come first in the list of object files. For all i960 processor types except the RP, the standard startup file is processors, the standard startup file is

D (Define)

Defines a macro.

macro[=value

crt960.o. For i960 RP

crtrp.o.

]

2-21

i960 Processor Compiler User's Guide

With no

macro

=1.)

macro=value

Defines

macro

d (Definitions)

Control macro processing.

• dD Tells the preprocessor to pass all macro definitions into the

output, in their proper sequence in the rest of the output.

•

dM Tells the preprocessor to output only a list of the macro

definitions that are in effect at the end of preprocessing.

•

dN Like dD except that the macro arguments and contents are

omitted. Only

These should be used only with

=value

, defines

value.

#define

macro

as 1. (This is exactly the same as D

macro

is included in the output.

-E, and they affect preprocessor output.

2-22

E (Preprocess)

Run only the C preprocessor.

Directs compilation system to preprocess all the C source files specified and send the results to standard output.

gcc960 Compiler Driver

Fbout | Fcoff | Felf (Format)

Specifies the object file format.

Fbout specifies the b.out object format. This is the

default. You can add the style of symbolic-debug symbols created. Note that you cannot use this option with the architecture setting.

Fcoff specifies the COFF object format, and causes the

assembler to be invoked as gas960c, rather than gas960. You can add the style of symbolic-debug symbols created.

Felf specifies the ELF object format, and causes the

assembler to be invoked as gas960e, rather than gas960. If you add the style of symbolic-debug symbols is used.

g option to specify the

-ARP

g option to specify the

g option, the DWARF

fdb (Database)

Builds optimization database.

All modules subject to program-wide optimization must be initially compiled with the database information in the object modules, and it requires a minimum module-local optimization level of optimization levels are allowed).

fdb option. This option causes the insertion of program

O1 (although higher module-local

2-23

i960 Processor Compiler User's Guide

This option does not otherwise change the code or data generated for the object modules. It simply makes optimization information collected during the initial compilation available to gcdm.

Before using the Analysis and Optimization, and Chapter 6, gcdm Decision Maker Option.

If you intend to use execution profiles when optimizing your application, you should read Chapter 5, Profile Data Merging and Data Format (gmpf960).

fprof (Instrument)

Instruments code for profile creation.

This option inserts execution profile instrumentation code into the code generated during compilation, so that when the linked program is executed, a profile can be collected.

Before using the strategies on using CTOOLS profiling and other optimization features.

This option enables the program database information into the object modules and create the program database. optimization level of O1 (although higher module-local optimization levels are allowed).

fdb option, you should read Chapter 4, Program-wide

fprof option, read Chapters 4 through 6 for general

fdb option, which instructs the compiler to insert

fprof also requires a minimum module-local

2-24

When you use the profile collection ( environment does not support file I/O, you must explicitly link an alternate profiling library ( Chapter 2 of the i960 Processor Library Supplement.

fprof option, a special profiling library required for libqf) is linked automatically. If your target

libq). The profiling libraries provided are described in

gcc960 Compiler Driver

Note that compiling with the fprof option creates object modules useful only for collecting a profile. If you compile with want a profile, you must then use substitutions to replace every instrumented module in the fprof option. See Chapter 4 for more information on this subject.

f (Fine-Tune)

Enable or disable specific options.

In most cases, you will want to optimize code automatically by using the various however, you may want to enable or disable specific features for a given optimization level. For example, at optimization level enable instruction scheduling with optimization process, you should first compile without the option and then recompile with the desired option enabled/disabled. You can then compare the generated assembly code and see if adding/removing the option produced the desired result.

fprof and later do not

prog, or you must recompile the modules without

O optimizations. (See the section on the -O option.) In some cases,

O0, you cannot

fschedule-insns. As with any

Before using any of these options, read chapters 4 through 6 for an overview using the compilation system’s performance features.

f[no-]asm Do [not] recognize asm, inline or

typeof as a keyword. These words can

then be used as identifiers. You can use

_ _asm_ _, _ _inline_ _ and _ _typeof_ _ instead. This option

provides compatibility with strict ANSI standards. See also the

-ansi option.

2-25

i960 Processor Compiler User's Guide

f[no-]bbr Enable/disable basic block

rearrangment. This option is normally used in a second-pass recompilation, but it can also be used in single-pass compilation.

f[no-]coalesce Coalesces memory references into a

single larger memory reference, thus taking better advantage of the i960 processor's burst bus. The compiler only coalesces memory references that can be proven to be contiguous and whose base address can be proven to be aligned properly.

fshadow-mem. f[no-]coerce Enable/disable byte/short optimization. f[no-]cond-mismatch Allow/do not allow conditional

expressions with mismatched types in

the second and third arguments of the

operator. The value of such an

expression is void.

fcoalesce enables

2-26

f[no-]condxform Performs a special conditional

transformation that allows the use of the

i960 Jx, Hx and RP processors' sel<cc>,

addo<cc>, and subo<cc> instructions.

You cannot use this optimization unless

the

, AHx, or ARP option is specified.

f[no-]constprop Performs constant propagation and

folding. This optimization replaces uses

of variables known to have a constant

value with the constant value, allowing

other optimizations to see these

constants and possibly generate more

optimized code.

gcc960 Compiler Driver

f[no-]copyprop Performs copy propagation. This

optimization replaces uses of registers that are destinations of register to register copies with the source register (when possible). This allows unnecessary copies to be deleted later in the compilation.

f[no-]cse-follow-jumps During common subexpression

elimination (CSE), scan through jump instructions in only certain cases. This is not as powerful as completely global CSE, but allows for faster compilation.

f[no-]cse-skip-blocks Enable/disable a limited form of global

CSE.

f[no-]expensive- Perform/skip a number of minor optimizations optimizations that are relatively

expensive. This option is enabled with optimization level

O2.

f[no-]fancy-errors Display/do not display C source line and

caret (

^) with error messages.

f[no-]float-store Store/do not store floating-point

variables in registers, and do not perform common sub-expression elimination on floating point expressions.

f[no-]force-addr Force/do not force memory address

constants to be copied into registers before doing arithmetic on them. This may produce better code.

f[no-]inline-functions Inline/do not inline all simple functions

into their callers. The compiler heuristically decides which functions are simple enough to be worth inlining in

2-27

i960 Processor Compiler User's Guide

this way. When all calls to a given

function are inlined, and the function is

declared static, then the function is

normally not output as assembler code in

its own right.

fint-alias-ptr indicates to the compiler that pointer

objects may be referenced as 32-bit

integers and vice versa.

fint-alias-real indicates to the compiler that float,

double, and long double objects (or

parts thereof) may be referenced as

32-bit integers and vice versa.

fint-alias-short indicates to the compiler that four-byte

integer objects may be referenced as

two-byte objects and vice versa. The aliasing options listed above tell the compiler not to use certain kinds

of type information when disambiguating memory references, even though ANSI section 3.3 “Disambiguation Constraints,” allows this.

2-28

The rules enforced by the aliasing options are transitive. For example, when user code accesses parts of

alias-real

The rules are also applied recursively to say, when pointer type is assumed to be aliased by 32-bit integers or by unions containing 32-bit integers.

Note that ANSI 3.3 requires the compiler to assume that alias all types, so code using these options is not necessary.

Using all three aliasing options effectively disallows all use of type information in memory disambiguation. This is bad both for compiler performance and the efficiency of generated code.

and fint-alias-short should both be used.

fint-alias-ptr is in use, then a union that has a member of

double objects as short, then fint-

structs and unions. That is to

structs or

char references

char pointers is already correct and using

gcc960 Compiler Driver

f[no-]keep-inline- Even when all calls to a given function

functions are inlined, a separate run-time callable

version of the function is still output.

f[no-]marry_mem Rejoin multi-word moves split apart by

fsplit_mem (where possible).

fmix-asm Intermix C code as comments within the

assembly code.

f[no-]rerun-cse- Re-run common subexpression after-loop elimination after loop optimizations

have been performed.

f[no-]sblock Enable/disable superblock formation.

This option is normally used in a second-pass recompilation, but it can also be used in a single-pass compilation.

fsigned-char | Make the type char be signed, like fno-signed-char signed char (fsigned-char), or

make the type

unsigned char (fno-signed-char). fsigned-char is equivalent to fnounsigned-char

char be unsigned, like

By default,

unsigned.

f[no-]schedule-insns Attempt to reorder instructions to

eliminate execution stalls due to required data being unavailable. This allows other instructions to be issued until the result of a previously issued instruction is required.

char variables are treated as

2-29

i960 Processor Compiler User's Guide

This option makes debugging more

difficult, since the code for multiple C

statements may become intermixed,

causing execution to make numerous

jumps while single-stepping.

f[no-]schedule-insns2 Similar to fschedule-insns, but it

requests an additional pass of instruction

scheduling after register allocation has

been done.

f[no-]shadow-globals Shadow memory locations with global

Memory locations that are known not to

change are temporarily allocated to

registers. This option makes debugging

more difficult, since objects allocated in

memory may not always be up-to-date.

f[no-]shadow-mem Shadow memory locations with register

variables where possible. Memory

references whose addresses are known

to be the same are temporarily allocated

to registers. This option makes

debugging more difficult, since objects

allocated in memory may not always be

up-to-date.

fshadow-globals, but its analysis is

considerably more sophisticated. In

most cases,

optimization than

but compile time is slower.

fshadow-mem is similar to

fshadow-mem allows more

fshadow-globals,

2-30

f[no-]space-opt Optimize to reduce the size of the

generated code.

gcc960 Compiler Driver

f[no-]split_mem Split all multi-word moves into

sequences of single word moves to improve copy propagation.

funsigned-char | Make the type char be unsigned, like unsigned char (funsigned-char), or make the type

char be signed, like signed char (fno-unsigned-char) char

is equivalent to fnosigned-char.

. funsigned-

By default,

unsigned.

f[no-]strength-reduce Perform loop strength reduction and

eliminate induction variables. See the Glossary for more information.

fsyntax-only Check the syntax of C source file(s),

without generating an object file.

f[no-]thread-jumps Test whether a jump branches to a

location where another comparison subsumed by the first is found. If so, the first branch is redirected to either the destination of the second branch or to a point immediately following it, depending on whether the condition is known to be true or false.

f[no-]unroll-all-loops Perform the optimization of loop

unrolling on all loops. This is not recommended as it increases code size and usually degrades runtime performance. enables both fstrength-reduce and

frerun-cse-after-loop.

char variables are treated as

funroll-all-loops

f[no-]unroll-loops Break up a loop into several iterations of

the loop body. This typically improves performance, since the loop's exit

2-31

i960 Processor Compiler User's Guide

condition is not checked for each

iteration. In a few cases, however, the

increased code size may decrease

performance.

This option uses several decision criteria

determine how far to unroll a loop. For

example, when the loop body is small

and there are relatively few iterations, it

may choose to completely unroll the

loop. For loops with larger bodies and

more iterations, it may partially unroll

the loop and change the increment

counter accordingly.

enables both fstrength-reduce and

frerun-cse-after-loop. f[no-]volatile Consider/do not consider all memory

references through pointers to be

volatile.

funroll-loops

2-32

f[no-]volatile-global Consider/do not consider all references

to global variables to be volatile.

f[no-]writable-strings Store/do not store string constants in the

writable data segment and make them

unique. This is for compatibility with

old programs that assume they can write

into string constants.

gcc960 Compiler Driver

G (Big-endian)

Generate big-endian code.

Compile for a target that uses big-endian memory. This option requires that

Fcoff or Felf be in effect. This option is also passed to

gas960c/gas960e and gld960. When symbol

__i960_BIG_ENDIAN__ is defined.

g (Debug)

Specifies debug information.

g [

level

G is specified, the preprocessor

]

where

level

specifies the amount of debug information. Note that the meaning of level varies depending on the object format in use, as described below.

Using

g0 disables debug information. (This is the same as not using the g

option.) For b.out and COFF, debug level settings of

same effect: they specify “normal” debug information. When the default object-file format (b.out) is selected, DBX-style

symbolic debug directives suitable for use only with gdb960 are output. For ELF/DWARF, debug level settings of

effect: they specify all DWARF debug information except preprocessor macros.

g, g1, g2, and g3 all have the

g, g1, and g2 all have the same

2-33

i960 Processor Compiler User's Guide

For ELF/DWARF, a debug level setting of g3 specifies all DWARF debug information, including preprocessor macros in the debug information. If your debugger (like gdb960) does not make use of preprocessor macro information, you can save space in your object files by dropping to ELF/DWARF debug level 2.

The

g (Debug) option does not inhibit optimization. When you specify the

g option but do not specify the O (Optimize) option, the optimization level

defaults to

O0.

Specifying an optimization level higher than effectiveness of the symbolic debug information. For example, if you set a breakpoint on a source line that has been removed during optimization, the breakpoint is never hit. Or if you try to print the value of a variable that has been optimized away, an erroneous value is displayed. In general, as the optimization level increases, the reliability of the symbolic debug information decreases.

When you are using the ELF object module format ( compiler to produce DWARF debug information. This debug information format is richer than that of other supported OMFs, and allows more reliable debugging under optimization. However, even with DWARF, there are situations where debugging behavior does not agree with the debugging behavior of unoptimized code.

gcdm,

Invoke gcdm960 optimization decision maker.

arg[,arg

gcdm,

]... (Decision Maker)

arg[,arg

]...

O0 can inhibit the

Felf), g causes the

2-34

The gcdm option provides a high level of automation for whole-program or profile-driven optimization processes. The compiler driver and the linker both use the gcdm option and its arguments.

gcc960 Compiler Driver

The gcdm option is flexible and powerful, and therefore requires a certain level of understanding in order to use it effectively. For these reasons, it is documented in a separate chapter (Chapter 6) in this manual. Before using the gcdm option, you should read Chapter 4, Program-wide Analysis and Optimization, and become familiar with the information in Chapter 5, Profile Data Merging and Data Format (gmpf960).

I (Searchinclude)

Specifies include file directory.

directory

Adds

directory

header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. When you use more than one the directories are scanned in left-to-right order; the standard system directories come after.

to the end of the list of directories to be searched for

I option,

I- | I. (Include-dash, Include-dot)

Controls search order and paths.

I- | I.

Any directories specified with I options before the I- option are searched only for

When additional directories are specified with directories are searched for all directories are searched this way.)

#include "

file

"; they are not searched for #include <

#include directives. (Ordinarily all I

file

I options after the I-, these

2-35

i960 Processor Compiler User's Guide

The I- option inhibits the use of the current directory as the first search directory for

#include "

is not searched automatically with you to control which directories are searched before the current one and which are searched after.

#include "

file

" only when it is requested explicitly with I. (I"dot"). It

file

". The current directory is searched for

ic960 (iC-960 Compatibility)

Accept iC-960 source dialect.

Accept the same C dialect as ic960 R3.0 or later. Note that this does not make the generated code compatible. To make the generated code compatible, the

mic3.0-compat option is necessary.

I-. Specifying both I- and I. allows

2-36

imacros (Macros File)

Specifies macros file.

imacros

Process the regular input file. Because the output generated from discarded, the only effect of in

file

command line are always processed before the order in that they are written. All the are processed in the order in that they are written. All are processed before all

file

as input, discarding the resulting output, before processing

available for use in the main input. Any D and U options on the

imacros

include options.

file

is to make the macros defined

imacros

include and imacros options

file

, regardless of

imacros options

gcc960 Compiler Driver

include (Preinclude File)

Specifies file for preinclusion.

include

Process the contents of command line are always processed before the order in that they are written. All the are processed in the order in that they are written. All are processed before all

j (Errata)

Specifies processor errata.

Use the j (Errata) option to cause the compilation system to generate code with workarounds for specified processor errata. A generates code to work around the Cx processors' DMA errata.

num

file

as input before processing the regular input file. In effect,

file

are compiled first. Any D and U options on the

include

include and imacros options

include options.

file

, regardless of

imacros options

num

argument of 1

L (Library Directory)

Specifies directory for library search.

directory

2-37

i960 Processor Compiler User's Guide

Adds your utilities user's guide for a complete explanation of the directory search order.

l (Library)

Specifies library for linking.

library

Search a standard list of directories for a library file named

lib

precisely by name.

directory

library

to the list of directories to be searched for libraries. See

.a. The linker uses this file as if it had been specified

Several standard directories are searched, plus any that you specify with Normally the files found this way are library files — archive files whose

members are object files. The linker handles an archive file by scanning through it for members that define symbols that so far have been referenced but not defined. However, when the file found is an ordinary object file, it is linked in the usual fashion. The only difference between using an directories. Under normal operation, gcc960 supplies the options and option

l option and specifying a filename is that l searches several

lqf, lc,

lm to the linker. For architectures without floating-point support, the

lh is also passed to the linker.

2-38

gcc960 Compiler Driver

M | MD | MM | MMD (Make)

Generate make tool output.

M Tells the preprocessor to output a rule suitable

for a make tool describing the dependencies of each source file. For each source file, the preprocessor outputs one make rule whose target is the object filename for that source file and whose dependencies are all the files in it. This rule can be a single line or can be continued with option stops compilation after preprocessing.

MM Like M, but the output mentions only the user-

header files included with System header files included with

file

\newline if it is long. Using this

> are omitted.

#included

#include "

#include

file

NOTE. Previous versions of this manual described the MD and options. In fact, these options function identically with the M and options respectively. To maintain compatibility with make files from previous versions of gcc960, these options are still accepted on the command line.

m (Machine-specific Options)

Various options.

string

Specifies a machine-specific option.

MMD

2-39

i960 Processor Compiler User's Guide

mabi Generate 80960 ABI-conformant code. This

causes the four bytes in size and signed, and changes default alignment rules for structs and unions. See Chapter 7 for more information.

masm-compat Generate special Intel pseudo-operations for long

compare-and-branch operations. gas960, gas960c, or gas960e do not require these pseudoops in order to generate correct code, but the ASM960 R3.5 or earlier assembler generates out-of-range errors for these instructions when this option is not used. This should not be used with gas960, gas960c, or gas960e, because the split compare-and-branch instructions are slower and larger than the combined ones.

mcave Generate all functions as CAVE secondary.

When you select special CAVE entries for all functions in the compilation unit. This prepares the functions for link-time compression. The cave entries resemble the following:

char type to be signed, enums to be

mcave, the compiler generates

2-40

.section .text _foo: lda L1,reg call __dispatcher ret

.section cave .word L2-L1,0

L1:

function body

L2:

gcc960 Compiler Driver

Can Be Used With

-AJA, -AJD, -AJF, -AHA,

-AHD, -AHT, or -ARP

Any architecture option

except -ARP

-AJA, -AJD, -AJF, -AHA,

-AHD, or -AHT

-ACA, -ACF, -AJA, -AJD,

-AJF, -AHA, -AHD, or

-AHT

At runtime, the dispatcher decompresses the function bodies and transfers control to them. This mechanism saves runtime memory.

See the discussion of for information on this option.

mcmpbr | mno-cmpbr Generate/do not generate code that uses

compare-and-branch instructions whenever possible.

mcode-align | Generate/do not generate alignment directives mno-nocode-align prior to labels that are not entered from above.

mcode-align is the default when the Cx or Hx

architecture is specified.

mcore0 | mcore1 | generate code that is compatible with multiple mcore2 | mcore3 | i960 processor types. Additionally, when you

use an

-mcore option, you can include another

-A switch to generate code that is optimized for a

particular architecture, but still compatible with a group of architectures. The table below lists the architectures that are supported by each option and the -A options that you can use with them.

Table 2-4 Mcore Supported Architectures

Option Name Compatible Architectures

Mcore0 Jx, Hx, RP

#pragma cave in Chapter 7

-mcore

Mcore1 Kx, Sx, Cx, Jx, Hx

Mcore2 Jx, Hx

Mcore3 Cx, Jx, Hx

2-41

i960 Processor Compiler User's Guide

mdouble4 Generate code so that the size and alignment of

double is the same as float.

mlong-double4 Generate code so that the size and alignment of

long double is the same as float.

NOTE. The mdouble4 and mlong-double4 options force floating-point arguments to be passed in single-precision format. When your source program explicitly calls functions (such as double-precision or extended-precision arguments, the arguments passed to these functions are incorrect.

sin and printf) that require

mi960_align=

mic-compat Use ic960 R2.0's rules for size and alignment of mic2.0-compat types. This option also causes the compiler to

mic3.0-compat Use ic960 R3.0's rules for size and alignment of

mleaf-procedures | Generate/do not generate output that contains mno-leaf-procedures leaf procedures: these are procedures that may be

Aligns struct data on the byte boundary that is a multiple of

use the ic960 compiler's rules for promotion of

char, unsigned char, short, and unsigned short

types and other conventions. These are largely the same as gcc960's, but ic960 R3.0 selects the size of ic960 R3.0 assumes that type char is signed by default, whereas gcc960 assumes it is unsigned.

mic3.0-compat option emulates ic960's

The behavior.

entered with the

call. The linker automatically promotes call

instructions into bal instructions when

. (Legal values are 1, 2, 4, 8, 16.)

types at function call and return.

enums based on their value. Additionally,

bal instruction rather than

2-42

gcc960 Compiler Driver

appropriate. This option makes debugging more difficult.

O2 or higher.

mlong-calls Generate all call instructions as calljx instead

callj. This is used where the distance

of between the call site and the called function may exceed degrades code execution speed and increases code size.

mpic Generate position-independent references to any

objects in the text section. Such objects are functions, tables, and strings. Position independent code references are made relative to the current instruction pointer (IP).

mpid Generate position-independent references to

objects in the bss, common, and data sections. Such objects are nonand strings when the option is used. Position independent data references are made relative to register Register

mleaf-procedures is the default at

callj's range. Using this option

const file-scope variables, switch

const file-scope variables,

fwritable-strings

g12.

g12 is not used for any other purpose.

mpid-safe Reserve register g12 as the position independent

data bias register, but do not generate code for position independent data.

msoft-float Generates output containing library calls for

architectures without on-chip floating point support (all except KB, SB). This is set automatically, based on the architecture option.

mstrict-align | This option determines whether or not the mno-strict-align compiler risks generating memory references

that are not provably aligned. When

align

is disabled, the compiler occasionally

mstrict-

2-43

i960 Processor Compiler User's Guide

generates potentially unaligned references when it seems advantageous to do so. When

mstrict-align is enabled, sequences of

smaller memory references are used instead of larger ones that might not be correctly aligned. The default is on for C-series and J-series processors.

mstrict-ref-def Generate code so that an uninitialized file-scope

variable definition causes space to be allocated in the

.bss section instead of as a .comm symbol.

This enforces a single unique definition of a variable.

mtail-call | Generate output that converts (does not mno-tail-call convert) call instructions immediately followed

ret instructions to branches to the call target.

While generating faster code, this option makes debugging more difficult. default at

O2 or higher.

mtail-call is the

2-44

mwait=

Specifies the expected number of wait-states for the memory being used in the target. This can make a difference in which optimizations are cost-effective and in the instruction scheduling optimization.

must be in the range 0.32.

nostdinc (No Standard Header Files)

Do not use standard header files.

Do not search the standard system directories for header files. Only the directories specified with appropriate) are searched. Using directories from the search path except those you specify.

I options (and the current directory, when

nostdinc and I-, you can eliminate all

gcc960 Compiler Driver

nostdlib (No Standard Libraries)

Do not use standard libraries.

Excludes standard libraries.

O (Optimize)

Specifies optimization level.

level

]

The O[ below.

O0 Turns optimization off, and additionally disables

O or O1 These options enable basic optimizations,

level

] option specifies the level of optimization as described

default optimizations that may interfere with debugging. This is the default.

including: advanced register allocation, common subexpression elimination, loop invariant code motion, expression simplification and instruction combination, jump optimization, dead-code elimination, and i960 processor-specific peephole optimization. This is the default setting when you use the (Program Database) or fprof (Instrument) option.

O1 is equivalent to O.

fdb

2-45

i960 Processor Compiler User's Guide

O2 This level includes the O or O1 optimizations

described above, and the following additional optimizations:

fcopyprop, fcondxform, fcse-followjumps

, fcse-skip-blocks, fexpensive-

optimizations fschedule-insns, fschedule-insns2, fshadow-globals, fstrength-reduce.

The

O2 level enables strength-reduction,

combination of more than one variable value into a single register, copy propagation, tail-call elimination, leaf-procedure optimization, and instruction reordering (scheduling) to make use of the particular i960 processor's pipeline and superscalar capabilities.

O3 This level includes the O2 optimizations

described above, and the following additional optimizations:

, frerun-cse-after-loop,

2-46

fcoerce, fconstprop, finline-functions, fshadow-mem, funroll-loops.

O4 This level includes the O3 optimizations

described above, and the following additional optimizations:

fcoalesce, fmarry_mem, fsplit_mem.

O5 This setting specifies program-wide

optimization. Before using the should read Chapter 4, Program-wide Analysis and Optimization, and Chapter 6, gcdm Decision Maker Option.

Note that the the gcc960 driver. It is accepted only in the

subst argument of the gcdm option.

O5 level is not accepted directly by

O5 option, you

gcc960 Compiler Driver

o (Output)

Specifies output filename.

filename

Specifies output filename.

P (Preprocessor Output)

Preprocessor output control.

Inhibits generation of #-lines with line-number information in the output from the preprocessor. This is useful when running the preprocessor on non-C code that is intended for a program that might be confused by the

#-lines.

pedantic[-errors] (Pedantic)

Controls ANSI messages

pedantic causes the compilation system to issue all the warnings

specified by ANSI C (such as when text other than a comment follows

#else or #endif) and to reject programs that use forbidden extensions.

Valid ANSI standard C programs should compile properly with or without this option (though a rare few require option, certain GNU extensions and traditional C features are supported as well. With this option, they are rejected.

ansi). However, without this

2-47

i960 Processor Compiler User's Guide

pedantic does not cause warning messages for use of the alternate

keywords whose names begin and end with

pedantic-errors is the same as pedantic, except that it causes the

compilation system to issue errors instead of warnings.

S (Assembly)

Create assembly output.

Compile into assembly code but do not assemble. The assembly output filename is made by replacing filename. Do nothing for assembly source files or object files specified as input.

.c or .i with .s at the end of the input

save-temps (Save Intermediates)

_ _ (double underscore).

2-48

Save intermediate files.

Store the usual "temporary" intermediate files permanently; place them in the current directory and name them based on the source file. Thus, compiling

foo.s, as well as foo.o.

foo.c with -c -save-temps would produce files foo.i and

gcc960 Compiler Driver

T (Target)

Specifies .gld file.

string

Causes gcc960 to configure itself for a specific target board.

traditional (Traditional)

Allow traditional C.

Attempt to support some aspects of traditional C compilers, specifically:

• All

• The keywords

• Integer types

• All automatic variables not declared

• In the preprocessor, comments convert to nothing at all, rather than to

• In the preprocessor, macro arguments are recognized within string

extern declarations take effect globally even when they are

written inside of a function definition. This includes implicit declarations of functions.

typeof, inline, signed, const, and volatile are

not recognized.

unsigned short and unsigned char promote to

unsigned int.

longjmp. Ordinarily, GNU C follows ANSI C: automatic variables

not declared

a space. This allows traditional token concatenation.

constants in a macro definition (and their values are stringified, though without additional quote marks, when they appear in such a context). The preprocessor always considers a string constant to end at a newline.

volatile may be clobbered.

where

string

configuration file,

identifies a target-specific

string.

gld.

2-49

i960 Processor Compiler User's Guide

• The predefined macro _ _STDC_ _ is not defined when you use

traditional, but _ _GNUC_ _ is (since the GNU extensions that _ _GNUC_ _ indicates are not affected by traditional). When you

need to write header files that work differently depending on whether

traditional is in use, by testing both of these predefined macros

you can distinguish four situations: GNU C, traditional GNU C, other ANSI C compilers, and other C compilers.

The following table summarizes the macros defined when the

traditional or ansi option is used.

_ _STRICT_ANSI_ __ _STDC_ __ _GNUC_ _

traditional X ansi X X X none X X

2-50

trigraphs (Trigraphs)

Support ANSI C trigraphs.

Process ANSI standard trigraph sequences. These are three-character sequences, all starting with single characters. For example, constant for a newline.

The

ansi option also enables trigraphs.

??, that are defined by ANSI C to stand for

??/ stands for \, so ’??/n’ is a character

gcc960 Compiler Driver

U (Undefine)

Undefines a preprocessor macro.

macro

Undefines the named preprocessor macro.

V (Version)

Display tool version numbers.

v (Verbose)

Display tool version numbers and subprocess commands.

v960 (Version, exit)

Display tool version numbers and exit.

2-51

i960 Processor Compiler User's Guide

W (Warnings)

Enables / disables specific warnings.

string

]

With no arguments, this option prints extra warning messages for certain events, including:

longjmp() warnings

Warn when a nonvolatile automatic variable might be changed by a call to These warnings are possible only in an optimizing compilation.

The compiler sees only the calls to cannot know where a signal handler could call it at any point in the code. As a result, you may get a warning even when there is in fact no problem because

longjmp() cannot actually be called at the place

that would cause a problem.

return and return(

Warn when a function can return either with or without a value. (Falling off the end of the function body is considered returning with a value.)

null effect

Warn when an expression-statement contains no side effects.

longjmp() is called; in fact

value

longjmp().

setjmp(). It

)

2-52

no-op comparison

Warn when an unsigned value is compared against zero with

< or <=.

gcc960 Compiler Driver

between-ness comparison

Warn when a comparison like this is equivalent to which is a different interpretation from that of ordinary mathematical notation.

obsolete storage class specification

Warn when storage-class specifiers like are not first in a declaration. According to the ANSI C standard, this usage is obsolescent.

partially bracketed initializer

Warn when an aggregate has a partially bracketed initializer.

Wall Enable the following warning options: W, Wchar-

subscripts type

, Wswitch, Wtrigraphs,

Wuninitialized, Wunused. There is no Wnoall

option.

Waggregate-return Warn when any functions that return structures

or unions are defined or called.

, Wcomment, Wformat, Wreturn-

{(x<=y ? 1 : 0) <=z},

x<=y<=z is used;

static

Wcast-align Warn whenever a pointer is cast such that the

required alignment of the target is increased. For example, warn when a on machines where integers can be accessed only at two- or four-byte boundaries.

Wcast-qual Warn whenever a pointer is cast so as to remove

a type qualifier from the target type. For example, warn when a an ordinary

char *.

char * is cast to an int *

const char * is cast to

2-53

i960 Processor Compiler User's Guide

Wchar-subscripts Warn when an array subscript has type char.

This is a common cause of error, as programmers often forget that this type is signed on some machines.

Wcomment Warn whenever a comment-start sequence /*

appears in a comment.

Wconversion Warn when a prototype causes a type conversion

different from what would happen to the same argument in the absence of a prototype. This includes conversions of fixed point to floating and vice versa, and conversions changing the width or signedness of a fixed point argument, except when these are the same as the default promotion.

Werror Make all warnings into errors. Wformat Check calls to printf and scanf, etc., to make

sure that the arguments supplied have types appropriate to the specified format string.

2-54

Wid-clash-

Wimplicit Warn when a function is used without being

Wmissing-braces Warn when an initializer is not completely

len

Warn whenever two distinct identifiers match in the first prepare a program that compiles with certain obsolete compilers. There is no this option.

explicitly declared.

enclosed within braces.

len

characters. This may help you

[no-] form of

gcc960 Compiler Driver

Wmissing-prototypes Warn when a global function is defined without a

previous prototype declaration. This warning is issued even when the definition itself provides a prototype. The aim is to detect global functions that are not declared in header files.

Wnested-externs Warn when an extern declaration is

encountered within a function.

Wparentheses Warn when parentheses are suggested around an

expression.

Wpointer-arith Warn about anything that depends on the size of

a function type or of types a size of 1, for convenience in calculations with

void* pointers and pointers to functions.

Wredundant-decls Warn when anything is declared more than once

in the same scope, even in cases where multiple declaration is valid and changes nothing.

Wreturn-type Warn whenever a function is defined whose

return-type defaults to

return statement with no return-value in a

function whose return-type is not

void. gcc960 assigns these

int. Also warn about any

void.

Wswitch Warn whenever a switch statement has an

enumeral type index and lacks a more of the named codes of that enumeration.

Wshadow Warn whenever a local variable shadows another

local variable.

case for one or

2-55

i960 Processor Compiler User's Guide

Wstrict-prototypes Warn when a function is declared or defined

without specifying the argument types. An oldstyle function definition is permitted without a warning when it is preceded by a declaration specifying the argument types.

Wtraditional Warn about certain constructs that behave

differently in traditional and ANSI C:

• Macro arguments occurring within string

constants in the macro body. These would substitute the argument in traditional C, but are part of the constant in ANSI C.

• A function declared external in one block

and then used after the end of the block.

• A

switch statement has an operand of type

long.

Wtrigraphs Warn when any trigraphs are encountered

(assuming they are enabled).

Wuninitialized An automatic variable is used without first being

initialized. These warnings are possible only in an optimizing compilation, because they require data flow information that is computed only when optimizing. When no these warnings are not generated.

O option is given,

2-56

These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared

volatile, or whose address is taken, or whose

size is other than 1, 2, 4, or 8 bytes. Also, they do not occur for structures, unions, or arrays, even when they are in registers.

gcc960 Compiler Driver

There may be no warning about a variable that is used only to compute a value that itself is never used, because such computations can be deleted by data flow analysis before the warnings are printed.

These warnings are optional because gcc960 cannot foresee all the reasons why the code might be correct despite appearing to have an error. Here is one example of how this can happen:

{ int x; switch (y) { case 1: x = 1; break; case 2: x = 4; break; case 3: x = 5; } foo (x); }

When the value of y is always 1, 2 or 3, then x is always initialized, but gcc960 doesn’t know this. Here is another common case:

{ int save_y; if (change_y) save_y = y, y = new_y; ... if (change_y) y = save_y; }

2-57

i960 Processor Compiler User's Guide

Wunused Warn whenever a local variable is unused aside

Wwrite-strings Give string constants the type const

w (Inhibit Warnings)

Inhibits all warnings.

This has no bug because save_y is used only when it is set.

Some spurious warnings can be avoided if you declare as volatile all the functions you use that never return.

from its declaration, and whenever a function is declared

char[

one into a nonwarning.

static but never defined.

length

] so that copying the address of

const char* pointer generates a

2-58

Z (Specify PDB)

Specifies PDB directory.

directory

Specifies the name of the program database (PDB) directory. Before using this option, you should read Chapter 4, Program-wide

Analysis and Optimization, Chapter 5, Profile Data Merging and Data Format (gmpf960), and Chapter 6, gcdm Decision Maker Option.

ic960 Compiler Driver

This chapter describes how to use the ic960 driver program to control the compilation system. This chapter also explains how to:

• invoke the compiler with the ic960 command-line options

• modify compiler operation using environment variables

• write a program that uses macros defined by the compiler

• use the ic960 driver to produce an output file

Controlling the Compilation System with ic960

iC-960-style translation and linking requires use of the ic960 driver, preprocessor, compiler, assembler, and linker. The ic960 driver:

•

invokes the preprocessor for C source text

•

invokes the compiler to check syntax of C source text and generate

assembly language

• manages the subsequent assembly and linking of a program Command-line options and environment variables allow you to control the

compilation.

3-1

i960 Processor Compiler User's Guide

Invoking the Compiler with ic960

The ic960 command-line syntax is:

ic960 [-

option

]... [

path]filename

...

ic960

option

path

NOTE. Although Windows pathnames require backslashes (\), this manual shows paths using the forward slash required by UNIX (

is the compiler driver executable filename. is a compiler option. Case is significant in

options and their arguments. On UNIX, the compiler driver recognizes a letter

preceded by a hyphen ( Windows, the driver recognizes a letter preceded by either a hyphen (

For a complete description of the ic960 options, see the ic960 Option Reference section. You can also use linker invocation options in an ic960 command; see Table 3-1 for a summary of these options.

identifies the directory containing the file named by

filename

directory. Each directory requires a separate specification of

path

. Not specifying

causes ic960 to search in the current

-) as an option. In

-) or a slash (/) as an option.

path

for a

filename

not in the current

3-2

ic960 Compiler Driver

filename

Table 3-1 lists the linker options that ic960 passes directly to the linker. To pass other options to the linker, use the

is the name of a source, assembly-language, or object file to be processed by the compilation system. The command line allows specification of more than one

[

path/]filename

Wl,

arg

pass-through option.

ic960 Sample Command Lines

This section provides examples of how the compiler is commonly invoked. All these examples assume that you have C source files named

t2.c and that you are generating code for the i960 CA architecture.

Preprocessing a Source File

To preprocess a source file, use the command:

ic960 -E t1.c

-E

informs the compiler to preprocess the source

file and echo the output to stdout.

Generating Assembly

To generate assembly code for the i960 CA architecture, use the following command.

t1.c and

ic960 -S -ACA t1.c

-S

instructs the compiler to generate assembly code.

-A specifies the i960 CA architecture.

3-3

i960 Processor Compiler User's Guide

Generating an Object Module with Debug Information

To generate a object module with debug information, use the following command.

ic960 -c -g -ACA t1.c

-g

instructs the compiler to generate debug

information.

-c instructs the compiler to generate an object file.

Generating an Executable

To generate an absolute module (executable file) for a Cyclone board with a CA processor, use the following command.

ic960 -ACA -Tcycx -g -O1 t1.c t2.c -o test

The above command compiles the modules t1.c and t2.c and links them with appropriate libraries to generate an absolute module targeted for a Cyclone i960 Cx board.

-Tcycx instructs the compiler that you are targeting a

Cyclone i960 Cx board.

3-4

-O1 causes the compiler to perform some basic

optimizations on the generated code.

-o instructs the compiler to name the generated

executable test.

ic960 Linker Options

When you do not specify a target with the T not attempt to link programs for a specific target board. Unless otherwise specified, following linker command is issued:

lnk960 -AKB

.c and .s files are compiled and/or assembled, and the

file

.o... -lqf

target

option, ic960 does

ic960 Compiler Driver

ic960 links in the profiling library (-lqf) by default. To avoid linking in the profiling library, invoke lnk960 directly to perform your final link. You can also link in your own libraries (lib1, lib2...) if needed.

lnk960 -AKB

You can invoke ic960 to create object files in either the COFF or ELF object module format. The compilation system accepts the to generate COFF and the

Fcoff is the default. For more detailed information, see the following

discussions of compiler invocation and options.

Table 3-1 Linker Options Accepted by ic960

Option Name Description

l Archive file specifies an archive file as input. x Compress removes local symbols from the output

L Library search adds directories to search for libraries,

m Map creates a linker memory map file. r Relocation retains relocation information in the output

s Strip strips line-number entries and symbol-table

T Target specifies the file describing the target

u Undefine introduces an unresolved symbol, causing the

file

.o... -llib1 -llib2

Felf option to generate ELF.

symbol table.

configuration files, and startup object files.

object file.

entries from the linker's COFF output file.

environment.

linker to search symbol tables for resolution of the reference.

Fcoff option

gcdm Decision Maker invokes gcdm960 decision maker.

For more information on the linker, see the i960 Processor Software Utilities User’s Guide.

3-5

i960 Processor Compiler User's Guide

ic960 and Predefined Macros

The following macros are available in accordance with the ANSI standard for C, as described in the book, C: A Reference Manual:

__DATE__ __FILE__ __LINE__ __TIME__ __STDC__

The following macros are predefined by the compilation system when invoked with the ic960 driver program:

__IC960 indicates the CTOOLS960 compilation system.

__IC960_VER is defined to a decimal number that can be used

U (Undefine) option can remove i960 processor-specific

The compiler defines when invoked with the ic960 driver.

to check the version number of the compiler. The number is expressed in decimal as

MmmPPPP mm

is the minor version number, and internal version number that is used to track the patch level. So, for example, R4.5 patch level 4008 has

, where M is the major version number,

__IC960_VER defined to be 4054008.

__IC960 automatically,

PPPP

is an

3-6

__i960 indicates the i960 processor environment. The

compiler defines macro can be used to identify the parts of a program specific to the i960 processor.

__i960 automatically. This

ic960 Compiler Driver

__i960

__PIC indicates that the generated code is position-

__PID indicates that the generated data is position-

__i960_BIG_ENDIAN__ indicates that the generated code is arranged for

__STRICT_ANSI__ indicates that C constructs not conforming to the __STRICT_ANSI ANSI standard should be flagged. The a (ANSI)

indicates the i960 processor instruction set in use. The compiler automatically defines the

__i960 KA, KB, RP, SA, SB, JA, JD, or JF. Definition of

instruction set specified by the option or the

independent. The independent-code) option causes the macro to be defined.

independent. The independent-data) option causes the macro to be defined.

big-endian address space. The (Generate-big endian) option causes this macro to be defined.

option causes these macros to be defined.

macro. The xx is CA, CF, HA, HD, HT,

depends on the specific i960 processor

A (Architecture)

I960ARCH environment variable.

G pc (Generate-for-position-

__PIC

G pd (Generate-for-position-

__PID

G be

__SIGNED_CHARS__ indicates that the plain char type are treated like

the

signed char type. This is the default.

__CHAR_UNSIGNED__ indicates that the plain char type are treated like

the

unsigned char type. The G cu (Generate-

char-unsigned) option causes this macro to be defined instead of

__SIGNED_CHARS__.

3-7

i960 Processor Compiler User's Guide

ic960 and Environment Variables

Environment variables specify default directories for input files, temporary files, libraries, the assembler, and the linker. In addition, the

I960ARCH environment variable specifies the default architecture. The

compilation system uses the following environment variables to set defaults:

I960ARCH specifies an architecture other than the i960 KB

processor for code generation. The possible definitions for

KA, KB, RP, SA, SB, JA, JD, or JF. The A

(Architecture) option overrides the architecture specified in

I960ARCH and the Architecture option, the

compiler selects the i960 KB processor architecture.

I960BASE contains the pathname of the top-level directory

containing the files and directories needed by the compiler. This environment variable is necessary for every phase of compilation. The driver uses compiler, assembler, linker, and include files.

I960ARCH are CA, CF, HA, HD, HT,

I960ARCH. In the absence of

I960BASE to find the preprocessor,

3-8

To invoke the preprocessor and compiler, the ic960 driver looks in the

I960BASE.

To invoke the assembler and linker, the driver looks in the specified by

To find include files, the driver looks in the

include directory under the directory specified

I960BASE.

bin directory under the directory

I960BASE.

lib directory under

ic960 Compiler Driver

The linker looks for libraries, startup modules, and configuration files in the the directory specified by

I960AS specifies a non-default pathname for the

assembler. The pathname must include the name of the executable. In the absence of ic960 looks for the assembler in directory specified by

I960CPP specifies an alternate name for the preprocessor.

The default pathname is

I960BASE/lib/cpp.960 on UNIX or cpp.exe

in Windows.

I960CC1 specifies an alternate name for the compiler.

The default pathname is

I960BASE/lib/cc1.960 or cc1.exe in

Windows.

I960DM specifies an alternate name for the gcdm960

optimization decision maker.

lib directory under

I960BASE.

I960AS,

bin under the

I960BASE.

I960ERR The assembler, linker, and other tools can

redirect errors to the standard error stream (

stderr). To use this capability, set the

Windows environment variable string, as in:

SET I960ERR="Enable stderr"

Leaving I960ERR unset directs error output to the standard output stream (

I960INC specifies a non-default pathname for the

directory containing include files. In the absence of

I960INC, the driver looks for include files in

the

include directory in the directory specified

under

I960BASE.

I960ERR to any

stdout).

3-9

i960 Processor Compiler User's Guide

I960LIB, I960LLIB contain additional pathnames of libraries.

Definition of search for libraries in the directory specified by

I960LIB. In the absence of I960LIB, the linker

searches the specified by causes the linker to search the directory specified by

I960LLIB before searching the lib directory

in the directory specified by complete description of the search algorithm used by the linker, see the i960 Processor Software Utilities User's Guide.

I960LD contains an alternate pathname of the linker. The

path must include the name of the executable. In the absence of in the

bin directory under the directory specified

I960BASE.

I960PDB defines the location of the program database for

use with profile-driven optimizations. The (Program Database) option overrides this environment variable and allows specification of an alternate database directory.

I960LIB causes the linker to

lib directory in the directory I960BASE. Definition of I960LLIB

I960BASE. For a

I960LD, ic960 looks for the linker

3-10

TEMP, TMP, TMPDIR, contain the pathname of the directory used for G960TMP compiler temporary work files. In the absence of

these variables, the compiler attempts to write temporary work files to the current working directory in Windows, and to on Unix.

/tmp or /usr/tmp

ic960 Compiler Driver

ic960 and File Use

The compiler, assembler, and linker all use filenames specified on the ic960 command line to find and create input and output files. In addition, translation and linking require temporary work files. Environment variables allow specification of default directories for work files.

Input Files

The ic960 command line allows filename inputs that support specification of assembly-language files, preprocessed source files, C source files, object files, and libraries. The compiler driver determines the type of each input file by the filename extension, as follows:

filename

filename filename

The driver passes any other filename to the linker. The linker then determines whether the file is an object file, library, or configuration file.

Input files not needed for processing are not processed. For example, if you specify an assembly-language (

S (Save assembly) stop-after option, ic960 takes no action on the

assembly-language file because processing stops after compilation and before assembly.

.c indicates a C source file that can contain macros

and preprocessor directives.

.i indicates a preprocessed C source file. .s indicates an assembly-language source file.

filename

.s) file and also specify the

Include Files

The ic960 command line allows insertion of text from include files. Both the

i (Preinclude) option and the #include preprocessor directive cause

text insertion.

3-11

i960 Processor Compiler User's Guide

The #include preprocessor directive causes a search of the directory or directories indicated by the the

I option, ic960 searches the current directory, the directory defined by

the

I960INC environment variable, or the I960BASE/include directory.

I (Searchinclude) option. In the absence of

NOTES. The include files

for on-chip cache and timer control are not supported with the option.

icache.h, dcache.h

, and

timer.h

used

-ARP

Temporary Files

The compiler, assembler, and linker automatically create and delete temporary work files. You need not remove temporary work files unless your host system loses power or some other abnormal termination prevents the compilation system from cleaning up its work files.

The compiler selects a directory for temporary work files as follows:

G960TMP, TEMP, TMPDIR, TMP, .\ (Windows), /tmp (Unix), /usr/tmp

(Unix).

Output Files

Specifying a Stop-after option (-n, -Q, -E, -P, -S, or -c) causes the compilation system to produce a separate output file representing the output of the last phase that completes for each primary input file. An output file can be a preprocessed source file, an assembly-language file, a listing file, a map file, or an unlinked object file. If no errors occur during processing, the output files created by the stop-after option are usable as input to a future ic960 invocation. Table 3-2 lists the compilation phases and their inputs and outputs.

3-12

Specifying the filename; ic960 places all listings in the single file specified. If you do not use

Z, ic960 produces a separate list file for each primary C source file.

Z (Listname) option allows specification of a list file

ic960 Compiler Driver

Outputs

preprocessed files or

display on standard

output

syntax error list

listing files

assembly-language file

listing files

unlinked object files

listing files

list files

executable file

map file

relinkable object file

Each filename has the form

file

.L, where

C source file.

Table 3-2 Intermediate Inputs and Outputs

Last Phase Completed

preprocessing P, E, or

syntax checking

compilation S C source files

assembly c C source files

linking (default) C source files

Stop-after Option Inputs

C source files

n C source files

preprocessed files

preprocessed files assembly files

preprocessed files assembly files unlinked object files relinkable object files libraries configuration files

file

is the same name as the

3-13

i960 Processor Compiler User's Guide

When specifying only one primary input file, the o (Output) option names a single output file besides the listing file. Specifying multiple primary input files, or not specifying an output filename, causes ic960 to use the primary input filenames to derive corresponding default output filenames with the form

filename.e

, where:

filename

Unless otherwise specified, the destination directory for any output file is the current working directory. If destination directory, the compilation system overwrites the existing file.

The filename from the linker, produced in the absence of the stop-after options and the Output option. For ELF files, the default is

Creating a linker configuration file containing information for preparing an absolutely relocated module, a module for incremental linking, or code ready for programming into read-only memory (ROM) allows for additional file types. For more information on linker configuration, see the i960 Processor Software Utilities User's Guide.

a.out is the default for the executable COFF object file

is the primary input filename without its extension.

is a single-letter extension indicating the contents of a file, as follows:

i indicates a preprocessed file from the

P (Preprocess-files) stop-after option.

s indicates an assembly-language file

from the option.

o indicates an object file from the c

(Create-object) stop-after option.

L indicates a listing file from the

z (List) option.

filename.e

S (Save assembly) stop-after

already exists in the

e.out.

3-14

ic960 Compiler Driver

The following examples illustrate the creation and use of output filename extensions:

• The command

ic960 Options

This section describes the ic960 compiler driver options that allow control of various aspects of compilation:

ic960 -c -zs proto.c proto1.i produces the

object files

proto1.L.

produces the object file proto.o and the listing file proto.L.

executable file

proto.o and proto1.o and the listing files proto.L and

ic960 -c -o proto_v1.o -zs proto.c

ic960 -ACA -Tcycx proto.c produces the

a.out.

Input processing The and output They stop the translation and linking process

Specifying included The source text prepend and find include files of C source text.

Defining macros The

c, E, n, P, Q, and S are the Stop-after options.

after the preprocessing, syntax checking, compilation, or assembly phase. A Stop-after option causes the compilation system to save the intermediate output of the last phase to execute.

The

C (Keep-comments) and M (Mix) options

affect the contents of the output file. The (Output) option allows specification of the output filename.

i (Preinclude) and I (Searchinclude) options

D (Define) and U (Undefine) options allow

specification of macros for conditional compilation.

3-15

i960 Processor Compiler User's Guide

Control contents The A (Architecture), Fcoff | Felf (Object- of generated object format), code

G (Generate), and O (Optimization-level) options

control the instruction set, object format, debug information, and optimization level.

F (Fine-tune), f (Optimize), g (Debug),

Assembler and The linker support preprocessor, compiler, assembler, and linker. In

Whole-program The optimizations (Instrumentation), and gcdm (Decision Maker)

Provide Information The on the compiling affect messages the compiler produces about process C syntax and semantics. The

W (Pass) option relays options to the

addition, ic960 recognizes some options as linker options rather than compiler options. Table 3-1 lists the options that are relayed to the linker without the Pass option. For more detailed information on linker options, see the i960 Processor Software Utilities User's Guide.

fdb (Program Database), fprof

w (Diagnostic) and a (ANSI) options

z (List) and Z

W (Warnings) option allows fine

v (Verbose), V

3-16

ic960 Compiler Driver

Option

arch

size

Option Arguments and Syntax

Some compiler driver options take arguments. Whitespace is optional between an option and its argument. Case is significant in options and arguments.

The options and arguments have default settings. In most cases, the option is "off," that is, not in effect. Default settings of options and arguments are summarized in Table 3-3 and further discussed in the detailed description of the option. Some option defaults are affected by environment variables, as noted in the option descriptions.

This chapter uses the following notation:

[

item

] Square brackets indicate that the enclosed item is

optional.

. . . Horizontal ellipses indicate that you can use

multiple instances of the preceding item.

If two or more options contradict each other, the right-most option in the command line takes precedence. For example, the following command line sets the value of the symbol

ic960 -DL=80 -DL=132 proto.c

L to 132:

Table 3-3 ic960 Option Summary

Name Purpose Default

Architecture Select the instruction set. AKB ANSI Warn about non-ANSI source. Do not warn Limit-

optimizations Keep-

comments

Limit optimization of functions with more than

Keep comments in preprocessor output. Strip comments

size

asm instructions.

b 2500

continued

☛

3-17

i960 Processor Compiler User's Guide

Table 3-3 ic960 Option Summary (continued)

Option Name Purpose Default

c Create-object Stop after creation of object file. Do not stop

symbol

D [=

value

]

E Preprocess -

Fcoff | Felf Object-format Generate COFF or ELF object format. Fcoff fdb Database Build program database (PDB). No database fprof Instrument Compile with instrumentation; build PDB. No instrument-

arg

F [no]

arg

f [no]

arg

G g [ gcdm Decision-maker Invoke gcdm960 decision-maker. Do not invoke

h Help Display invocation help; terminate. No help text I i J j M Mix Mix C text with assembly output. No C text n Syntax only Check syntax; list errors; terminate. Do not stop O o P Preprocess -

arg

level

] Debug Include debug information in objects. No debug info

dir

filename

arg

]... Miscellaneous Selects miscellaneous controls. J nogd

num

level

filename

Define Define

stdout

Fine-tune Adjust optimizations. Additional fine-

tune

]... Generate Control code generation options. G cs,dc

Searchinclude Search Preinclude Prepend text to source files.

Errata Specify processor errata.

Optimize Specify optimization level (0, 1, 2, or 5). O1 Output Name output file.

file

symbol

Write preprocessed source to stdout; terminate.

Enable or disable an optimization.

dir

for include files.

Write preprocessed source text to files; terminate.

symbol

Do not stop

ation

gcdm960

filename

Do not stop

=a.out

3-18

continued

☛

ic960 Compiler Driver

Option

symbol

v960

phase

arg

]...

W [no-]

arg

level

Y d,

dirname

filename

arg

Table 3-3 ic960 Option Summary (continued)

Name Purpose Default

Dependencies Print include-file dependencies;

terminate. Save-assembly Save assembly-language output. Do not save Undefine Undefine symbol. Version Display version information. No display Version-exit Display version information and exit. Verbose Display invocation information. No display Pass Pass arguments to preprocessor,

compiler, assembler, or linker. Warnings Enable/disable a warning. Diagnostic-

level Program

database

Listname Name listing file. Compiler

List Produce listing file. No listing

Control diagnostic messages.

Specify location of program database. I960PDB

No print

level

specifies location

generates name

A (Architecture)

Selects the instruction set.

architecture

SA, SB, KA, KB, CA, CF, JA, JD, JF, HA, HD, HT, or RP

is one of:

3-19

i960 Processor Compiler User's Guide

Default

By default, the compiler uses the i960 KB architecture. The I960ARCH environment variable can override the default architecture.

Discussion

Use the A (Architecture) option to specify the target instruction set. This option overrides the environment variable

-Gcore0, -Gcore1, -Gcore2, and -Gcore3 options that let you generate

code that is compatible with multiple i960 processor types.

I960ARCH. See also the

NOTES. Also, with release 5.1 using the that is compatible with current and proposed future variations on the i960 RP architecture.

__i960

In addition to selections. Use i960 architecture but not necessarily specific to a particular processor.

In addition, for compatibility with earlier releases, macros of the forms:

i960, _ _i960_ _, _ _i960

If you link object modules compiled with incompatible architectures, the linker displays the following warning message:

is CA, CF, KA, KB, RP, SA, SB, HA, HD, HT, JA, JD, or

JF.

The compiler selects the value of

according to the architecture you specify.

__i960

, the __i960 macro is defined for all architecture

__i960 to identify parts of your program specific to the

xx_ _

and _ _i960_

-ARP

option generates code

xx_ _

are defined.

3-20

ic960 Compiler Driver

file

: architecture i960:XX incompatible with output

i960:

file

Example

The following example selects the i960 KA instruction set:

ic960 -AKA proto.c

a (ANSI)

Flags non-standard constructs.

Default

is the first file containing incompatible instructions the linker encounters.

is one of the two-letter architecture abbreviations.

The compiler accepts constructs that are legal under Kernighan and Ritchie's definition of the C language but that do not comply with the ANSI standard.

Discussion

Use the ANSI option to flag old-style C constructs that are legal according to Kernighan and Ritchie's definition in The C Programming Language, but are not legal according to the ANSI standard. When the ANSI option is in effect, the compiler prints warning messages for each occurrence.

3-21

i960 Processor Compiler User's Guide

NOTE. When this option is in effect, if your program contains in-line assembly-language ( a regular function call and produces code for the call. For example, if your program contains the following line:

asm("flushreg");

The compiler produces the following code:

callj _asm LFC0.$: asciz "flushreg" ...

The linker may then generate an error for an undefined extern for the

_asm call.

asm) statements, the compiler treats the statement as

To use keyword.

Specifying the option, as follows:

-a -w2 has the same effect as -a -w1; that is, errors and

-a -w1 errors and major warnings appear.

-a -w0 errors and all warnings appear.

asm statements and functions with the a option, use the __asm

a (ANSI) option can override the w (Diagnostic-level)

major warnings appear.

Example

The following example causes the compiler to issue an error message when it encounters a non-standard C construct. Because of the object) option, the compiler stops after creating an object file:

ic960 -c -a proto.c

c (Create-

3-22

ic960 Compiler Driver

Intel i960 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual