2. How to use the Compiler Driver
2.1. Target, Range, and Structure of this Document
This document describes the design and the usage of the COINS
compiler driver for the COINS users.
The COINS is a framework of compiler mainly to support users who
are to construct their own compiler. Thus, its driver part consists
of Java API to create their own compiler driver and a compiler driver
with traditionally fashioned command line interface (CLI) using the
API.
Section two describes about the design and the structure of the
COINS compiler driver. Section three is a users manual of the CLI
driver. Section four describes about an outline of the driver API.
2.2. COINS Compiler Driver
2.2.1. The design
We expect that the COINS users can be categorized into following
two categories:
- Users to implement their own compilers
- Users to compile programs using a compiler implementation packed
in the COINS release, or built by users of another category
Users of the former category may intend to:
- build a new compiler of a newly designed programming language,
- build a new compiler for a newly developed processor,
- integrate a newly designed optimizer into a compiler, and/or
- implement a new compiler interface, and so on.
The "new compilers" may require "new compiler drivers". The COINS
compiler driver provides a driver programming API.
Hereafter, we call a user of the latter category "operator".
When we write "user" without explanation, it doesn't mean the
operators.
Operators (and we) must not be willing to follow some ritual
procedures to use a compiler. Some of them will try "make
CC=newcc", without reading documents. To meet the requirement, a
traditionally fashioned CLI driver is provided. This CLI driver has
many similarities with the gcc (GNU C compiler) in the command syntax
and the basic compile options.
2.2.2. Structure
Figure 2-1 illustrates the structure of the COINS compiler driver.
prepared +---------------------+ +---------------------+ +------------+
by users |driver implementation| |driver user interface| |suffix rules|
+---------------------+ +---------------------+ +------------+
+-----------------------------+ +----------------------------+
API | tracer API / warning API | | compile specification API |
+-----------------------------+ +----------------------------+
+------------------------------------------------------------+
| engine |
+------------------------------------------------------------+
Figure 1-1: The structure of the COINS compile driver
Users should prepare the following three parts if needed:
- Driver User Interface:
The driver user interface is to:
- create a ``compile specification object,'' and
- pass the ``compile specification object'' to the engine.
The compile specification object is a Java object to hold source
files names and the compile options specified by the operator
implicitly or explicitly by the way the driver user interface
provides. It may be by CLI, may be by GUI.
- Driver Implementation:
The driver implementation is to provide following services
called from the engine:
- preprocess
- compile
- assemble
- link
The driver implementation refers the compile specification
object passed from the engine.
- Suffix Rules:
Suffix rules describes which suffix a file should have when a
certain action is taken to a file with a certain suffix.
The COINS release package provides a default suffix rule set
describing C, Fortran and Java suffix rules. Users can provide
their own suffix rules for existing languages and their new
languages.
Each API and the engine have following functions:
- Engine:
Calls services provided by the driver implementation according
to the compile specification passed from the driver user
interface. The resulting files are named according to the
suffix rules.
- Compile Specification API:
Is to create and refer the compile specification object. Target
file names and compile options can be specified / unspecified /
referred.
A special option system named ``COINS options'' is provided to
allow users to implement their own compile options. The driver
user interface can freely define a new COINS option and set a
value to it. The driver implementation can refer it.
- Tracer API:
Interprets trace options specified in the compile specification
object and decides to, or not to write trace messages.
- Warning API:
Interprets warning options specified in the compile
specification object and decides to, or not to write warning
messages.
2.3. How to Use the CLI Driver
2.3.1 CLI Driver
The class coins.driver.Driver provided by the release package is a
CLI-based driver implemented by the COINS driver API, which is
designed to have many similarities with gcc.
The class coins.driver.Driver is the driver implementation and the
class coins.driver.CommandLine is the driver user interface.
2.3.2 Command Syntax
java [java-option ...] coins.driver.Driver [option | filename]...
The command name 'java' may be 'jre' or other command name
according to your Java runtime.
'java-option's are for Java runtime environment, e.g., a -cp option
to use COINS classes. If you deployed the COINS classes at
/usr/local/coins,
java -cp /usr/local/coins coins.driver.Driver [option | filename]
will be enough to load COINS classes to the Java runtime.
2.3.3. Options
Following compile options can be specified:
- -E
- only preprocessing. As for C program, foo.i is generated by
processing foo.c. The output file is produced at the
directory where the input file (foo.c, in the example) is
located. COMPATIBILITY NOTE: gcc produces the output to the
stdout.
- -S
- stops after compilation (in the strict meaning, i.e., the
assembler code generation). As for C program, foo.s is
generated by processing foo.c. The output file is produced
at the directory where the input file (foo.c, in the
example) is located. COMPATIBILITY NOTE: gcc produces the
output to the current working directory.
- -c
- don't link. As for C program, foo.o is generated by
processing foo.c. The output file is produced at the
directory where foo.c is located. COMPATIBILITY NOTE: gcc
produces the output to the current working directory.
- -help
- shows help messages.
- -o file
-
specifies a path name of the output file. The output file
means a preprocessed source file when the -E option is
specified, an assembly code file when the -S option is
specified, an object code file when the -c option is
specified, and the executable file when none of the above
is specified.
- -barch, or -b arch
-
specifies a target architecture, as well as specifying
-coins:target=arch (see -coins:target=arch).
- -pipe
- uses pipelines instead of temporary files to communicate
between passes.
- -Wcategory
-
shows warning messages whose warning category is `category.'
- -Wno-category
-
suppresses warning messages whose warning category is
`category.'
- -C
- preserve comments while preprocessing.
- -Dmacro[=definition]
-
defines a preprocessor macro. `definition' is set to the
macro value when specified.
- -Ipath
-
specifies an include path.
- -P
- inhibits #line directives.
- -Umacro
-
undefines a preprocessor macro.
- -O
-
same as -O1.
- -Olevel
-
specifies an optimization level. The `level' must be a
non-negative integer. Optimizations done at each level are
following:
- -O0
- same as -coins:hirOpt=noSimplify
that does nothing.
- -O1
- same as -coins:hirOpt=cf,ssa-opt=prun/cpyp/cstp/dce/ebe/srd3,loopinversion
- -O2
- same as -coins:hirOpt=cf,ssa-opt=
prun/divex/cse/cstp/hli/osr/hli/cstp/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.4.3, includes the following additional options:
-coins:regpromote,schedule-after
- -O3
- same as -coins:hirOpt=inline/cf/pre,ssa-opt=
prun/divex/cse/cstp/hli/osr/hli/cstp/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.5.2, includes the following additional options:
-coins:regpromote-ex,schedule,pipelining
- -O4
- same as -coins:hirOpt=inline/loopexp/cf/cpf/pre,ssa-opt=
prun/divex/cse/cstp/hli/osr/hli/cstp/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.5.2, includes the following additional options:
-coins:regpromote-ex,schedule,pipelining
- -g
- preserves symbols in an executable file.
- -v
- prints a command line when a sub-process is invoked.
- -Lpath
-
specifies an archive search path.
- -dynamic
-
uses dynamic linkage.
- -static
-
uses static linkage.
- -larchive
-
specifies an archive to link.
- -coins:option
-
See the following section.
2.3.4. -coins Options
-coins:option,option,...
option is a COINS option. Any string not including `,' can be
specified as option.
More than one COINS option can be specified by delimiting
them by `,'s, e.g.
-coins:debug,trace=HIR.1,suffix=/tmp/mysuffixes
is same as
-coins:debug -coins:trace=HIR.1 -coins:suffix=/tmp/mysuffixes
Standard COINS options (which means the options that affects
driver API behavior) are as follows:
- -coins:target=arch
-
- -coins:target=arch-convention
-
specifies a target architecture.
Equivalent to -b arch, or to -b arch-convention.
"-coins:target=arch" is equivalent to
-coins:target=arch-standard
and "-coins:target=arch-convention" is equivalent to
-coins:target-arch=arch,target-convention=convention
-coins:target-arch=arch
specifies a target architecture name. arch
must be one of:
- sparc ...... SPARC architecture (mult/div is a subroutine)
- sparc-v8 ... SUN SPARC (mult/div is a machine instruction)
- x86 ........ Intel i386 architecture
- x86-cygwin .. Intel i386 architecture, cygwin
- x86_64 ...... Intel 64 architecture (comform to AMD64 ABI Draft 0.98) (from coins-1.4.3)
- x86_64-mac .. Intel-Mac architecture (comform to AMD64 ABI Draft 0.98) (from coins-1.4.3)
- arm ........ ARM
- mips ....... MIPS
- sh4 ........ Hitachi SH-4
- ppc ........ IBM PowerPC
- alpha ... Alpha
- thumb ... Thumb (16 bit ARM architecture)
- mb ...... Xilinx MicroBlaze
When this option is specified, the COINS Compiler Driver
specifies -D__arch__ as a preprocessor option, and specifies
the arch to LIR module invocation as a target architecture
name, which will be 'sparc' when this option is not specified.
Note:
All of above target options have been tested by using test programs
under the directory test/c and succeeded to execute correctly
except for a few number of special cases. As for the sparc and x86,
the compiler passed the test by comprehensive test program set
composed of 8000 programs and successfully executed the SPEC
CPU 2000 benchmark programs. (When -O3 option is specified,
some programs in SPEC CPU 2000 fail yet.)
When target=arm is specified, a few programs in SPEC CPU 2000
can be executed successfully but others failed because of
restrictions from test environment and remaining defects
in code generation. As for other targets (mb, mips, ppc,
sh4, thumb, alpha, x86_64), test by SPEC CPU2000 is not yet tried.
The code generators for sparc and x86 support the "long long" type,
while the others do not support it.
-coins:target-convention=convention
specifies a target convention name.
convention can be:
- in case of arch=sparc:
- standard ... standard SPARC convention
- v8 ... mult/div is a machine instruction
- in case of arch=x86:
- standard ... Linux ELF
- cygwin ... cygwin
- in case of arch=x86_64:
- standard ... Linux ELF
- mac ... Intel-Mac (fprintf is not supported)
When this option is specified, the COINS Compiler Driver
specifies the convention to LIR module invocation as a target
architecture convention name, which will be 'standard' when
this option is not specified.
- -coins:preprocessor=prep
- -coins:assembler=asm
- -coins:linker=link
-
specify the preprocessor, assembler, and linker.
The default preprocessor is 'cpp', the default assembler is 'as', and the default
linker is 'gcc'. (The default assembler has been 'gas' until coins-1.4.4.4.)
If the specified architecture requires different names from these default names,
the required names must be specified as shown in the following examples:
- x8_64-mac
-coins:assembler="as -arch x86_64",linker="gcc -arch x86_64"
- Alpha (linux machine)
-coins:preprocessor=alpha-linux-cpp
- arm, thumb, mb
-coins:preprocessor=XXX-linux-cpp,assembler=XXX-linux-as
where XXX is 'arm', 'thumb', or 'mb'
- mips-linux
-coins:preprocessor=mips-linux-cpp,assembler="mips-linux-as -KPIC"
- MicroBlaze (with EDK8.1)
-coins:preprocessor=mb-cpp,assembler=mb-as
- specification of header files
-
The stdarg.h file for sparc, x86, x86_64, and arm, is in COINS-directory/lang/c/include/stdarg.h. The following command option
-coins:preprocessor="cpp -I../lang/c/include"
specifies to use this file.
For x86_64-mac, a program which contains
#include <stdio.h>
may cause a syntax error. In that case, the program can be compiled by using
simplified header files. Examples of simplified header files are in
COINS-directory/lang/c/include/samples/
Cygwin users may need to specify the following option:
-coins:preprocessor="cpp-3 -I/usr/include"
(-coins:preprocessor="cpp -I/usr/include"
-- in case of using java version older than java 1.6)
- -coins:hirOpt=hiroptspec
- -coins:hirOpt=hiroptspec/hiroptspec/...
-
Do optimizations on HIR.
hiroptspec must be one of following:
cf constant folding
cpf constant propagation and folding
cse common subexpression elimination
dce dead code elimination
fromc simple optimizations done by C parser
gt global variable temporalization within basic blocks
pre partial redundancy elimination
loopexp loop expansion
presrhir loop expansion linked to the scalar replacement by
demend-driven partial redundancy elimination.
loopif loop invariant if-statement expansion
inline inline expansion
inlinedepth control recursive inline expansion
globalReform global pattern matching
complexityAllowance control optimization for large programs
See "5.1. How to Use HIR Basic Optimizer" in
5. Optimization for HIR for detail.
- -coins:ssa-opt=option/..
-
specifies SSA optimization options. The options are defined as follows:
- Translation to SSA form
(You MUST specify one of them at the beginning of this SSA option)
- mini : Translation to Minimal SSA form
- semi : Translation to Semi-Pruned SSA form
- prun : Translation to Pruned SSA form
- Back Translation from SSA form
(You MUST specify one of them at the end of this SSA option)
- brig : Back translation using Briggs's Method
- srd1 : Back translation using Sreedhar's Method I
- srd2 : Back translation using Sreedhar's Method II
- srd3 : Back translation using Sreedhar's Method III
- Optimization for SSA form
- cbb : Concatinate Basic Block
- cpyp : Copy Propagation
- cse : Common Subexpression Elimination
- cstp : Constant Folding and Propagation with Conditional Branches
- dce : Dead Code Elimination
- divex : Divide expression into three address code
- ebe : Empty Block Elimination
- esplt : Split Critical Edge
- gra : Global Reassociation
- hli : Hoisting Loop-invariant Code
- lir2c : Make C program from LIR
- osr : Operator Strength Reduction related to Induction Variables
and Linear Function Test Replacement
- preqp : Global Value Numbering and Partial Redundancy Elimination
with Efficient Question Propagation (under development)
- rpe : Redundant Phi-function Elimination
- ssag : Making SSA graph
- glia : Global Load Instruction Aggregation
After coins-1.4.4.2, the following optimizations for non-SSA forms can be specified:
- Optimization for non-SSA form
- pdeqp : Partial Dead Code Elimination based on Question Propagation
- divex2 : Divide expression into Three-Address Code (divex applied to normal form)
- esplt : Split Critical Edge
- expde : Exhaustive Partial Dead Code Elimination
- ddpde : Demand-Driven Partial Dead Code Elimination
After coins-1.5, the following optimizations for non-SSA forms can be specified:
- Scalar replacement by demand-driven partial redundancy elimination based on global value numbering
(Scalar replacement by demand-driven PRE in brief.)
- divex3 : Divide expression into Three-Address Code
(for Scalar replacement by demand-driven PDE).
- eqp : Demand-driven partial redundancy elimination without copy propagation
(for decreasing required number of registers).
- presr : Scalar replacement by demand-driven PRE.
See "8.2. SSA OPTIONS" in
8. SSA Optimization for LIR for detail.
- -coins:lir-opt=option/..
-
- -coins:lirOpt=option/..
-
These can be used after coins-1.4.4.3.
Options are the same as the options of ssa-opt.
- -coins:parallelDoAll=OpenMP
-
analyze for-loops and generate OpenMP program written in C
to be executed in parallel.
See "6.1. Loop Parallelizer" in
6. Parallelization for HIR for detail.
- -coins:parallelDoAll=n -S
-
where n is an integer number indicating maximum degree of
parallelization. This option specifies to
analyze for-loops and generate assembly language program
that can be executed in parallel by linking with
execution time routines prepared for parallelization.
See "6.1. Loop Parallelizer" in
6. Parallelization for HIR for detail.
- -coins:coarseGrainParallel
- -coins:cgParallel
-
specified to invoke the Coarse Grain Parallelizing
Module. See "6.2. Coarse Grain Parallelizing Module" in
6. Parallelization for HIR for detail.
- -coins:debug
-
Tells that the compiler is under debugging. Same as
-coins:preserveFiles,testHir,testSym.
- -coins:preserveFiles
-
Preserves temporary files.
- -coins:trace=tracespec
- -coins:trace=tracespec/tracespec/..
-
Tracer options.
There are two types of trace messages: categorized
trace messages and generic trace messages. A
categorized trace message have a message category,
and a generic trace message doesn't have message
category.
A trace message may have a message level which is a
non-negative integer value. Trace messages without a
message level are treated as level zero.
In the above form, each tracespec can be in form of
level
or
category.level
where a level is non-negative integer which
represents a trace level, and the category is a
sequence of letters and digits which represents a
message category. The former form specifies the trace
level of a generic trace message (hereafter, a generic
trace level). A generic trace message is printed only
if its message level is less than or equals to the
generic trace level. The latter form specifies the
trace level of categorized messages whose message
category is category. A trace message whose message
category is category is printed only if its message
level is less than or equals to the trace level. For
example,
-coins:trace=2
prints generic trace messages whose message level is
less than or equals to 2;
-coins:trace=HIR.2
prints trace messages of category `HIR' whose
message level is less than or equals to 2.
The available trace categories are:
Control -- What phases and (principal) modules are executed
HIR -- HIR (High level Intermediate Representation) information
Sym -- Sym and symbol table information
Flow -- Control flow and data flow information
Alias -- Alias analysis information
Parse -- C Parser information
ToHir -- C-AST (abstract syntax tree of C) to HIR transformation inf
HIR2C -- HIR-to-C transformation information
Opt1 -- HIR optimizer information
Para1 -- Loop parallelizer information
TMD -- Code Generation information
LIR -- LIR (Low level Intermediate Representation) information
When multiple categories are specified separating by / delimiter,
then trace information for each specified category is printed.
For example,
-coins:trace=Sym.1/HIR.1
prints the symbol table and HIR that are handed from the
front-end to the back-end. When optimization level and
Flow, Opt1 categories are specified in such a way as
-O3 -coins:trace=Sym.1/HIR.2/Flow.1/Opt1.4
then, information of the symbol table, HIR, control flow,
data flow, and optimization process will be printed.
Trace information is useful for understanding the process of
compilation as well as debugging the compiler itself.
When more than one generic trace levels are specified,
or more than one trace levels are specified for a same
category, the latter one overwrites the former one.
For example,
-coins:trace=4/8
prints generic trace messages whose message level is
less than or equals to 8, not 4;
-coins:trace=HIR.4/HIR.2
prints HIR trace messages whose message level is
less than or equals to 2, not 4.
A special category `default' is provided to specify a
trace level of all trace messages other than trace
messages whose trace levels are explicitly specified in
the other tracespecs. For example,
-coins:trace=default.2/HIR.4
prints HIR trace messages whose message level is
less than or equals to 4, and all non-HIR messages
(and generic trace messages) whose message level is
less than or equals to 2.
Note that a large trace level (e.g. 7, 8, 9, etc.) may
produce huge amount of traces.
- -coins:libdir=path
-
specifies a library directory path. See section 2.4.6
about the library directory.
When more than one -coins:libdir options are specified,
only the last one is valid.
- -coins:property=path
-
specifies property file path name. By default, a file
named `property' located at the library directory is
the property file.
See section 2.4.7 about the property file.
When more than one -coins:property options are
specified, only the last one is valid.
- -coins:suffix=path
-
specifies a path name of a suffix database file. By
default, a file name `suffixes' located at the library
directory is the suffix database file.
See section 2.4.8 about the suffix database file.
When more than one -coins:suffix options are
specified, only the last one is valid.
- -coins:suffixoption=option
-
specifies a suffix option.
See section 2.4.8 about the suffix option.
When more than one -coins:suffixoption options are
specified and are conflicting, the latter one overrides
the former one.
- -coins:hirAnal
-
Do HIR flow analysis.
- -coins:hir2c=t1
- -coins:hir2c=t1/t2/.../tn
-
translates HIR into a C program at specified timing.
t1, t2, ..., tn must be one of
new ... just after HIR creation,
flo ... just after data flow analysis on HIR has
been done, and
opt ... after all optimizations on HIR.
When more than one timing specifiers are specified,
HIR is translated at all specified timings.
Generated files are named as r-hir-t.c, where `r' is
the file name root of original source file, and `t' is
the timing specifier. For example,
java coins.driver.Driver -coins:hir2c=new foo.c
will produce foo-hir-new.c as the hir2c result.
Invalid timing specifiers are ignored and the
corresponding file is not generated.
- -coins:lir2c=t1
- -coins:lir2c=t1/t2/.../tn
-
translates LIR into a C program at specified timing.
t1, t2, ..., tn must be one of
new ... just after LIR creation,
opt ... after all optimizations.
When more than one timing specifiers are specified,
LIR is translated at all specified timings.
Generated files are named as r-lir-t.c, where `r' is
the file name root of original source file, and `t' is
the timing specifier. For example,
java coins.driver.Driver -coins:lir2c=new foo.c
will produce foo-lir-new.c as the lir2c result.
Invalid timing specifiers are ignored and the
corresponding file is not generated.
- -coins:stopafterhir2c
- -coins:stopafterlir2c
-
quits compilation of each compile unit just after
generating C source files at all specified timings by
the hir2c/lir2c option. When some invalid timing
specifiers are specified in hir2c/lir2c option,
however, the behavior of the compiler is undefined.
- -coins:testHir
-
Tests HIR integrity after HIR optimization and
parallelization and before converting HIR to LIR.
- -coins:testSym
-
Tests symbol table integrity after HIR optimization and
parallelization and before converting HIR to LIR.
- -coins:preprocessor=preprocessor-command
- -coins:assembler=assembler-command
- -coins:linker=linker-command
-
specifies alternative commands of preprocessor,
assembler, and linker.
In default, the COINS Compiler Driver uses cpp, gas,
and gcc as preprocessor, assembler, and linker. You
can override them by specifying these options.
Following example sets `as' as the assembler.
-coins:assembler=as
Blanks appeared in the command name works as a word
delimiter: e.g., following example sets the gcc as the
preprocessor and an option -E is given to it.
-coins:preprocessor=gcc -E
Do not forget to escape the blanks from your command
interpreter, if it treats blanks as a word delimiter,
too. For example, most of Unix shells can escape
blanks using quotations, e.g.,
-coins:preprocessor="gcc -E"
-coins:preprocessor='gcc -E'
'-coins:preprocessor=gcc -E'
Double quotations will work on Windows, too.
A quotation mark (' and ") and a next appearing same
quotation mark are removed from the string and
characters between them are interpreted as follows:
- a blank is not a word delimiter, and
- the other kind of quotation mark is treated as
itself, not a quotation mark.
This rule can be used to avoid the above rule which
interprets a blank as a word delimiter. For example,
in an environment where the file and directory names
can have blanks in its name, quotation marks can escape
the blank in the command name as follows:
-coins:preprocessor='my cc' -E
In this example, a program 'my cc' is invoked as a
preprocessor with an option '-E'. Do not forget to
escape quotation marks and blanks from your command
interpreter. For example, in Windows, double
quotations will be required as follows:
-coins:preprocessor="'my cc' -E"
Any character following a backslash (`\') is
interpreted as the character itself. A backslash can
be given by a backslash following a backslash. A
quotation mark can be interpreted as itself losing the
special effect described above by following a
backslash. This escape rule can be used to escape a
blank from being interpreted as a word delimiter. For
example, if your environment allows you to include
blanks in file/directory name, you can escape them by
backslashes: e.g.,
-coins:linker=c:\\Program\ Files\\bin_utils\\ld
will set `c:\Program Files\bin_utils\ld' as a linker.
Again, never forget to escape `\'s and blanks from your
command interpreter, if necessary; e.g., in Windows,
-coins:linker="c:\\Program\ Files\\bin_utils\\ld"
- -coins:max-recovered-errors=n
-
When the number of recovered compile errors exceeds n
while executing a compile step of a compile unit, a
compile error is issued. Or, if 0 is specified as n,
no compile error is issued only by increasing the
number of recovered compile errors. A compile step
here is one of preprocess, compile, assemble, and link.
- -coins:max-warnings=n
-
When the number of warnings exceeds n while executing a
compile step of a compile unit, a compile error is
issued. Or, if 0 is specified as n, no compile error
is issued only by increasing the number of warnings. A
compile step here is one of preprocess, compile,
assemble, and link.
- -coins:compile-parallel
-
Compilations of all compile units are executed
concurrently. Do not specify this option while using a
compiler driver which is not implemented in thread-safe
way.
- -coins:loopinversion
-
specifies to invert a loop end condition when the loop
ends with an unconditional jump.
- -coins:regpromote
-
can be used after coins-1.4.4.3. It
specifies register promotion (the attach option is not needed).
See "11.2.3. Example 3: Register Promotion" in
11. Structure and Extensions of the Backend Process for detail.
- -coins:regpromote-ex
-
can be used after coins-1.4.5.2. It
specifies extended register promotion (the attach option is not needed)
that promote more variables to registers based on pointer analysis.
- -coins:schedule
- -coins:schedule-after
-
can be used after coins-1.4.4.3 (the attach option is not needed). schedule
specifies instruction scheduline before and after the register allocation.
schedule-after
specifies instruction scheduline after the register allocation.
See "11.2.1. Example 1: Instruction Scheduler" in
11. Structure and Extensions of the Backend Process for detail.
- -coins:pipelining
-
can be used after coins-1.4.4.3 (the attach option is not needed). It
specifies software pipelining.
See "11.2.2. Example 2: Software Pipelining" in
11. Structure and Extensions of the Backend Process for detail.
- -coins:gprof
-
specifies to generate profiling information just like gcc.
This option should be accompanied with the option
-coins:linker="gcc -pg"
By executing the execution-file (a.out, a.exe, etc.),
gmon.out will be generated and user can get profiling
information by executing following command
gprof execution-file
just like gcc.
The test scripts test/c/testdriver_gprof, test/c/testdriverw_gprof.sh
are available to do automatic test and profiling for
a set of test programs.
The gprof option is effective only for sparc and x86 at present.
See
gprof manual
'gprof: A Call Graph Execution Profiler' by S. Graham, P. Kessler, M. McKusick
2.3.5. Input Files
Input files can be listed among options. The engine determines which
passes should be applied to an input file according to its suffix. As for
this suffix rule, see coins.driver.SuffixFactory.
Each output file is generated at the directory where its source file
exists, unless -o option is specified.
2.3.6. Exit Status
The CLI driver returns exit status as follows:
- 0 ... normal termination
- 1 ... abnormal termination
`Abnormal termination' includes I/O error, compile error, etc.
2.3.7 Some Simple Examples
In all examples below, it is assumed that the CLASSPATH environment
variable is set appropriately:
java coins.driver.Driver foo.c
will compile foo.c and generate a.out.
java coins.driver.Driver -o foo foo.c
will compile foo.c and generate foo as an executable binary.
java coins.driver.Driver -c foo.c
will compile foo.c and generate foo.o as an object file.
java coins.driver.Driver -E foo/bar.c baz/boo.c
will preprocess foo/bar.c and baz/boo.c and generate foo/bar.i and
baz/boo.i where `.i' is a suffix meaning `preprocessed C source' in
the default suffix rule.
java coins.driver.Driver -S foo.c bar.i
will compile foo.c and bar.i and generate foo.s and bar.s.
Generally speaking, aliasing `java coins.driver.Driver' as `cc', you
can use COINS C compiler like an ordinary C compiler except some
exceptions; e.g., cc -E will not work as cpp.
2.4. The Driver API
This document describes an abstract.
For a full description, see JavaDoc's of each API class.
2.4.1. Driver User Interface
The function of the driver user interface is as follows:
- Generates a compile specification object representing the
operator specification, and
- Invoke the engine passing the compile specification object and a
driver implementation.
The compile specification object must implements an interface
coins.driver.CompileSpecification.
In the CLI driver, the methods main() and go() of class
coins.driver.Driver correspond the driver user interface. They are
described as follows:
protected void go(String[] args) {
CompileSpecification spec = new CommandLine(args);
int status = new CompilerDriver(spec).go(this);
System.exit(status);
}
public static void main(String[] args) {
new Driver().go(args);
}
The class coins.driver.CommandLine is a compile specification class
for the CLI driver. The class coins.driver.CompilerDriver is the
engine. Since the class coins.driver.Driver is a driver
implementation class, it passes an instance of itself as a driver
implementation.
If you are to build a compiler driver which has a same user
interface as the CLI driver, the above code segment will be reused
without change.
2.4.2. Driver Implementation
The driver implementation provides following services called from
the engine:
- Preprocess
- Compile
- Assemble
- Link
An interface coins.driver.CompilerImplementation is defining the
interface to be implemented by the driver implementations.
In case of the CLI driver, the class coins.driver.Driver is the
driver implementation. The CLI driver is providing the above four
services. Three of the four, i.e., preprocess, assemble, and link are
just call an external program.
2.4.3. Compile Specification
The compile specification must implement an interface
coins.driver.CompileSpecification.
In case of the CLI driver, the class coins.driver.CommandLine is
the compile specification.
2.4.4. Tracer API
Tracer API interprets trace options specified by an operator,
determines whether a trace message should be printed or not, and
prints it if it should.
A driver implementation, and compiler modules called from it, can
use the trace API to put a trace message, specifying a message
category and a message level. A message category can be an arbitrary
string of letters and digits. A message level must be a non-negative
integer.
A trace option is a set of pairs of a trace category and a trace
level. The tracer API prints a trace message if its message level is
less than or equal to the trace level of the trace category which is a
same string with the message category.
To obtain an instance of a Tracer API, which knows trace options
specified by an operator, use a method
CompileSpecification#getTrace().
2.4.5. Warning API
Warning API interprets warning options specified by an operator,
determines whether a warning message should be printed or not, and
prints it if it should.
A driver implementation, and compile modules called from it, can
use the warning API to put a warning message, specifying a warning
category. A warning category can be an arbitrary string of letters
and digits.
A warning option is a set of warning categories which should be
printed and a set of warning categories which should not be printed.
The warning API prints warnings specified to be printed.
To obtain an instance of Warning API which knows warning options
specified by an operator, use a method
CompileSpecification#getWarning().
2.4.6. Library Directory
Compiler modules can be designed configurable and thus require
configuration files for them. For example, the driver API is designed
to allow operators preparing following configuration file:
- Property file (see section 2.4.7)
- Suffix database file (see section 2.4.8)
A library directory is a directory at where the configuration files
should be located.
A compiler module can ask the COINS driver API where the library
directory is, i.e., use a method CoinsOptions#getLibDir() to an
instance of class.driver.CoinsOptions, which can be obtained by a
method CompileSpecification#getCoinsOptions(). A COINS user can let
an operator to prepare a configuration file at his/her library
directory and let a compiler module to read the file using the API.
If a -coins:libdir=path option, which is one of the COINS options,
is specified, the driver API returns path as the library directory
path name. If not specified, the driver API searches a directory
named `coins' at the operators home directory (`user.home' property
value returned by the Java runtime) and returns its path name if it is
found. If not found, a relative path name which represents a current
working directory is returned as the library directory path name.
2.4.7. Property File
When applying COINS to develop a compiler, a relatively long COINS
options including tracer, warning, and user own options may be
required at each compilation. A `property file' functionality is to
improve such a situation by storing the options in a file and give the
file to the compiler.
By default, a file named `properties' in the library directory (see
section 2.4.6) is treated as a property file.
Since some operators may change the property file location, it is
changeable at creating compile specification. Interpretation of the
property file is done at that time by class coins.driver.CoinsOptions.
The property file may be written in arbitrary format which can be
read by a method java.utils.Properties#load(). An example follows:
debug:
trace: HIR.4
suffix: /tmp/mysuffixes
This example is exactly same as giving a following COINS option to the
CLI driver.
-coins:debug,trace=HIR.4,suffix=/tmp/mysuffixes
2.4.8. Suffix Rules
A suffix rule is a rule to determine which pass should be applied
to an input file and which suffix should be given to the output file.
The COINS release package has a default suffix database file which
contains suffix rules for C, Fortran, and Java.
By default, a file named `suffixes' under library directory (see
section 4.6) is treated as a suffix database file. If not found,
following default is used:
#SRD, 2, Suffix rule DB file, format version 2
c, C, C source, i,s,o
c(out-newlir), C, C source, i,lir,-
i, C, preprocessed C source, -,s,o
cc/cpp/cxx/C, C++, C++ source, ii,s,o
ii, C++, preprocessed C++ source, -,s,o
java, Java, Java source, -,class,-
java(native), Java, Java source (native compile), -,s,o
f, FORTRAN, FORTRAN source, -,s,o
f(out-newlir), FORTRAN, FORTRAN source, -,lir,o
lir, LIR, new LIR, -,s,o
S, Assembler, assembly source (need preprocess), s,-,o
s, Assembler, assembly source, -,-,o
Detail of this file format is described in a JavaDoc document of
class coins.driver.SuffixFactory.java. Roughly speaking, it is a
sequence of records each of which is in structure of:
suffix, language name, meaning, suffixes after preprocess, compile, and assemble.
Since some operators may change the suffix database file location,
it is changeable at creating compile specification. Interpretation of
the property file is done at that time by class
coins.driver.SuffixFactory.
2.4.9 .`settings' File
While compilation, various information is required because
compilation is an essentially complicated process. There can be some
information which differs site by site, e.g., a special library path,
an OS name, and so on. Thus, there needs a way to read site-local
settings. `Settings' file is designed to keep such site-local
settings
coins.driver.Driver reads settings file by a method
java.utils.Process#load() from a library directory if it exists, and
stores the contents to a member variable named `defaultSettings'.
For coins.driver.Driver, valid properties are:
- defaultLinkerOptions
Always specified linker Options. Can be used for the
situation such that some -L and -B options are always
required.
- systemIncludePath
Include path options (-Ipath) always specified. The COINS
stdarg.h can be used by this property.
The following is an example of the settings file
(as for libf2cLocation, see " 4.2.2 Fortran Driver Setup " of
How to use Fortran 77 Compiler).
(This example is applicable after coins-1.4.5.)
systemIncludePath ./lang/c/include ./lang/c/include/samples
defaultLinkerOptions /usr/lib
libf2cLocation ./lnag/fortran
Compiler modules of COINS and drivers other than
coins.driver.Driver can use this mechanism to read their site-local
settings.
2.5. Known Bugs and Restrictions
Known bugs and restrictions of release 1.0 is as follows.
2.5.1. Known bugs
- Compilation may not terminate:
A long period of continuous compilation may leave an assembler
process unterminated.
2.5.2. Restrictions
- An option -b arch is not given to a linker command.
Although a naming convention of target architecture of the COINS
compiler infrastructure differs from the one of the GNU CC, used
as a linker in the COINS compiler infrastructure, no conversion
method between them is implemented currently. Thus, specifying
target architectures differing from the default architecture of
the GNU CC cause linker errors. This problem can be avoided by
several ways; e.g., specifying -coins:linker=linker-command to
invoke the GNU CC with appropriate options.
- -coins:lir2c has following restrictions:
- function pointers
lir2c cannot convert function pointer declarations into
proper C codes.
- pointer variables
lir2c converts pointer variable declarations into int
variable declarations.
- signed and unsigned
lir2c converts unsigned variable declarations into signed
variable declarations.
- global variable initializations
lir2c removes definitions and initializations of variables
outside of functions.
- Phi functions
lir2c cannot convert Phi functions, created in SSA
optimizations invoked by -coins:ssa-opt options.