Provide language with tools

[13]

Let’s focus on adding execution specific features to the language.

This includes enabling animation and representing the dynamic part of the language. Ie. the RunTime Data (RTD) and relevant information that change during the model execution.

Some feature may be generic and available for any languages, some may be domain specific and require some customization dedicated to the language.

1. Define model debug support

[14]

Providing debug support for a language mainly consist in offering 2 main features:

  • the possibility to suspend/resume/step in the model execution. This includes the possibility to have breakpoints to indicates when a model execution should suspend.
  • and look at the model content when suspended.

This debug support is enabled only when the model is executed in Debug mode.

Note

Visual effects and animations related to the debug must not be confused with animations that are supposed to occurs even in Run mode (see Section 3, “Define model animation”).

1.1. Define model debug step information

[15]

The debug step information is the information that indicates to the engine when it can suspend/resume/step/break in a model execution.

The information provided here will typically drive the Debug view (the stack of step frames) and the Timelines.

Debug step information used by the views in the Debug perspective are driven by the engine kind.

If the language uses the Java engine (see Section 1, “Make a sequential executable language”), then this is the annotation @Step that drives the places where the execution can suspend and the stack of steps in the Debug view.

If the language uses the CCSLJava engine (see Section 2, “Make a concurrent executable language”), then this is every call to a DSA (defined by event in the ECL file) that can suspend.

Note

in the current implementation of the CCSLJava engine, the suspend due to a breakpoint/step on call to a DSA is not aligned with the pause due to the Logical Step Decider which is specific to this engine. (see Section 1.3.2, “Logical step view” and Logical Step Decider button in Section 1.3.1, “Engine View”)

1.2. Define model debug RTD information

[16]

Debug RunTime Data information used by the views in the Debug perspective are driven by the declaration of which data in the model can change during the model execution with regard to the part of the model that do not change.

Basically, this means that the elements in ecore of the language that can change during the execution must be annotated with aspect annotation.

The elements tagged with this will be treated as mutable and used by the various part of the studio when deployed in the modeling workbench. This includes for example the Variables view, the MultiDimentional timeline view, the trace, …​

Model debug RTD using aspect annotation in k3fsm.ecore

Figure 5. Model debug RTD using aspect annotation in k3fsm.ecore.


Figure 5, “Model debug RTD using aspect annotation in k3fsm.ecore.” shows a basic usage of this annotation on the example K3FSM Example and its effect on the Variables view and Multidimentional Timeline view in Figure 6, “Aspect annotation effect in Modeling workbench.”.

aspect annotation effect in modeling workbench

Figure 6. Aspect annotation effect in Modeling workbench.


Note

Melange can help to set these annotations. If you are using Melange in order to generate the executable language from a non executable ecore then this annotation is automatically added for you on every element added thanks to aspects.

[17]

1.3. Defining MultiDimentional Trace support

The multidimentional trace is a mechanism that enables some extra feature in the debugger in the Modeling workbench. This turns the debugger into an omniscient debugger with forward/backward features and advanced visualization of data changes in the model.

This feature can be enabled by using the generator on top of the xdsml project and generate the Trace Addon Project.

2. Define editor specific debug support

2.1. Define a debug representation and commands for Sirius

[18]

The debug layer is an extension on top of a graphical editor defined with Sirius (See Section 3.2, “Defining a Concrete Syntax with Sirius” for more details about Sirius.) which represents the current instruction and provides commands to enable/disable breakpoints. This layer is activated when the model is executed in Debug mode.

Note

The Debug layer role is similar to the services of a text editor that highlights the current line of the selected Step in the stack frame and offer to toggle breakpoints.

Tip

Additionally, the editor may also present the RunTime Data in this layer, but usually, a better design would separate the task of RTD presentation in another Animation layer as the animation is supposed to be also displayed in Run mode. (See Section 3.1, “Define an animation representation for Sirius”)

This section covers the debug representation creation wizard and the technical implementation details. Technical implementation details are only useful for advanced use case and troubleshooting.

