esterel(1)

NAME
esterel - Esterel compiler - Version v5_21

SYNTAX
esterel [options] files ...

DESCRIPTION
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

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 -Llanguage[: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 -Slanguage[: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 -Alanguage[: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 -Ilanguage[: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

EXAMPLES
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.

DIAGNOSTICS
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.

BUGS
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).

FILES

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

SEE ALSO
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)

IDENTIFICATION
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.