
Project: StateCharts cOmPilEr (SCOPE)
Release: scope-0-10

     Copyright (C) 2001-2002 Andrzej Wasowski
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

MANUAL,v 1.11 2002/11/15 23:33:41 wasowski Exp




CONTENT

1. About this document
2. Credits & License
3. About SCOPE
4. Installation Note
4.1. Linux binary
4.2. Compiling from scratch under Linux
4.3. Windows
4.4. File list
5. Usage
5.1. Executable Code Synthesis
5.2. Generating helper code for visualSTATE programs
5.3. Anonymizing Projects 
6. Some evaluation




1. ABOUT

This file attempts to give an overview of SCOPE tool, its purpose, usage and
installation. 



2. CREDITS & LICENSE 

You should have received a LICENSE file bundled together with this
distribution. Please, refer to it for details on possible use and
distribution.

This works is a part of Resource Constraint Embedded Systems
(RCES) project run at IT-University of Copenhagen.

Implemented by Andrzej Wasowski, It-University of Copenhagen. 

The work under supervision of Peter Sestoft (IT-C/KVL). Syntactic and
lexical structures implemented based on work by Jorn Lind Nielsen with
significant support from Kent Rene Simonsen (IAR). 

I would like to thank Peter Sestoft, Henrik Hulgaard, Kaare Jelling
Kristoffersen for discusssions on statecharts and code generation, and to
Ken Friis Larsen for comprehensive support on MoscowML and Muddy.

This software was produced using (or incorporates parts of) MoscowML, Muddy,
Buddy and numerous GNU tools. All those are available under GPL licences.
It was developed working under Linux/GNU operating system.

On top of that I have used commercially available IAR VisualSTATE
development environment kindly provided by IAR Inc. I would like to thank
Kent Rene Simonsen of IAR for patient replies to my numerous questions on
visualSTATE statechart language.




3. ABOUT SCOPE

SCOPE is a statechart compiler I develop along with my phd project. SCOPE
compiles statecharts as supported by IAR visualSTATE tool (or rather a
sublanguage of visualSTATE statecharts). Thus you will probably only be
interested in SCOPE if you are a visualSTATE user already, or you are also a
researcher working on statecharts.

The visualSTATE statecharts are subset of Harel's statecharts (Harel,1987)
incorporating most of the original language including concurrents states,
history and deep history states, internal signals, multiple target
transitions and other elements. These statecharts are very similar to UML
statecharts too.

SCOPE compiles vsp (project) and vsr (independent single system) files.
Currently only projects containing a single system are supported.  The target
language is C (ISO C99 standard). Other target languages might be considered
in future. The objective is to get a reactor code which is compact, fast
or/and has some desirable properties (for instance easily estimateable worst
case execution time).

In addition to normal functionality, SCOPE may also be used as a general
purpose anonymizer for visualSTATE models. This may be useful for
communicating the models to third parites without revealing the behaviour
(one purpose would be debugging tools and filing bug reports for vendors).


If you really need an explanation for name, SCOPE comes from Statechart
COmPilEr. Resolving scopes of dynamically scoped multiple targets transitions
was one of the very first problems we had to solve during implementation.




4. INSTALLATION NOTE

4.1. INSTALLATION UNDER LINUX (BINARY VERSION)

To run the binary version (compiled on RH 7.3, gcc-2.96, confirmed to work
on Debian 3.0) you will need also a running installation of muddy package.
The package named scope-bin.tar.gz presumably contains all you need. In
case you fail, I recommend using a source distribution.

1. Download scope-bin.tar.gz
2. Unpack it: tar xzvf scope-bin.tar.gz
   This will create directory scope-bin/ in current directory.
3. In this directory you wil find .so file with muddy library (libmuddy.so).
   Make it visible for your linker (for instance move it to some visible
   location like /usr/lib and run ldconfig - beware: must be root to do
   that).
4. Cross your fingers and run the scope executable (scope-bin/scope).
   If you see the usage message then it works. Linker error means that your
   ld does not see a library (most probably libmuddy.so). 

Generally it is a good idea to place .h and .c files contained in the
distribution in a directory which is searched by your C compiler by default.


4.2 COMPILING FROM SCRATCH UNDER LINUX