2.1.1. The debug representation wizard

This wizard creates a layer to represent the current instruction and add commands in order to manage breakpoints and launch a simulation in debug mode. This is a default implementation, it can be customized to represent runtime data for instance. The customization uses the Sirius description definition, see the Sirius Specifier Manual for more details. The wizard presents three ways to implement this layer:

  • Create a debug diagram description
  • Extend an existing diagram description
  • Add a debug layer to an existing diagram description
Debug representation wizard
2.1.1.1. Create a debug diagram description

It creates a diagram representation with a default debug layer. The representation does not depend on another representation. A typical use case is a language where the runtime data representation is too far from the language graphical syntax.

Debug representation wizard
Debug representation wizard
2.1.1.2. Extend an existing diagram description

It creates a diagram representation with a default debug layer that extends an existing representation. This allows to have a debug layer based on the representation of the language concrete syntax. The language concrete syntax can be deployed without the debug representation. A typical use case is the reuse of an existing diagram definition that you cannot modify by yourself. For instance if you want to use UML, you can reuse the UML Designer.

You can select any diagram description.

Debug representation wizard

And then define the new diagram description which extends the one you previously selected.

Debug representation wizard
Debug representation wizard
2.1.1.3. Add a debug layer to an existing diagram description

It creates a default debug layer in an existing diagram representation. This should be used if you are also in charge of the language concrete syntax.

In this case, you can only select a diagram description from the workspace.

Debug representation wizard
Debug representation wizard

2.1.2. Implementation details

Implementation details are for advanced use and troubleshooting. It explains how the implementation works behind the scene. There are two main elements covered here : the debugger services class and the debug layer itself.

2.1.2.1. Debugger services

The debugger services class is use to tell which representations should be activated and refreshed during debug (see the getRepresentationRefreshList() method). It also provides a method to know if an element of the diagram is the current instruction. This is provided by the isCurrentInstruction() method.

Debug services

Important

The line res.add(new StringCouple("DD_or_RN", "LAYER_ID")); indicates which layers are part of the "debug" animation. Ie. if these layers must be activated automatically and updated when an execution is in debug mode.

The way to indicate the layer depends on how you have created the layer:

  • in case of a single odesign with all layers in a single viewpoint:

    • the first String DD_or_RN is the id of the Diagram Description
    • the second String LAYER_ID is the id of the Layer
  • in case of a diagram extension:

    • the first String DD_or_RN is the Representation Name of the Diagram Extension (do not confuse with the Name !!)
    • the second String LAYER_ID is the id of the Layer
2.1.2.2. Debug layer

The default debug layer adds action to start the simulation in debug mode and to toggle breakpoints (1). When a breakpoint exists for an element of the diagram, a visual feedback is displayed according to the breakpoint state (2). The current instruction is also highlighted in yellow by default (3).

Debug layer

This is a default debug layer, it can be customized to fit your needs. The customization use the Sirius description definition, see the Sirius Specifier Manual for more details.

3. Define model animation

[19]

Providing model animation mainly consist in offering representations (textual, graphical, tabular, or even specialized views) for the data that changes during model execution (ie. RunTime Data).

As opposed to Debug representation (see Section 2.1, “Define a debug representation and commands for Sirius”), Animation is supposed to be available in all execution modes (both Run mode and Debug mode).

As for concrete syntaxes, GEMOC supports several technologies, including graphical editor extension, in semantic direct call or engine addons.

3.1. Define an animation representation for Sirius

[20]

The Sirius editor defined Section 3.2, “Defining a Concrete Syntax with Sirius” can also be extended in order to present the RunTime Data during a model execution.

A good design consists in creating a dedicated layer that would be enabled on every execution in both Debug mode and Run mode.

The design principles are similar to the one used in Section 2.1, “Define a debug representation and commands for Sirius”. It can add either new diagram or new layers on top of existing diagrams in order to display the domain specific RunTime Data. Additionally, a service is registered in order to activate the layer when starting the execution and trigger refresh event during the execution.

