Wiki source code of SCCharts Development

Version 7.1 by ssm on 2016/04/21 16:23
Hide last authors
ssm 7.1 1 {{layout}}
2 {{layout-section ac:type="single"}}
3 {{layout-cell}}
4
5
ssm 5.1 6 This is a light-weight tutorial for developing additions for SCCharts in KIELER. It will use Eclipse, EMF, and Xtend and therefore, finishing the corresponding tutorials could prove useful. However, they are not a strict requirement for this tutorial.
ssm 1.1 7
8 = Preliminaries =
9
10 There's a few things to do before we dive into the tutorial itself. For example, to do Eclipse programming, you will have to get your hands on an Eclipse installation first. Read through the following sections to get ready for the tutorial tasks.
11
12 == Required Software ==
13
14 As you're going to develop for KIELER SCCharts we recommend to use the semantic Oomph setup as described in [[doc:KIELER.Getting Eclipse]] (Oomph Setup). However, you could also install all componentes by yourself. Please consult the other tutorials if you want to do that. You would need to install the Modeling Tools and the Xtext SDK.
ssm 7.1 15 {{/layout-cell}}
16 {{/layout-section}}
ssm 1.1 17
ssm 7.1 18 {{layout-section ac:type="two_equal"}}
19 {{layout-cell}}
20 Additionally, install the** EcoreViz** from the **Ecore Model Visualization** category from the **OpenKieler** update site: [[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/updatesite/nightly-openkieler/>>url:http://rtsys.informatik.uni-kiel.de/~~kieler/updatesite/nightly-openkieler/||rel="nofollow" shape="rect"]]. For this, choose //Install New Software...// in the //Help// tab.
21 {{/layout-cell}}
ssm 1.1 22
ssm 7.1 23 {{layout-cell}}
24 [[image:attach:InstallEcoreViz.png]]
25 {{/layout-cell}}
26 {{/layout-section}}
27
28 {{layout-section ac:type="single"}}
29 {{layout-cell}}
ssm 1.1 30 == Recommended Tutorials ==
31
32 We recommend that you have completed the following tutorials before diving into this one (or at least sweep over them). However, this is not a strict requirement.
33
34 1. [[doc:Eclipse Plug-ins and Extension Points]]
35 1. [[doc:Eclipse Modeling Framework (EMF)]]
36 11. This tutorial needs the turingmachine.ecore and the controller you've implemented in the EMF tutorial. If you did not complete the EMF tutorial, you may download a working turing machine here... (in the future).
37 1. (((
38 (% class="with-breadcrumbs" %)
39 [[Xtend 2 - Model Transformations>>url:http://rtsys.informatik.uni-kiel.de/confluence/display/TUT/Xtend+2+-+Model+Transformations||shape="rect"]]
40 )))
41
42 == Helpful Tutorials ==
43
44 When developing within the KIELER semantics team, you will most likely be confronted with Xtext and [[doc:KIELER.Lightweight Diagrams (KLighD)]]. The following tutorials may be helpful but not required for this tutorial.
45
46 1. [[doc:Xtext 2 - Creating a Grammar from Scratch]]
47 1. [[doc:Lightweight Diagrams (KLighD)]]
48
49 == Finding Documentation ==
50
ssm 5.1 51 You can find additional documentation to the aforementioned topics in the corresponding tutorials. If you get stuck with a particular topic, please consult that tutorial. For SCCharts, you should read the SCCharts confluence page in our wiki: [[doc:KIELER.SCCharts]]
ssm 1.1 52
53 As usual, documentation often gets obsolete or wrong if not maintained regularly, so please, if you find missing, misleading, or outdated information, please let us know.
54
55 Additionally, the following list will give a short overview over the most important publications:
56
57 * (% style="color: rgb(0,0,0);" %)**Main paper:**
58 Reinhard von Hanxleden and Björn Duderstadt and Christian Motika and Steven Smyth and Michael Mendler and Joaquín Aguado and Stephen Mercer and Owen O’Brien. SCCharts: Sequentially Constructive Statecharts for Safety-Critical Applications. In (% class="cmti-10" %)Proc. ACM SIGPLAN Conference on Programming Language Design(%%) (% class="cmti-10" %)and Implementation (PLDI’14)(%%), Edinburgh, UK, June 2014. ACM. (%%)[[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/pldi14.pdf||shape="rect"]](% style="color: rgb(0,0,0);" %), (%%)[[talk>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/talks/pldi14-talk.pdf||shape="rect"]](% style="color: rgb(0,0,0);" %), (%%)[[bib>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/cgi-bin/bibcgi.cgi?key=vonHanxledenDM+14||shape="rect"]]
59 * **SLIC Compilation:**
60 (% style="color: rgb(0,0,0);" %)Christian Motika and Steven Smyth and Reinhard von Hanxleden. Compiling SCCharts—A Case-Study on Interactive Model-Based Compilation. In (% class="cmti-10" %)Proceedings of(%%) (% class="cmti-10" %)the 6th International Symposium on Leveraging Applications of Formal(%%) (% class="cmti-10" %)Methods, Verification and Validation (ISoLA 2014)(%%), volume 8802 of (% class="cmti-10" %)LNCS(%%), page 443–462, Corfu, Greece, October 2014. The (%%)[[original publication>>url:http://dx.doi.org/10.1007/978-3-662-45234-9||shape="rect"]](% style="color: rgb(0,0,0);" %) is available at (%%)[[http:~~/~~/link.springer.com>>url:http://link.springer.com/||shape="rect"]](% style="color: rgb(0,0,0);" %). (%%)[[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/isola14.pdf||shape="rect"]](% style="color: rgb(0,0,0);" %), (%%)[[bib>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/cgi-bin/bibcgi.cgi?key=MotikaSvH14||shape="rect"]]
61 * **Theoretical Foundations:**
62 (% style="color: rgb(0,0,0);" %)Reinhard von Hanxleden and Michael Mendler and Joaquín Aguado and Björn Duderstadt and Insa Fuhrmann and Christian Motika and Stephen Mercer and Owen O’Brien and Partha Roop. Sequentially Constructive Concurrency—A Conservative Extension of the Synchronous Model of Computation. (% class="cmti-10" %)ACM Transactions on Embedded Computing(%%) (% class="cmti-10" %)Systems, Special Issue on Applications of Concurrency to System Design(%%), 13(4s):144:1–144:26, July 2014. (%%)[[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/tecs14.pdf||shape="rect"]](% style="color: rgb(0,0,0);" %), (%%)[[bib>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/cgi-bin/bibcgi.cgi?key=vonHanxledenMA+14||shape="rect"]]
63 * **Overview and High-Level Transformations in Detail:**
64 (% style="color: rgb(0,0,0);" %)Reinhard von Hanxleden and Björn Duderstadt and Christian Motika and Steven Smyth and Michael Mendler and Joaquín Aguado and Stephen Mercer and Owen O’Brien. SCCharts: Sequentially Constructive Statecharts for Safety-Critical Applications. Technical Report 1311, Christian-Albrechts-Universität zu Kiel, Department of Computer Science, December 2013. ISSN 2192-6247. (%%)[[pdf>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/downloads/papers/report-1311.pdf||shape="rect"]](% style="color: rgb(0,0,0);" %), (%%)[[bib>>url:http://rtsys.informatik.uni-kiel.de/~~biblio/cgi-bin/bibcgi.cgi?key=vonHanxledenDM+13b||shape="rect"]]
65
66 = The SCCharts Metamodel =
67
ssm 4.1 68 Navigate to the models folder of the plugin {{code language="none"}}de.cau.cs.kieler.sccharts{{/code}}. Here, open the {{code language="none"}}sccharts.ecore{{/code}} and right-click on the {{code language="none"}}sccharts.ecore{{/code}} file and select //Visualize Ecore Model//. Since you also installed **EcoreViz** from the OpenKieler Suite, you should now see a graphical representation of the SCCharts metamodel. Every SCChart will be a model of this metamodel.
ssm 1.1 69
70 IMAGE
71
72 Try to understand most parts of the metamodel. You don't have to understand every detail but you should get the idea.
73
74 ==== Model Task ====
75
ssm 5.1 76 1. (% style="line-height: 20.0px;" %)Answer the following questions
77 11. (% style="line-height: 20.0px;" %)Name the class of the root element of an SCChart
78 11. (% style="line-height: 20.0px;" %)How do you describe a superstate in the model?
79 11. (% style="line-height: 20.0px;" %)What is a valued object?
80 11. (% style="line-height: 20.0px;" %)How do you get the type of an interface variable?
81 11. Outline the relationship between states, regions, transitions, and valued objects
82 11. (% style="line-height: 20.0px;" %)What other metamodels are needed for the SCCharts metamodel and write down which one is needed for what?
83 1. (% style="line-height: 20.0px;" %)Write down (on paper, text editor, etc) how the following SCChart models look like
84 11. (% style="line-height: 1.42857;" %)Open the wiki page that explains the [[doc:KIELER.Textual SCCharts Language SCT]].
85 11. (% style="line-height: 1.4286; line-height: 1.4286" %)Search the (%%)//SCChart, Initial State, State, Transition and Immediate Transition //example and ...
86 111. write down (on paper or text editor, etc) how the model of that SCChart looks like.
87 111. The user now marks C as final. What has to be changed in the model? What semantic problem do you see?
88 11. (% style="line-height: 1.42857;" %)Now, navigate to the //Super State: Strong Abort Transition //example. Write down (on paper) how the model of that SCCharts looks like.
89 11. And finally a more sophisticated model: Write down the model of ABO (from [[doc:KIELER.Examples]]).
ssm 4.1 90
91 = Creating SCCharts Models Programmatically =
92
93 == Creating a Test Project ==
94
95 We need a project for testing. Do the following:
96
97 1. Create a new empty //Plug-In Project//.
98 1. Add the project that contains the sccharts metamodel as a dependency of your new project through the //Plugin Manifest Editor//.
99 1. Create a simple Java class that implements a main method. Hint: In a new Java class, simply type main and hit Ctrl+Space. Eclipse content assist will create the method for you.
100
101 == Creating a Model ==
102
103 To create a model programmatically you cannot directly use the Java classes generated for the model. Instead, the main package contains interfaces for all of your model object classes. The {{code language="none"}}impl{{/code}} package contains the actual implementation and the {{code language="none"}}util{{/code}} package contains some helper classes. Do not instantiate objects directly by manually calling {{code language="none"}}new{{/code}}. EMF generates a Factory to create new objects. The factory itself uses the singleton pattern to get access to it:
104
105 {{code language="java"}}
106 SCChartsFactory sccFactory = SCChartsFactory.eINSTANCE;
107 State state = sccFactory .createState();
108 Transition transition = sccFactory .createTransition();
109 {{/code}}
110
111 Important: The SCCharts grammar is build on top of several other grammars. Therefore, not all language objects can be found in the SCCharts factory. For example, all expression elements are part of the KExpressions grammar and hence, have their own factory. If you need other factories, don't forget to add the corresponding plugin to your plugin dependency list.
112
113 {{code language="java"}}
114 KExpressionsFactory kFactory = KExpressionsFactory.eINSTANCE;
115 BooleanValue boolValue = kFactory.createBooleanValue();
116 {{/code}}
117
118 For all simple attributes, there are getter and setter methods:
119
120 {{code language="java"}}
121 state.setId("Root");
122 boolValue.setValue(true);
123 {{/code}}
124
125 Simple references (multiplicity of 1) also have getters and setters:
126
127 {{code language="java"}}
128 transition.setTrigger(boolValue);
129 {{/code}}
130
131 List references (multiplicity of > 1) have only a list getter, which is used to manipulate the list:
132
133 {{code language="java"}}
134 state.outgoingTransitions.add(transition);
135 {{/code}}
136
137 == Saving a Model ==
138
139 EMF uses the [[Eclipse Resource concept>>url:http://help.eclipse.org/juno/topic/org.eclipse.platform.doc.isv/guide/resInt.htm?cp=2_0_10||rel="nofollow" shape="rect" class="external-link"]] to save models to files and load models from files. It can use different //Resource Factories// that determine how exactly models are serialized. We will use the [[XMIResourceFactoryImpl>>url:http://download.eclipse.org/modeling/emf/emf/javadoc/2.8.0/org/eclipse/emf/ecore/xmi/impl/XMIResourceFactoryImpl.html||rel="nofollow" shape="rect" class="external-link"]] to save our models to XML files:
140
141 1. Add a dependency to the {{code language="none"}}org.eclipse.emf.ecore.xmi{{/code}} plug-in.
142 1. (((
143 Use something like the following code to save the model from above:
144
145 {{code language="java"}}
146 // Create a resource set.
147 ResourceSet resourceSet = new ResourceSetImpl();
148
149 // Register the default resource factory -- only needed for stand-alone!
150 // this tells EMF to use XML to save the model
151 resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put(
152 Resource.Factory.Registry.DEFAULT_EXTENSION, new SCTResourceFactoryImpl());
153 // Get the URI of the model file.
154 URI fileURI = URI.createFileURI(new File("myABO.sct").getAbsolutePath());
155
156 // Create a resource for this file.
157 Resource resource = resourceSet.createResource(fileURI);
158
159 // Add the model objects to the contents.
160 resource.getContents().add(myModel);
161
162 // Save the contents of the resource to the file system.
163 try
164 {
165 resource.save(Collections.EMPTY_MAP); // the map can pass special saving options to the operation
166 } catch (IOException e) {
167 /* error handling */
168 }
169 {{/code}}
170 )))
171
172 ==== Model Creation Task ====
173
174 With these information out of the way, on we go to some model creation:
175
176 1. Programmatically create a valid model of ABO in the {{code language="none"}}main(){{/code}} method.
177 1. Run the {{code language="none"}}main(){{/code}} method by right-clicking its class and selecting //Run as// -> //Java Application//. Note that this runs your {{code language="none"}}main(){{/code}} method as a simple Java program, not a complete Eclipse application. EMF models can be used in any simple Java context, not just in Eclipse applications.
178 1. Execute the main method.
179 1. Inspect your SCT file.
180 1. Start your SCChart Editor Eclipse instance and load your SCT file. KLighD should now be able to visualize your ABO correctly.
181
182 = Transforming SCCharts =
183
184 Transformations from one model to another may be performed within the same metamodel or from metamodel to a different metamodel. Both methods are used in KIELER and in principle they do not really differ in implementation. Nevertheless, if working within the same metamodel you should keep in mind that you're potentially changing the actual model instead of changing another instance (after copying). Both is possible. Just make sure that you know what you're doing.
185
186 Now, you're going to transform the normalized form of HandleA from ABO to an SCG. The Sequentially Constructive Graph is a control-flow graph which can be seen as another representation of the same program. The SCG of the normalized version of ABO's HandleA is depicted on the right.
187
188 |(((
189 {{code}}
190 scchart ABO_norm_HandleA {
191 input output bool A;
192 input output bool B;
193 output bool O1;
194 output bool O2;
195 region HandleA:
196 initial state WaitA
197 --> _S immediate with A
198 --> _Pause immediate;
199 final state DoneA;
200 state _S
201 --> _S2 immediate with / B = true;
202 state _S2
203 --> DoneA immediate with / O1 = true;
204 state _Pause
205 --> _Depth;
206 state _Depth
207 --> _S immediate with A
208 --> _Pause immediate;
209 }
210 {{/code}}
211 )))|(((
212 [[image:attach:abo_norm_HandleA.png]]
213 )))|(% colspan="1" %)(% colspan="1" %)
214 (((
215 [[image:attach:abo_scg_HandleA.png]]
216 )))
217
218 The next figure depicts the direct mapping from normalized SCCharts to their corresponding SCG.
219
220 [[image:attach:sccharts-scg.png]]
221
222 Inspect the metamodel of the SCGs in plugin de.cau.cs.kieler.scg. SCGs are used for analyses and optimization and include a lot of additional elements. However, for this tutorial it should be sufficient to look at the SCGraph class, its nodes attribute, the important node classes and the controlflow class. Important nodes for this SCG are entry, exit, assignment, conditional,
223
224 ==== Transformation Task ====
225
226 Write a transformation that transforms your normalized version of ABO's HandleA into its corresponding SCG.
227
228 1. (((
229 **Writing a Model Transformation**
230
231 This time we want you to integrate your transformation into your SCCharts Editor instance. Therefore,...
232 (% style="color: rgb(51,51,51);line-height: 1.66667;" %)\\
233
234 1. Add a new package 
235
236 {{code language="none"}}
237 <project>.transformations
238 {{/code}} to your project.
239 1. Add an //Xtend Class// to the new package.
240 1. If you notice that your new class is marked with an error marker because of a missing dependency of the new plug-in project to 
241
242 {{code language="none"}}
243 org.eclipse.xtext.xbase.lib, 
244 {{/code}}you can hover over the error with your mouse and have Eclipse add all libraries required by Xtend to your project.
245 1.
246
247 Define an entry method for the transformation that takes an SCChart program instance as an argument and returns an SCG {{code language="none"}}Program{{/code}}. You can use the following (incomplete) method as a starting point:
248
249 (((
250 (% class="syntaxhighlighter sh-confluence nogutter java" %)
251 (((
252
253
254 |(((
255 (% class="container" title="Hint: double-click to select code" %)
256 (((
257 (% class="line number1 index0 alt2" %)
258 (((
259 {{code language="none"}}
260 /**
261 {{/code}}
262 )))
263
264 (% class="line number2 index1 alt1" %)
265 (((
266 {{code language="none"}}
267  
268 {{/code}}
269
270 {{code language="none"}}
271 * Transforms a given SCCharts program into an SCG.
272 {{/code}}
273 )))
274
275 (% class="line number3 index2 alt2" %)
276 (((
277 {{code language="none"}}
278  
279 {{/code}}
280
281 {{code language="none"}}
282 *
283 {{/code}}
284 )))
285
286 (% class="line number4 index3 alt1" %)
287 (((
288 {{code language="none"}}
289 */
290 {{/code}}
291 )))
292
293 (% class="line number8 index7 alt1" %)
294 (((
295 {{code language="none"}}
296 def SCGraph transform(State rootState) {
297 {{/code}}
298 )))
299
300 (% class="line number9 index8 alt2" %)
301 (((
302 {{code language="none"}}
303     
304 {{/code}}
305
306 {{code language="none"}}
307 // Create the SCG
308 {{/code}}
309 )))
310
311 (% class="line number10 index9 alt1" %)
312 (((
313 {{code language="none"}}
314     
315 {{/code}}
316
317 {{code language="none"}}
318 val scg = SCGraphFactory::eINSTANCE.createSCGraph()
319 {{/code}}
320 )))
321
322 (% class="line number11 index10 alt2" %)
323 (((
324 {{code language="none"}}
325   
326 {{/code}}
327 )))
328
329 (% class="line number12 index11 alt1" %)
330 (((
331 {{code language="none"}}
332     
333 {{/code}}
334
335 {{code language="none"}}
336 // TODO: Your transformation code
337 {{/code}}
338 )))
339
340 (% class="line number13 index12 alt2" %)
341 (((
342 {{code language="none"}}
343   
344 {{/code}}
345 )))
346
347 (% class="line number14 index13 alt1" %)
348 (((
349 {{code language="none"}}
350     
351 {{/code}}
352
353 {{code language="none"}}
354 // Return the transformed program
355 {{/code}}
356 )))
357
358 (% class="line number15 index14 alt2" %)
359 (((
360 {{code language="none"}}
361     scg
362 {{/code}}
363 )))
364
365 (% class="line number16 index15 alt1" %)
366 (((
367 {{code language="none"}}
368 }
369 {{/code}}
370 )))
371 )))
372 )))
373
374
375 )))
376 )))
377
378 (((
379 (% class="syntaxhighlighter nogutter java" %)
380 (((
381 There's a few points to note here:
382 )))
383 )))
384
ssm 1.1 385 \\
ssm 4.1 386
387 1.
388 1*. Lines in Xtend code don't have to and with a semicolon.
389 1*. We have been explicit about the method's return type, but we could have easily omitted it, letting Xtend infer the return type.
390 1*. The keyword 
391
392 {{code language="none"}}
393 val
394 {{/code}} declares a constant, while 
395
396 {{code language="none"}}
397 var
398 {{/code}} declares a variable. Try to make do with constants where possible.
399 1*. The methods you call should be declared as 
400
401 {{code language="none"}}
402 def private
403 {{/code}} since they are implementation details and shouldn't be called by other classes.
404 1*. You may be tempted to add a few global variables that hold things like a global input variable or a pointer to the current state. While you could to that, 
405
406 {{code language="none"}}
407 def create 
408 {{/code}}methods might offer a better alternative...
409 \\
410 1. Replace the TODO with an transformation code that takes an extended BF program and transforms it into an semantically equivalent BF program that only uses standard BF instructions. 
411 HINT: Some of the extended BF commands can only be expressed by standard operations if you can write to other cells. Therefore you are allowed to perform side effects on the tape.
412 1. Open the //Plug-In Manifest Editor// and switch to the Runtime tab. Add the package containing your transformation to the list of exported packages. (You may have to check the //Show non-Java packages// option in the //Exported Packages// dialog to see the package.)
413 \\
414 )))
415 1. **Verify your generated SCG**. If you added your transformation correctly, the SCG should be displayed automatically as soon as selected. If your SCG looks like the SCG depicted earlier, then everything is fine.
416 1. Check your SCG semantically. Is there anything you could improve/optimize? 
417 11. Write a second transformation (just as before) and add it to the transformation chain right after the transformation you already added.
418 11. Optimize the given SCG and compare the result with the previous one.
419 11. Make sure that the two SCGs are still semantically identical.
420
421 Congratulations! You finished the SCCharts Development Tutorial. Ask your supervisor for further instructions!
422
423
ssm 7.1 424 {{/layout-cell}}
425 {{/layout-section}}
426 {{/layout}}

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage