README

Readme file for translation tool mdl2smv (Matlab's Stateflow into SMV)
Written by Alma Juarez <aljuarez@cs.uwaterloo.ca>, November 26 2008
(c) Alma Juarez, Nancy Day
Last Modified: May 9, 2012


** Quick overview of the files included in the package and steps to
run the translator. However, for a detailed explanation, please look
at: http://www.cs.uwaterloo.ca/~aljuarez/mdl2smv.html 

The files that are part of the package to create the mdl2smv executable 
tool are (to obtain the package, e-mail <aljuarez@uwaterloo.ca>):
  o mdlparser.l :	Token definitions to capture the Stateflow portion 
  					of the .mdl file and ignore the rest. The Stateflow 
  					objects captured are states, transitions, junctions, 
  					events, and data. 
  
  o mdlparser.y: 	Grammar definitions given the structure of the .mdl 
  					file.
  
  o data.h: 		Definition of constants for console display used 
  					during debugging. 
  					- The constant TREEDEBUG, when uncommented, creates 
  					  contents of file "tree.txt" (called in makeTree())
  					- The constant TRANSDEBUG, when uncommented, creates 
  					  contents of file nodes.txt (called in linkTrans())
  					- The constant PRINTLIST, when uncommented, creates 
  					  contents of file lists.txt (called in main)  
  					
  o structs.h: 		Declaration of function prototypes and of the generic 
  					node structure to hold any necessary information 
  					required for all Stateflow entries.

  o functions.c: 	C functions for the creation of nodes, and the addition 
  					of attributes to the respective list. Some functions 
  					for string manipulation are also included in this file.
  					
  o printing.c:		C functions for the SMV output creation. Each Stateflow 
  					design model becomes a separate module for SMV. The 
  					main functions included in printing.c are: printSMV,
  					printInputOutput, printStates, printInits, and
  					printSwitch.
  					
  o main.c: 		Calls for parsing routines and SMV creation functions.
  o Makefile: 		Makefile for for the generation of mdl2smv executable, 
  					using flex (the GNU version of lex) and bison (the GNU 
  					version of yacc), which need to be installed.


Once the executable is generated with the Makefile, type the following command 
at the prompt:

		./mdl2smv input_file_name.mdl OPTION > output_file_name.smv 
		 
where OPTION equal to "-t" indicates mdl2smv to create several transition 
	variable declarations, and if the option is not included, it generates 
	only one transition variable declaration (the default). 

NOTE1: In the mdl2smv translator, we assume that Stateflow design models 
adhere to the following syntax rules:

	- The designer should specify the type of data used for all input data, 
	output data, local data, etc. To do so, in the Stateflow Model Explorer, 
	click on the data variable. Then, set “Data type mode:” to “Built-in” 
	and set “Data type:” to appropriate type (double, boolean, etc.).
	- The designer should also specify the ranges of data values when 
	appropriate (e.g., when using doubles). To do so, in the Stateflow Model 
	Explorer, click on the data variable. Then, select “Value attributes” 
	and enter the "Minimum value" and "Maximum value". 
	- Quotes should not be part of the string of any label. 
	- Only numbers, letters, or an underscore should be included in names. 
	- Spaces should not be included in data names.
	- Ensure that actions written in transitions have the form “ x = y ; ”. 
	- Ensure that no two Stateflow models have the same name for their Simulink 
	block name (i.e., “Chart”, which is the default), and provide a meaningful 
	name. 
	- When using our translator, if a parsing error occur, designer should 
	ensure that all label strings are on a single line. (Parsing errors might 
	occur due to newline characters \n and \r). 
	- Outputs that are meant to be commands (e.g., request to actuators) need 
	to follow the naming convention set_ACT, where ACT is the name of the 
	device where the command is going to be executed (e.g., brakes).

NOTE2: As for events, we assume that some events will be used, for 
example, "Cancel" or "Error". If no events are defined, you might
have at least defined as events "no_event", which we define as the 
initial event.
