1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd-->
<html xmlns="http://www.w3.org/1999/xhtml"
>
<head><title>Component Overview</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
<meta name="originator" content="TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/)" />
<!-- xhtml,3,next,html -->
<meta name="src" content="etrice-doc.tex" />
<meta name="date" content="2013-07-04 14:25:00" />
<link rel="stylesheet" type="text/css" href="etrice-doc.css" />
</head><body
>
<!--l. 94--><div class="crosslinks"><p class="noindent">[<a
href="etrice-docse35.html" >prev</a>] [<a
href="etrice-docse35.html#tailetrice-docse35.html" >prev-tail</a>] [<a
href="#tailetrice-docse36.html">tail</a>] [<a
href="etrice-docch9.html#etrice-docse36.html" >up</a>] </p></div>
<h3 class="sectionHead"><span class="titlemark">9.2 </span> <a
id="x47-1350009.2"></a>Component Overview</h3>
<!--l. 96--><p class="noindent" >
</p>
<h4 class="subsectionHead"><span class="titlemark">9.2.1 </span> <a
id="x47-1360009.2.1"></a>Room Language Overview</h4>
<!--l. 98--><p class="noindent" >We assume that the reader is familiar with the Xtext concepts. So we concentrate on the details of our
implementation that are worth to be pointed out.
</p><!--l. 101--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1370009.2.1"></a>Model Tweaks</h5>
<!--l. 103--><p class="noindent" >The Room EMF model is inferred from the grammar. However, this powerful mechanism has to be tweaked at
some places. This is done in the <span
class="ec-lmsso-10">/org.eclipse.etrice.core.room/src/org/eclipse/etrice/core/RoomPostprocessor.ext</span>
which is written in the legacy Xtend language.
</p><!--l. 109--><p class="noindent" >The following parts of the model are changed or added: </p>
<ul class="itemize1">
<li class="itemize">the default
<div class="verbatim" id="verbatim-21">
multiplicity
</div>
<!--l. 111--><p class="nopar" > of the <span
class="ec-lmtt-10">Port </span>is set to 1
</p></li>
<li class="itemize">the operation <span
class="ec-lmtt-10">isReplicated </span>is added to the <span
class="ec-lmtt-10">Port</span>
</li>
<li class="itemize">the default <span
class="ec-lmtt-10">size </span>of the <span
class="ec-lmtt-10">ActorRef </span>is set to 1
</li>
<li class="itemize">an operation <span
class="ec-lmtt-10">getName </span>is add to the <span
class="ec-lmtt-10">State </span>class
</li>
<li class="itemize">an operation <span
class="ec-lmtt-10">getName </span>is add to the <span
class="ec-lmtt-10">StateGraphItem </span>class
</li>
<li class="itemize">an operation <span
class="ec-lmtt-10">getGeneralProtocol </span>is added to the <span
class="ec-lmtt-10">InterfaceItem</span></li></ul>
<!--l. 119--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1380009.2.1"></a>Imports by URI Using Namespaces</h5>
<!--l. 121--><p class="noindent" >The import mechanism employed is based on URIs. This is configured for one part in the GenerateRoom.mwe2
model workflow by setting the fragments ImportURIScopingFragment and ImportUriValidator). For the other
part it is configured in the Guice modules by binding </p>
<ul class="itemize1">
<li class="itemize"><span
class="ec-lmtt-10">PlatformRelativeUriResolver </span>– this class tries to convert the import URI into a platform
relative URI. It also replaces environment variables written in $ with their respective values.
</li>
<li class="itemize"><span
class="ec-lmtt-10">ImportedNamespaceAwareLocalScopeProvider </span>– this is a standard scope provider which is
aware of namespaces
</li>
<li class="itemize"><span
class="ec-lmtt-10">GlobalNonPlatformURIEditorOpener </span>– this editor opener tries to convert general URIs into
platform URIs because editors can only open platform URIs
</li>
<li class="itemize"><span
class="ec-lmtt-10">ImportAwareHyperlinkHelper </span>– turns the URI part of an import into a navigatable hyper link</li></ul>
<!--l. 134--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1390009.2.1"></a>Naming</h5>
<!--l. 136--><p class="noindent" >Two classes provide object names used for link resolution and for labels. The <span
class="ec-lmtt-10">RoomNameProvider </span>provides
frequently used name strings, some of them are hierarchical like State paths. The <span
class="ec-lmtt-10">RoomFragmentProvider</span>
serves a more formal purpose since it provides a link between EMF models (as used by the diagram editors)
and the textual model representation used by Xtext.
</p><!--l. 142--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1400009.2.1"></a>Helpers</h5>
<!--l. 144--><p class="noindent" >The <span
class="ec-lmtt-10">RoomHelpers </span>class provides a great deal of static methods that help retrieve frequently used information
from the model. Among many, many others </p>
<ul class="itemize1">
<li class="itemize"><span
class="ec-lmtt-10">getAllEndPorts(ActorClass) </span>- returns a list of all end ports of an actor class including
inherited ones
</li>
<li class="itemize"><span
class="ec-lmtt-10">getInheritedActionCode(Transition, ActorClass) </span>- get the inherited part of a transition’s
action code
</li>
<li class="itemize"><span
class="ec-lmtt-10">getSignature(Operation) </span>- returns a string representing the operation signature suited for a
label</li></ul>
<!--l. 156--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1410009.2.1"></a>Validation</h5>
<!--l. 158--><p class="noindent" >Validation is used from various places. Therefore all validation code is accumulated in the @ValidationUtil@
class. All methods are static and many of them return a Result object which contains information about the
problem detected as well as object and feature as suited for most validation purposes.
</p><!--l. 162--><p class="noindent" >
</p>
<h4 class="subsectionHead"><span class="titlemark">9.2.2 </span> <a
id="x47-1420009.2.2"></a>Config Language Overview</h4>
<!--l. 164--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1430009.2.2"></a>Model Tweaks</h5>
<!--l. 166--><p class="noindent" >A couple of operations are added to the ConfigModel </p>
<ul class="itemize1">
<li class="itemize"><span
class="ec-lmtt-10">getActorClassConfigs</span>
</li>
<li class="itemize"><span
class="ec-lmtt-10">getActorInstanceConfigs</span>
</li>
<li class="itemize"><span
class="ec-lmtt-10">getProtocolClassConfigs</span>
</li>
<li class="itemize"><span
class="ec-lmtt-10">getSubSystemConfigs</span></li></ul>
<!--l. 174--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1440009.2.2"></a>Imports by URI Using Namespaces</h5>
<!--l. 176--><p class="noindent" >Imports are treated like in Room language, section <span
class="ec-lmsso-10">Imports by URI Using Namespaces</span>.
</p><!--l. 178--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1450009.2.2"></a>Util</h5>
<!--l. 180--><p class="noindent" >A set of static utility methods can be found in the <span
class="ec-lmtt-10">ConfigUtil </span>class.
</p><!--l. 182--><p class="noindent" >
</p>
<h4 class="subsectionHead"><span class="titlemark">9.2.3 </span> <a
id="x47-1460009.2.3"></a>Aggregation Layer Overview</h4>
<!--l. 184--><p class="noindent" >The eTrice Generator Model (genmodel) serves as an aggregation layer. Its purpose is to allow easy access to
information which is implicitly contained in the Room model but not simple to retrieve. Examples of this are
the state machine with inherited items or a list of all triggers active at a state in the order in which
they will be evaluated or the actual peer port of an end port (following bindings through relay
ports).
</p><!--l. 190--><p class="noindent" >The Generator Model is created from a list of Room models by a call of the
</p>
<div class="verbatim" id="verbatim-22">
createGeneratorModel(List<RoomModel>, boolean)
</div>
<!--l. 192--><p class="nopar" >
</p><!--l. 194--><p class="noindent" >method of the <span
class="ec-lmtt-10">GeneratorModelBuilder </span>class.
</p><!--l. 196--><p class="noindent" >The <span
class="ec-lmtt-10">Root </span>object of the resulting Generator Model provides chiefly two things: </p>
<ul class="itemize1">
<li class="itemize">a tree of instances starting at each <span
class="ec-lmtt-10">SubSystem </span>with representations of each <span
class="ec-lmtt-10">ActorInstance </span>and
<span
class="ec-lmtt-10">PortInstance</span>
</li>
<li class="itemize">for each <span
class="ec-lmtt-10">ActorClass </span>a corresponding <span
class="ec-lmtt-10">ExpandedActorClass </span>with an explicit state machine
containing all inherited state graph items</li></ul>
<!--l. 204--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1470009.2.3"></a>The Instance Model</h5>
<!--l. 206--><p class="noindent" >The instance model allows easy access to instances including their unique paths and object IDs. Also it is
possible to get a list of all peer port instances for each port instance without having to bother about port and
actor replication.
</p><!--l. 210--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1480009.2.3"></a>The Expanded Actor Class</h5>
<!--l. 212--><p class="noindent" >The expanded actor class contains, as already mentioned, the complete state machine of the actor class. This
considerably simplifies the task of state machine generation. Note that the generated code always
contains the complete state machine of an actor. I.e. no target language inheritance is used to
implement the state machine inheritance. Furthermore the <span
class="ec-lmtt-10">ExpandedActorClass </span>gives access to
</p>
<ul class="itemize1">
<li class="itemize"><span
class="ec-lmtt-10">getIncomingTransitions(StateGraphNode) </span>– the set of incoming transition of a
<span
class="ec-lmtt-10">StateGraphNode </span>(<span
class="ec-lmtt-10">State</span>, <span
class="ec-lmtt-10">ChoicePoint </span>or <span
class="ec-lmtt-10">TransitionPoint</span>)
</li>
<li class="itemize"><span
class="ec-lmtt-10">getOutgoingTransitions(StateGraphNode) </span>– the set of outgoing transition of a
<span
class="ec-lmtt-10">StateGraphNode</span>
</li>
<li class="itemize"><span
class="ec-lmtt-10">getActiveTriggers(State) </span>– the triggers that are active in this <span
class="ec-lmtt-10">State </span>in the order they are
evaluated</li></ul>
<!--l. 226--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1490009.2.3"></a>Transition Chains</h5>
<!--l. 228--><p class="noindent" >By transition chains we denote a connected subset of the (hierarchical) state machine that starts with a
transition starting at a state and continues over transitional state graph nodes (choice points and transition
points) and continuation transitions until a state is reached. In general a transition chain starts at one state
and ends in several states (the chain may branch in choice points). A <span
class="ec-lmtt-10">TransitionChain </span>of a
transition is retrieved by a call of <span
class="ec-lmtt-10">getChain(Transition) </span>of the <span
class="ec-lmtt-10">ExpandedActorClass</span>. The
<span
class="ec-lmtt-10">TransitionChain </span>accepts an <span
class="ec-lmtt-10">ITransitionChainVisitor </span>which is called along the chain to generate the
action codes of involved transitions and the conditional statements arising from the involved choice
points.
</p><!--l. 238--><p class="noindent" >
</p>
<h4 class="subsectionHead"><span class="titlemark">9.2.4 </span> <a
id="x47-1500009.2.4"></a>Generator Overview</h4>
<!--l. 240--><p class="noindent" >There is one plug-in that consists of base classes and some generic generator parts which are re-used by all
language specific generators
</p><!--l. 243--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1510009.2.4"></a>Base Classes and Interfaces</h5>
<!--l. 245--><p class="noindent" >We just want to mention the most important classes and interfaces.
</p>
<ul class="itemize1">
<li class="itemize">
<div class="flushleft"
>
<!--l. 248--><p class="noindent" >
<span
class="ec-lmtt-10">ITranslationProvider </span>— this interface is used by the <span
class="ec-lmtt-10">DetailCodeTranslator </span>for the language
dependent translation of e.g. port.message() notation in detail code</p></div>
</li>
<li class="itemize"><span
class="ec-lmtt-10">AbstractGenerator </span>— concrete language generators should derive from this base class
</li>
<li class="itemize">
<div class="flushleft"
>
<!--l. 252--><p class="noindent" >
<span
class="ec-lmtt-10">DefaultTranslationProvider </span>— a stub implementation of <span
class="ec-lmtt-10">ITranslationProvider </span>from which
clients may derive</p></div>
</li>
<li class="itemize"><span
class="ec-lmtt-10">Indexed </span>— provides an indexed iterable of a given iterable
</li>
<li class="itemize"><span
class="ec-lmtt-10">GeneratorBaseModule </span>— a Google Guice module that binds a couple of basic services. Concrete
language generators should use a module that derives from this</li></ul>
<!--l. 259--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1520009.2.4"></a>Generic Generator Parts</h5>
<!--l. 261--><p class="noindent" >The generic generator parts provide code generation blocks on a medium granularity. The language dependent
top level generators embed those blocks in a larger context (file, class, ...). Language dependent low level
constructs are provided by means of an <span
class="ec-lmtt-10">ILanguageExtension</span>. This extension and other parts of the generator
be configured using Google Guice dependency injection.
</p>
<!--l. 266--><p class="noindent" ><span class="paragraphHead"><a
id="x47-1530009.2.4"></a><span
class="ec-lmssbx-10">GenericActorClassGenerator</span></span>
The <span
class="ec-lmtt-10">GenericActorClassGenerator </span>generates constants for the interface items of a actor. Those constants
are used by the generated state machine.
</p>
<!--l. 271--><p class="noindent" ><span class="paragraphHead"><a
id="x47-1540009.2.4"></a><span
class="ec-lmssbx-10">GenericProtocolClassGenerator</span></span>
The <span
class="ec-lmtt-10">GenericProtocolClassGenerator </span>generates message ID constants for a protocol.
</p>
<!--l. 275--><p class="noindent" ><span class="paragraphHead"><a
id="x47-1550009.2.4"></a><span
class="ec-lmssbx-10">GenericStateMachineGenerator</span></span>
</p>
<div class="flushleft"
>
<!--l. 277--><p class="noindent" >
The <span
class="ec-lmtt-10">GenericStateMachineGenerator </span>generates the complete state machine implementation. The
skeleton of the generated code is</p></div>
<ul class="itemize1">
<li class="itemize">definition state ID constants
</li>
<li class="itemize">definition of transition chain constants
</li>
<li class="itemize">definition of trigger constants
</li>
<li class="itemize">entry, exit and action code methods
</li>
<li class="itemize">the <span
class="ec-lmtt-10">exitTo </span>method
</li>
<li class="itemize">the <span
class="ec-lmtt-10">executeTransitionChain </span>method
</li>
<li class="itemize">the <span
class="ec-lmtt-10">enterHistory </span>method
</li>
<li class="itemize">the <span
class="ec-lmtt-10">executeInitTransition </span>method
</li>
<li class="itemize">the <span
class="ec-lmtt-10">receiveEvent </span>method</li></ul>
<!--l. 292--><p class="noindent" >The state machine works as follows. The main entry method is the <br
class="newline" /><span
class="ec-lmtt-10">receiveEvent </span>method. This is the case for both, data driven (polled) and event driven state machines. Then
a number of nested switch/case statements evaluates trigger conditions and derives the transition chain that is
executed. If a trigger fires then the <span
class="ec-lmtt-10">exitTo </span>method is called to execute all exit codes involved. Then the
transition chain action codes are executed and the choice point conditions are evaluated in the
<span
class="ec-lmtt-10">executeTransitionChain </span>method. Finally the history of the state where the chain ends is entered and all
entry codes are executed by <span
class="ec-lmtt-10">enterHistory</span>.
</p><!--l. 300--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1560009.2.4"></a>The Java Generator</h5>
<!--l. 302--><p class="noindent" >The Java generator employs the generic parts of the generator. The <span
class="ec-lmtt-10">JavaTranslationProvider</span>
is very simple and only handles the case of sending a message from a distinct replicated port:
<span
class="ec-lmtt-10">replPort[2].message()</span>. Other cases are handled by the base class by returning the original
text.
</p><!--l. 306--><p class="noindent" >The <span
class="ec-lmtt-10">DataClassGen </span>uses Java inheritance for the generated data classes. Otherwise it is pretty much straight
forward.
</p><!--l. 309--><p class="noindent" >The <span
class="ec-lmtt-10">ProtocolClassGen </span>generates a class for the protocol with nested static classes for regular and
conjugated ports and similar for replicated ports.
</p><!--l. 312--><p class="noindent" >The <span
class="ec-lmtt-10">ActorClassGen </span>uses Java inheritance for the generated actor classes. So ports, SAPs and attributes and
detail code methods are inherited. Not inherited is the state machine implementation.
</p><!--l. 315--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1570009.2.4"></a>The ANSI-C Generator</h5>
<!--l. 317--><p class="noindent" >The C generator translates data, protocol and actor classes into structs together with a set of methods
that operate on them and receive a pointer to those data (called <span
class="ec-lmtt-10">self </span>in analogy to the implicit
C++ <span
class="ec-lmtt-10">this </span>pointer). No dynamic memory allocation is employed. All actor instances are statically
initialized. One of the design goals for the generated C code was an optimized footprint in terms of
memory and performance to be able to utilize modeling with ROOM also for tiny low end micro
controllers.
</p><!--l. 324--><p class="noindent" >
</p>
<h5 class="subsubsectionHead"><a
id="x47-1580009.2.4"></a>The Documentation Generator</h5>
<!--l. 326--><p class="noindent" >The documentation generator creates documentation in LaTex format which can be converted into PDF and
many other formats.
</p>
<!--l. 82--><div class="crosslinks"><p class="noindent">[<a
href="etrice-docse35.html" >prev</a>] [<a
href="etrice-docse35.html#tailetrice-docse35.html" >prev-tail</a>] [<a
href="etrice-docse36.html" >front</a>] [<a
href="etrice-docch9.html#etrice-docse36.html" >up</a>] </p></div>
<!--l. 82--><p class="noindent" ><a
id="tailetrice-docse36.html"></a> </p>
</body></html>
|