Note

Even if very similar, an animation layer is slightly different from a Debug layer of Section 2.1, “Define a debug representation and commands for Sirius” which is not enabled in Run mode and is focused on presenting the current stack element and debug controls.

3.2. Define an animation representation using an engine addon

[21]

GEMOC offers an API to develop Engine Addons. These addons have access to the engine execution context, the model and its runtime data. As they are refreshed during the execution, they are convenient to provide many services including animated UI for representing the model.

For example, they will easily connect to a dedicated Eclipse view.

Tip

An Engine addon may be generic and apply to any language, but it can also be language specific. In that case, you should prefer to add its code in the project containing the dsl file of the language and declare it in the plugin.xml.

This way, the addon will be available only for this specific language.

Add language specific Engine Addon on DSL

Figure 7. Add language specific Engine Addon on DSL


See Section 1.1, “Developing new Addons” for technical detail about addon implementation.

3.3. Define an animation representation using calls in the semantics

[22]

A designer of the DSA code (see Make language executable) can also call a dedicated GUI (for example opening an AWT, Swing, SWT window) and then populate it during the execution. In order to not freeze the general UI of the engine, the GUI must start in another thread. This thread can be initialized during the model initialization method of the engine (The initialization may differ depending on the engine see Section 1.2, “Defining the initialization function” or Section 2.1.4, “Defining the initialization function”).

Note

Using this approach do work and can be convenient for simple representations. However this creates a strong link from the semantics to the UI. As much as possible, this is not the recommended approach.

4. Exhaustive Exploration and Verification at Language Design Time

[23]

One benefit of assigning an execution semantics onto a DSL is to pave the way for exhaustive exploration. Exhaustive exploration is a technique used in complex and safety system design to ensure the correct adequacy between the system requirements and the real behavior of the system. This is made possible by exploring and verifying properties on an exhaustive finite state space of the system representing the whole set of relevant configurations your system may reach.

Gemoc provides the first step towards exploration and verification by building the graph of all the possible schedules of a system model constrained with MoCCML. It can then be used in a model-checking tool to verify behavioral properties of the MoCCML models. Thanks to Gemoc approach the execution model is explicited and can be manipulated to for instance:

  • Verify temporal logic properties (safety and liveness) on the state space graph structure;
  • Extract a schedule that optimizes specific objectives;
  • Extract system properties by static analysis of an event-graph representation of the execution model.

In the Gemoc approach the steps toward exploration and verification during language design are:

In the Gemoc approach the steps toward exploration and verification during modeling design are described in Section 1, “Exhaustive Exploration and Verification at Model Design Time”: The flow toward exhaustive exploration and verification in Gemoc is presented in figure Figure 8, “The exploration and verification flow in Gemoc” and described in the following sections.

The Exploration and Verification Flow in Gemoc

Figure 8. The exploration and verification flow in Gemoc


4.1. Generating inputs for Exhaustive Exploration tools : T1 at Language Level

ECL specification is the starting point toward exploration. In this specification we define events associated with the actions of the DSA and also events associated with the DSE events. On these event bindings we apply the MoccML relations of the MoC Library to schedule the events. A finite state space of a system uses such scheduling constraints and therefore a configuration file to target an exhaustive exploration tool must be generated:

T1 transformation generates a configuration file to later target exhaustive exploration or simulation tools. T1 takes as input the ECL mapping definition between the DSL and the MoCCML to generate a transformation T2 describing transformation rules that will be used to produce the processes for the DSL related functions and data (DSA) and the behavioral processes corresponding to the MoCCML constraints.

T1 is automatically generated from ecl model and results are stored in mtl-gen folder.

However to execute T1 manually right-click on the ECL file → clocksystem logo 32x32Exhaustive Exploration → cs t1 16x16Generate ClockSystem transformation from ECL model as illustrated in figure Figure 9, “Using T1 Tranformation”.T2 is generated in the repository <mtl-gen>.

Using T1 Tranformation

Figure 9. Using T1 Tranformation