If you want to have a look on internals, want to run it on another version
of linux (or even non-linux) you will need to do the compilation yourself.
Start with ensuring that you have MoscowML installed (ver. >= 2.00). On top
of that you will need Muddy package (I used ver. 2.0-1) and gnu make.
MoscowML and Muddy can be found on respective websites (rpm packages
available).

1. download scope-src.tar.gz
2. tar xzvf scope-src.tar.gz
3. cd scope-src/
4. cross your fingers and "make scope"
5. try to run it: ./scope

You should see the usage info if compilation was succesfull. Contact me if
in trouble. 




2.3 INSTALLATION UNDER WINDOWS

Unfortunately current version of SCOPE does not work under Windows. This is
really a shame as Windows is a native invironment for original VisualSTATE.

Frankly speaking, Windows version is practically ready. Contacting me might
be a good way to convince me that someone needs it (which might result in
deploying it eventually). Note that simply compiling the linux version under
windows won't work (because the source distro does not contain windows
version of muddy).




2.4. FILE LIST

In scope-bin package:

scope	    - executable (scope.exe under windows)
MANUAL      - this minimal instructions
LICENSE     - current license for SCOPE
camlrt.dll  - MosowML runtime library (only in windows version, currently
              not deployed)
libmuddy.so - dynamic library for Muddy package.

The source distribution contains enormous amounts of files, so I give up
listing them here ;).




5. USAGE

Current description is very brief. Just type "scope<enter>" to see most
up-to-date list of options. Following chapters give several examples 




5.1 EXECUTABLE CODE SYNTHESIS

To be written.




EXAMPLES

Assume that you have a project in file project.vsp, containing a single
system (in file system.vsr). Let output be a directory where you want to put
generated C files. The basic call is:

	scope -d output/ -cC1 project.vsp 

The option -cC1 means to generate code by C1 code generator, which is the
only real code generator we have at the moment. By default the code is
generated in release mode. To generate debug code (containing assertions,
symbolic information about states and events) add a release option:

	scope --debug -d output/ -cC1 project.vsp 

If you omit the output option (-d) then current directory will be used
(beware, any C files having the same names as generated files are silently
overwritten). If -d refers to nonexisting directory, the directory will be
created.

The order of options generally matters. Only the options preceding a call to code
generator (-c) will affect its execution (these does not apply to several
options which generally seem to be usuful when applied globally, like for
example -d).

The files generated by C1 code generator are using the system name as root
for generated file names (various suffixes are added). If you want to
overwrite this behaviour use the -o option:

	scope -d output/ -o nameroot -cC1 project.vsp

You do not need to use vsp files. You can use a vsr file directly to generate
code. Simply use it instead:

	scope -d output/ -o nameroot -cC1 system.vsr

If your model is using external actions you can provide a header file with
prototypes:

	scope -d output/ --externhdr=myactions.h -cC1 project.vsp

Alternatively you can make SCOPE generate prototypes itself in the way
visualSTATE does (all the needed information is saved in the vsr file). For
this reason we have a special purpose code generator (called Cstubs) only
performing this task:

	scope -d output/ -o myctions -cCstubs project.vsp

This will generate to files myactions.h and myactions.c, former containing
prototypes, latter containing bodies. Of course the bodies are faked. These
are merely empty functions (or functions printing the action name on standard
output if --debug is used). We use this empty actions to evaluate properties
of control algorithm itself. If you only need action prototypes, simply
discard the generated .c file. 

In similar manner you can automatically generate a simple driver for you
program:

	scope -d output/ -Cdrv project.vsp

This will created a small .c file which includes some model specific
information (for instance preprocessor definitions for events) and a driver
routine (standard file: CodGenC_drv.c). This routine allows you to test your 
model interactively issuing commands (or piping them to standard input). For
instance:

  autoconf - toggles printing current configuration after each step (default:
             off)

  init     - initialize the model (note: there is no SE_RESET special event in 
  	     code synthesized by SCOPE). 

  macro <name> - process event <name>. Event parameters are not yet supported
                 in this generic testing routine.

Look into CodGenC_drv.c and CodGenC_tiny.c for examples on how to write your
own driver to the code generated by scope. There is no other description for
the moment.
 
	    
To summarize: compilation of the whole model in debug mode (using standard C
compiler on Unix system):

	scope -d output/ --debug -cC1 project.vsp -cCstubs -cCdrv
	cd output
	cc -I INCPATH system.c system_extern.c system_main.c -o executable

