| <?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="2014-03-31 09:04:00" /> |
| <link rel="stylesheet" type="text/css" href="etrice-doc.css" /> |
| </head><body |
| > |
| <!--l. 92--><div class="crosslinks"><p class="noindent">[<a |
| href="etrice-docse31.html" >prev</a>] [<a |
| href="etrice-docse31.html#tailetrice-docse31.html" >prev-tail</a>] [<a |
| href="#tailetrice-docse32.html">tail</a>] [<a |
| href="etrice-docch6.html#etrice-docse32.html" >up</a>] </p></div> |
| <h3 class="sectionHead"><span class="titlemark">6.2 </span> <a |
| id="x40-1780006.2"></a>Component Overview</h3> |
| <!--l. 94--><p class="noindent" > |
| </p> |
| <h4 class="subsectionHead"><span class="titlemark">6.2.1 </span> <a |
| id="x40-1790006.2.1"></a>Room Language Overview</h4> |
| <!--l. 96--><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. 99--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1800006.2.1"></a>Model Tweaks</h5> |
| <!--l. 101--><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. 107--><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-12"> |
| multiplicity |
| </div> |
| <!--l. 109--><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. 117--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1810006.2.1"></a>Imports by URI Using Namespaces</h5> |
| <!--l. 119--><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. 132--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1820006.2.1"></a>Naming</h5> |
| <!--l. 134--><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. 140--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1830006.2.1"></a>Helpers</h5> |
| <!--l. 142--><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. 154--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1840006.2.1"></a>Validation</h5> |
| <!--l. 156--><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. 160--><p class="noindent" > |
| </p> |
| <h4 class="subsectionHead"><span class="titlemark">6.2.2 </span> <a |
| id="x40-1850006.2.2"></a>Config Language Overview</h4> |
| <!--l. 162--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1860006.2.2"></a>Model Tweaks</h5> |
| <!--l. 164--><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. 172--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1870006.2.2"></a>Imports by URI Using Namespaces</h5> |
| <!--l. 174--><p class="noindent" >Imports are treated like in Room language, section <span |
| class="ec-lmsso-10">Imports by URI Using Namespaces</span>. |
| |
| |
| </p><!--l. 176--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1880006.2.2"></a>Util</h5> |
| <!--l. 178--><p class="noindent" >A set of static utility methods can be found in the <span |
| class="ec-lmtt-10">ConfigUtil </span>class. |
| </p><!--l. 180--><p class="noindent" > |
| </p> |
| <h4 class="subsectionHead"><span class="titlemark">6.2.3 </span> <a |
| id="x40-1890006.2.3"></a>Aggregation Layer Overview</h4> |
| <!--l. 182--><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. 188--><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-13"> |
| createGeneratorModel(List<RoomModel>, boolean) |
| </div> |
| <!--l. 190--><p class="nopar" > |
| </p><!--l. 192--><p class="noindent" >method of the <span |
| class="ec-lmtt-10">GeneratorModelBuilder </span>class. |
| </p><!--l. 194--><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. 202--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1900006.2.3"></a>The Instance Model</h5> |
| <!--l. 204--><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. 208--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1910006.2.3"></a>The Expanded Actor Class</h5> |
| <!--l. 210--><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. 224--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1920006.2.3"></a>Transition Chains</h5> |
| <!--l. 226--><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. 236--><p class="noindent" > |
| </p> |
| <h4 class="subsectionHead"><span class="titlemark">6.2.4 </span> <a |
| id="x40-1930006.2.4"></a>Generator Overview</h4> |
| <!--l. 238--><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. 241--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1940006.2.4"></a>Base Classes and Interfaces</h5> |
| <!--l. 243--><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. 246--><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. 250--><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. 257--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1950006.2.4"></a>Generic Generator Parts</h5> |
| <!--l. 259--><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. 264--><p class="noindent" ><span class="paragraphHead"><a |
| id="x40-1960006.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. 269--><p class="noindent" ><span class="paragraphHead"><a |
| id="x40-1970006.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. 273--><p class="noindent" ><span class="paragraphHead"><a |
| id="x40-1980006.2.4"></a><span |
| class="ec-lmssbx-10">GenericStateMachineGenerator</span></span> |
| </p> |
| <div class="flushleft" |
| > |
| <!--l. 275--><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. 290--><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. 298--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-1990006.2.4"></a>The Java Generator</h5> |
| <!--l. 300--><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. 304--><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. 307--><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. 310--><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. 313--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-2000006.2.4"></a>The ANSI-C Generator</h5> |
| <!--l. 315--><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. 322--><p class="noindent" > |
| </p> |
| <h5 class="subsubsectionHead"><a |
| id="x40-2010006.2.4"></a>The Documentation Generator</h5> |
| <!--l. 324--><p class="noindent" >The documentation generator creates documentation in LaTex format which can be converted into PDF and many other |
| formats. |
| </p> |
| <!--l. 109--><div class="crosslinks"><p class="noindent">[<a |
| href="etrice-docse31.html" >prev</a>] [<a |
| href="etrice-docse31.html#tailetrice-docse31.html" >prev-tail</a>] [<a |
| href="etrice-docse32.html" >front</a>] [<a |
| href="etrice-docch6.html#etrice-docse32.html" >up</a>] </p></div> |
| <!--l. 109--><p class="noindent" ><a |
| id="tailetrice-docse32.html"></a> </p> |
| </body></html> |