Table of Contents
esterel - Esterel compiler - Version v5_21
esterel [options] files ...
The esterel command calls the Esterel compiler. This compiler translates
an Esterel file (suffix .strl ) into various intermediate codes
and finally into executable target code, C being the standard target format.
Version v5_21 actually contains two compilers: V3 and v5_21 proper. These
compilers accept the same language and produce compatible object codes;
they differ only by the internal algorithms. The newer v5_21 compiler is
the default one. The older V3 compiler is available through option -v3
.
The basic usage is to compile Esterel programs into straight-line single-loop
C code. Writing
-
esterel foo.strl
-
compiles foo.strl into foo.c . This is for embedded code.
for simulation, one uses the -simul option:
-
esterel -simul foo.strl
-
The object code foo.c can be compiled and linked with a simulation
library, either libcsimul.a (csimul(3)
) for tty simulation or libxes.a (xes(3) ) for X-windows simulation
and symbolic debugging (see also the xes (1)
command).
Other forms of generated code are byte-code single-state automata (option
-S ) and byte-code expanded automata well-known to Esterel v3 users
(option -A ). One interpreter is also available (option -I ).
Usually, source code occupies several files. These files are simply
given to the esterel command, and a -B option is used to
give the basename of the result:
-
esterel foo.strl bar.strl -B foo
-
builds file foo.c .
To understand the esterel command and its various options, it
is necessary to understand the name and function of the intermediate codes.
All intermediate codes start with a common set of symbol tables and differ
only by their statement part. Most processors act only on the statement
table.
-
ic
-
First intermediate code, common to V3 and v5_21. The statement language
is a synchronous concurrent process calculus. An ic module can contain
open references to other ic modules.
-
lc
-
Identical to ic intermediate code, but fully linked: all references
to submodules have been resolved by in-place expansion of submodule. Common
to V3 and v5_21.
-
sc
-
The statement part is made of a boolean circuit definition. Used only in
v5_21. Translation from lc to sc code is the main part of
Esterel v5_21.
-
ssc
-
Sorted boolean circuit definition. Used only in v5_21. Obtained from sc
code by topological sorting and constant folding with possible causality
analysis.
-
oc
-
Automata coded in byte-code format. Common to V3 and v5_21.
A file in a given format has the format name for suffix: foo.ic ,
foo.ssc , etc.
The Esterel compiler automatically chains processors that translate
a format into the next one. Here are these processors:
-
strlic
-
The Esterel front-end. It reads files containing Esterel source code (.strl
suffix) and produces intermediate code in ic format. Common
to V3 and v5_21.
-
iclc
-
The Esterel binder. It performs the expansion of submodules instantiated
using the run statements; it reads several ic (or lc )
files and builds an unique linked code file in lc format. Common
to V3 and v5_21.
-
lcsc
-
The v5_21 compiler to boolean circuits. It reads a lc file and produces
its object code in sc format.
-
scssc
-
The v5_21 circuit topological sorter. It reads a sc file and produces
a sorted circuit in ssc format.
-
sccausal
-
The v5_21 causality analyzer. It reads a sc file and produces a
sorted circuit in ssc format.
-
sscl
-
A generic name for Esterel code generators, which translate ssc sorted
circuit code into l target language (examples: sscc , sscdebug
).
-
scl
-
A generic name for v5_21 interpreted code generators, which translate sc
code into object code interpreting the sc equations (example: scc
). See option -I .
-
sscoc
-
The v5_21 compiler to automata in oc format and oc format
optimizer. It takes a ssc or a oc file and produces a file
in oc format describing either fully-expanded or single-state automata.
-
ocl
-
A generic name for Esterel code generators, which translate automata in
oc format into l target language (example: occ , ocdebug
).
-
lcoc
-
The V3 compiler to automata. It is used when option -v3 is specified.
It reads a lc file and generates an automaton in oc format.
The V3 compiler chains strlic , iclc , lcoc , and
occ . By default, the v5_21 compiler chains strlic , iclc
, lcsc , scssc , sscc ; if the oc format
options -S or -A described below are used, the v5_21 compiler
chains strlic , iclc , lcsc , scssc sscoc ,
and occ . If the -causal or -singlw options are used,
sccausal is chained instead of scssc .
In addition, there are two run-time libraries:
-
libcsimul.a
-
The tty simulator library, common to V3 and v5_21.
-
libxes.a
-
The X-windows simulator and symbolic debugging library, common to V3 and
v5_21.
Any suffix in the list .strl , .ic , .lc , .sc
, .ssc , or .oc is recognized in the file names: the
esterel command will arrange for only the appropriate utilities
to be called. For example,
-
esterel foo.strl bar.ic -B foo
-
will produce a file foo.c out of a source file foo.strl and
of an already compiled ic file bar.ic . Notice that bar.ic
may come from another language than Esterel.
Options and file names can be given in any order and mixed arbitrarily.
The following two options are of general use:
-
-help
-
Display a brief description of the command line arguments on standard output;
all other options are ignored.
The following options define the kind of object code in v5_21 proper:
-
-L or -L language [:specific_options ]
-
In simple form, generate C code directly from boolean equations in ssc
format. This is the default option. In extended form, specifies a target
language; for example -Ldebug prints the equations in readable form,
by calling sscdebug . The string specific_options allows
the user to specify additional options for the code generator. For instance,
-Ldebug:-names add more names to the debug code. To pass several
options to a code generator, use double quotes: -Ldebug:"-names -emitted"
. See the documentation of each code generator for relevant options.
-
-S or -S language [:specific_options ]
-
Use sscoc to translate equations into straight-line single-state
oc format and then compact C byte-code. The extended form defines
a target language as for option -L , e.g. -Sdebug calls ocdebug
.
-
-A or -A language [:specific_options ]
-
Use sscoc to generate fully-explored automata in oc format
and then compact C byte-code. Use option -A:-inline to inline function
calls: this may improve execution speed (see occ(1)
). Subject to code size explosion. The extended form is as for option
-L , e.g. -Adebug calls ocdebug .
-
-I or -I language [:specific_options ]
-
Simply translate the sc file into C and interpret it at run-time.
Usefull for cyclic sc code which cannot be topologically sorted.
The extended form is as for option -L , e.g. -Ipascal calls
scpascal if it exists.
Remark: language can not be an intermediate code.
The following option calls the V3 compiler;
-
-v3
-
Call V3 lcoc and occ modules and directly produce a fully-explored
oc automaton. Subject to code size explosion. A target language
can be specified using the -A option above. Useful since v5_21 is
by now less tolerant w.r.t. causality than V3.
The following option must be used to generate tty or X-windows simulators
and symbolic debuggers using the libraries libcsimul.a
(3) and libxes.a (3) :
-
-simul
-
Generate code with additional simulation data structures
The following option controls oc code optimization:
-
-O or -O [n ]
-
Optimize the oc code produced under options -S or -A .
The optional parameter allows the user to select the optimization performed
by the processor with a combination of bits. See sscoc(l)
for bit correspondence. Beware: option -O is not directly compatible
with option -v3 . To optimize v3 code, use option -oc below
to stop at oc code level, and optimize in a second step:
-
esterel -v3 -oc foo.strl; esterel -O foo.oc
-
By default, the compiler compiles all the modules that are not themselves
included in other modules. This may be too much when including Esterel
or ic code libraries. The following options provide the user with
better compilation control:
-
-main module
-
Consider the named module to be a root module. If at least one such option
is present, only modules mentioned in -main options are compiled.
The following options allow the user to control the name and directory
of output files:
-
-B name
-
name defines the output files default base name; this name is used
for intermediate and target code files. The appropriate suffix is added
automatically. If this option is omitted and if the esterel command
is invoked with only one file name, name defaults to the base name
of this unique file with the appropriate suffix; otherwise it defaults
to the base name esterel , still followed by the appropriate suffix.
-
-D directory
-
Specify a directory where intermediate and output files will be placed.
The default is the current directory.
The following options control the printing of compilation warnings and
errors:
-
-w
-
Suppress all warning messages.
-
-W
-
Display all warning messages (the default is to display only harmful warnings).
The following options control the kind of causality analysis to be used:
-
-cycles
-
Print all causality cycles in the program and show them using a graphical
interface (available in v5_21 compiling). There is no strong causality
analysis performed: the analysis is based on simple topological sort. Furthermore,
the compiler stops and nothing is generated.
-
-causal
-
Use the strong causality analysis based on state reachability and strongly
connected components.
-
-oldcausality
-
Enable the v3_1r4 causality error detection. For example, the following
program: "emit S; present S else emit S end" is no longer accepted by the
compiler unless this option is used.
-
-single
-
Check for each valued signal without combination function if that signal
is actually emitted once per instant. The analysis is based on state reachability.
The -single implies the -causal option.
The following options give information about what is happenning when compiling
programs:
-
-v
-
Verbose mode: the esterel command and the various utilities tell
what they are doing.
-
-n
-
Tell what is to be done, but don't do it.
-
-stat
-
Display various time statistics and the size of each process; implemented
on BSD 4.x systems only.
-
-size
-
Display the final size (number of states, actions and bytes) of generated
automata.
-
-show
-
Display dynamically the number of states generated and explored so far
in automata computations by sscoc or lcoc .
The following option is useful for checking programs without actually compiling
them
-
-s
-
Silent mode, do not produce output files.
The following options enable the user to stop the compilation process at
some intermediate stage:
-
-ic
-
Just use strlic to convert strl files into ic files,
ignoring all other files. Each .strl file is translated into a .ic
file having the same basename.
-
-lc
-
Stop after running the binder (iclc ), leaving a .lc file,
with basename determined by options -B and -D .
-
-sc
-
Stop after running the circuit generator (lcsc ) leaving a .sc
file, with basename determined by options -B and -D .
-
-ssc
-
Stop after running the topological sorter (scssc ), leaving a .sc
file, with basename determined by options -B and -D .
-
-oc
-
Stop after running the automata producer (sscoc or lcoc ),
leaving a .ssc file, with basename determined by options -B and
-D .
The esterel command removes all the intermediate files it has created,
unless one of the following options is given:
-
-Kic
-
Keep all the ic files, with basenames those of the corresponding
esterel files.
-
-Klc
-
Keep the lc file, with basename determined by options -B and
-D .
-
-Ksc
-
Keep the sc file, with basename determined by options -B and
-D .
-
-Kssc
-
Keep the ssc file, with basename determined by options -B and
-D .
-
-Koc
-
Keep the oc file, with basename determined by options -B and
-D .
-
-K
-
Keep all the intermediate files.
The following options give information about processor versions. They are
processed by the esterel command and passed recursively to all related
utilities it can find:
-
-version
-
Display the version number of the esterel command, as well as the
ones of the various utilities including all known code generators. The
only relevant options with -version is -backup .
-
-access
-
Display access rights to the esterel command.
-
-allaccess
-
Display access rights to the esterel command and to the various
utilities including all known code generators. The only relevant options
with -allaccess is -backup .
-
-info
-
Display various information about the compilation of the esterel command
and the various utilities including all known code generators. The only
relevant options with -info is -backup .
The following option makes it possible to use alternate compiler modules:
-
-backup path
-
Give an alternate way of finding the various utilities called by the esterel
command. Usually these utilities are found in a default directory (/usr/local/lib/esterel).
The user can specify another default directory by setting the shell environment
variable ESTEREL. It is assumed that the ESTEREL directory contains itself
a bin sub-directory where the utilities may be found. The user can
also supersede any of these defaults by using the -backup in one
of two forms.
-
If path is the name of a directory, the result is the same as
-
setting ESTEREL to path for the duration of the command. If path
has the form processor : path , with processor being
one of strlic , iclc , lcoc , lcsc , scssc
, sscoc , scl , sscl , or ocl , the corresponding
utility is found in directory (with standard name) or file path .
In the case of scl , sscl , and ocl , path (if
not a directory) is just the prefix of the code generator name. The full
name will be path concatenated with the target language (see the
-L , -S , -A , and -I options below).
-
There can be several -backup options; they are scanned from left
-
to right.
The following options are used to pass specific options to subprocessors
other than code generators:
-
-strlic:options
-
-iclc:options
-
-lcsc:options
-
-scssc:options
-
-sccausal:options
-
-sscoc:options
-
-lcoc:options
-
The string options is either a single option or a list of options
enclosed within double quotes. For example:
-
esterel -iclc:-R foo.strl
-
esterel -iclc:"-R -debug" foo.strl
-
The simple command
esterel foo.strl
performs a full Esterel compilation, leaving the generated C code in file
foo.c .
To produce a fully expanded automaton in debug format while keeping
the intermediate oc format, type
esterel -Koc -Adebug foo.strl
A little more complex, the following command
esterel -Kic -Koc -O -B autom -Scobol f1.strl f2.ic
f3.lc
will pass f1.strl through strlic and keep the f1.ic file;
then it will pass f1.ic , f2.ic , and f3.lc through
iclc , lcsc , scssc , and sscoc to produce
single-state optimized oc code in file autom.oc ; the intermediate
file autom.lc is discarded; finally, the autom.lc file is
converted into COBOL by occobol (most certainly a user-developped
code generator, since the standard distribution is very unlikely to support
this target language).
The command
esterel -v3 -K -Bfoo -D/a/b -S f1.strl f2.strl f3.ic f4.oc
produces the following files: /a/b/f1.ic , /a/b/f2.ic , /a/b/foo.lc
, /a/b/foo.sc , /a/b/foo.ssc , /a/b/foo.oc , and
/a/b/foo.c .
To illustrate the -s option, note that
esterel -s foo.strl
performs a full compilation upto C code generation, but the C file is not
produced; similarly,
esterel -ic -s foo.strl
will only execute the front-end strlic without producing any .ic
file.
Finally,
esterel -Ldebug:"-names -emitted" -Lc foo.strl
performs a full compilation of the Esterel source file foo.strl to
both C and debug formats, passing the argument "-names -emitted" to
the ocdebug code generator.
The command returns with exit code 0 if and only if no error was detected
by the various utilities.
Various error or warning messages indicate incompatible or redundant
options, or error conditions related to file handling.
The command checks whether it generates a file which is already present
in its argument list, and, if so, stops with an error, to avoid clobbering
the file.
The corresponding test is based on the name of files as given by the
user and is rather rustic. For instance, the following erroneous condition
(or any similar one) is not detected
esterel -K -Bfoo -D.. foo.strl .././foo.lc
and will certainly result in loosing the original content of ../foo.lc
(use the -n option to see what will occur).
The esterel command is unaware of any file generated as a side-effect
of the utilities it calls. This is not really a bug, just a remark.
New code producers may be added. It suffices to install the code producer
into the default library directory for Esterel utilities (/usr/local/lib/esterel).
A code producer must have a -B option which has the same meaning
and argument as the -B option of the esterel command. A code
producer whom output is an intermediate format will not be recognize (examples:
scoc, sscic...).
ssc sorted circuit code may be optimized using hardware techniques.
To do this, one must first generate BLIF (Berkeley Logic Interchange Format)
only for the program control:
esterel -ssc -Lblif:-soft foo.strl
The result file foo.blif is a description of the program control as a sequential
circuit, together with a foo.ctbl file. foo.blif may be optimized using
standard hardware optimization techniques. Once foo.blif is optimized,
say foo.opt.blif, one can get back to the esterel compiler. The command:
blifssc -B foo.new -ctbl foo.ctbl foo.opt.blif
will generate a file foo.new.ssc that contains the optimized control and
my be used in the esterel compiler as any .ssc files. See ssblif(1)
and blifssc(1) .
In the following, $lib designates the default library directory for Esterel
utilities (/usr/local/lib/esterel). This default path can be modified by
setting the environment variable ESTEREL, or by using -backup options.
$lib/bin/esterel
Esterel command shell script
$lib/bin/esterel.exe
Esterel command binary file
$lib/bin/strlic
Esterel front-end
$lib/bin/iclc
Esterel binder
$lib/bin/lcoc
Esterel v3 compiler (automaton generator)
$lib/bin/lcsc
Esterel compiler (circuit generator)
$lib/bin/sccausal
Esterel circuit causality analyzer
$lib/bin/scssc
Esterel circuit topological sorter
$lib/bin/sscoc
Esterel automaton producer and optimizer
$lib/bin/sc*
Esterel code generators (for v4 interpreter)
$lib/bin/ssc*
Esterel code generators (from equations)
$lib/bin/oc*
Esterel code generators (from automata)
$lib/lib/libcsimul.a
Esterel tty simulation library
$lib/lib/libxes.a
Esterel X-windows simulation library
*.strl Esterel
source files
*.ic Intermediate
code files
*.lc Linked
intermediate code file
*.sc Circuit
description
*.ssc Sorted
circuit description
*.oc Portable
automata file
esterel.*
Default names for intermediate files
Esterel documentations.
strlic(1) , iclc(1)
, lcoc(1) , lcsc(1) ,
sccausal(1) , scssc(1)
, sscoc(1) , occ(1) ,
ocdebug(1) , sscblif(1)
, blifssc(1) , csimul(3)
, xes(1)
Ecole des Mines de Paris (CMA) and INRIA.
Initially written by Jean-Paul Rigault and Jean-Marc Tanzi. Updated
by Frederic Mignard, Jean-Pierre Paris, Francois-Xavier Fornari.
Table of Contents
Back To Main Manual Page