where INCPATH denotes a path containing standard .c and .h header files
distributed with SCOPE. May be omitted if you place them in destination
searched by default. 

Similar example in the release mode (compiler option for minimal size)
	
	scope -d output/ --release -cC1 project.vsp -cCstubs -cCd2rv
	cd output
	cc -I INCPATH -Os -DNDEBUG system.c system_extern.c system_main.c -o executable
	strip executable

You need to define NDEBUG in release compilation in order to deactivate some
assertions and eliminate some debugging related code from runtime
interpreter.  The last command (strip) removes all symbolic information from
the executable produced. 

Note that executable produced this way (in --release
mode of scope) will not contain generic testing library. It's driver is
virtually useless for testing anything else than code size. 
In practice you would subsitute system_main.c with your own driver routine
(translating external events to model events) and system_extern.c with real
implementation of actions (simple functions translating action names to
actions of actuators on the environment).

5.2 GENERATING HELPER CODE FOR VISUALSTATE PROGRAMS

You can now use scope to generate empty action functions (and functions used
in guards and expressions) in visualSTATE compatibility mode. You can use it 
for testing (reaction time, code size etc). The code generator is called
VSstubs (option -cVSstubs). Modes are the same as for native C1stubs
(debug/release).

Similarly VSdrv is a new code generator producing main() function for test
purposes which uses VS API (and not SCOPE API, which is different and
simpler). Modes are smoke/test/tiny.

 
5.3. ANONYMIZING PROJECTS

To anonymize a project file named "project.vsp" invoke

 		scope -d output/ -a Project.vsp 

This call makes scope to read the vsp file in together with associated
vsr files (as mentioned inside the vsp file itself). vsp file is looked
where indicated (in current directory if a plain name is given or in any
other directory if path is specified explicitly). vsr files are searched in
one of two ways. If vsp file contains a relative reference to vsr file then
scope tries first to find vsr file in relative location with respect to
location of vsp file (so if both vsp file and vsr files are in the same
directory vsr files can be found even if you call the tool from some
external location). If vsr files cannot be found in this location scope
retries the openning relatively to current directory. If vsr file name is an
absolute path scope just tries the path itself without other guesses.

Scope will create an output directory indicated if it does not exist (but only one level
creation in given path - will not create the whole subtree). Output file
names will be anonymous and put all in output. Regardless of initial
placement of vsr files now all ouput files will reside in target_dir and
will only contain relative paths in current directory. If project contained
two vsr files with the same name but in two distinct directories you will
get two files in target dir with different names. Default output directory
is current directory.

Scope anonymizes file names to some cryptic :) text. Extension is supposed
to be preserved (not really preserved: project file will always get a vsp
extension and rulebase file a vsr extension regardless of what extensions
had the original files. Remember that scope does not use extensions to
recognize file type). In target directory you will get exactly one file
with vsp extension and perhaps some more files with vsr extentions.  

CAUTION!!!: files in target directory which happen to have the same name
as output files are silently overwritten (no warning!!!). For safety always
specify a nonexisting or empty directory for output.

Also note that if you move the original project you may need to edit the vsp
file by hand to modify vsr file paths (if original vsr file contained
relative paths).

In the same way you can anonymize single vsr files. Simple give vsr file
name instead of vsp file name. Files are autmatically recognized by structure.
Note that this facility can only be used if you need to anonymize a single
vsr file not releated to any project. If your files are binded together by
vsp file you need to use vsp file to anonymize them as described above.
Otherwise global names may not be renamed consistently across files.


6. SOME EVALUATION

As from version 0-10 SCOPE generates code which is comparable or even
competes with code generated by visualSTATE. For small, simple models
visualSTATE usually wins, by a small factor. For bigger models SCOPE gets an
advantage, sometimes very clear. The programs are usually smaller and less
likely faster (but this also happens).

Rule of thumb is that visualSTATE is efficient for sparse flat models, while
SCOPE is more efficient for models with high density of various statecharts
elements. If your modelling style is very intensive and you tend to produce
terse designs by means of using what statechart offer (entry/exit actions,
history, hierarchy, concurrency, etc) then SCOPE will do better.


---------------------------------------------------------------------------

