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" 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 - process event . 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. ---------------------------------------------------------------------------