Version 0.14 RC1
This page is part of the SCCharts Editor 0.14 RC1 documentation. This page is still under construction. We are still in the process of creating the release candidate. Please excuse any missing or incomplete entry. We apologize for any inconvenience.
Note that this page refers to the new textual SCCharts syntax (SCTX)
For a detailed description of the basic concepts and semantics of SCCharts please consult Sections 3.1 & 3.2 in the dissertation of Christian Motika.
Each SCChart starts with the keyword scchart followed by an ID. A ID can be any alpha-numerical combination, but must start with an alphabetical character or an underscore (a single underscore is prohibited). However, underscores are used to identify auto-generated constructs, so the modeler should not use them as prefix.
One of the basic constructs of SCCharts is a simple state. A simple state does not have any inner behavior and can be connected via transitions to other states.
To tell the program where to start, a state can be marked as initial. Exactly one state (per concurrent region, see concurrency) must be marked as initial.
Transitions connect states. There are different kinds of Transitions, but we will restrict ourselves to the two basic types for now. (See below for more complex transitions.)
They can be guarded by a trigger that determines when this transition is enabled and they can have effects that are executed whenever this transition becomes active.
IMPORTANT: We are testing different syntax variations for transitions in the release candidate. At the moment we prefer the following syntax as default.
[immediate] [if condition] [do effect[; effect]*] (go | abort | join) to targetstate
Please test it. We appreciate it.
However, in the RC1 you can also start with the jump and follow with the if or even use the legacy syntax with the ascii art arrow. Hence, some examples may differ slightly from each other. Feel free to experiment. Please provide us with feedback. We will streamline the syntax before the final release.
A delayed transition cannot trigger in the instance the parent state is entered. If a state is entered, they become active in the next tick. You can see this in the Simple example. Just write go to.
Immediate transitions are checked as soon as their parent state is entered. Hence, the state can be entered and left within the same tick. Use the keyword immediate to create an immediate transition
Implicit Delay Behavior
A state can also be marked as final. A final state marks the end of a thread. If a final state is reached on root level, the program terminates.
Declarations & Variables
Each scope (for now just the SCChart) can have a list of declarations. The SCChart code on the right gives an example. A declaration starts with the type, followed by a list of variable identifier. Each variables can be initialized with a specific value.
The following native types are supported: bool, int, double, string, signal (see below)
Additionally, you can mark a declaration as extern and give it a string that will be used in the serialization of the final code, e.g., the name of a host type. You can then add variables as before.
If you add brackets to a variable and specify cardinalities, you declare an array.
Declarations can be marked as constant, meaning that each occurrence is then replaced by the initialization because the variable is not allowed to be changed.
You can assign a whole tuple at once to an array.
To assign only certain values of an array, you can also use the ignore value placeholder. Consult the expression manual for further information.
This would, for example, result in c code assignments as displayed on the right.
You can simply use JavaDoc-style comments to comment you SCChart. The comments will appear in the synthesized diagram as comment boxes. You can toggle these boxes in your sidebar.
Additionally, for documentation reason, you can annotate different elements to give them a user-defined style. E.g. colorize a state or comment box for visual effect. Use html-like color codes for different colors. Please read more on annotations in the section below.
Hierarchy & Concurrency
Superstates model hierarchy. Each nested superstate creates a new scope. The syntax is easy: just start a new scope via curly brackets after your initial state declaration.
A superstate can be exited by any transition preemption type. However, especially the termination (or join) is of interest as it is taken as soon as the superstate finishes (meaning a final state is reached.)
Regions model concurrency. They follow the initialize-update-read protocol if scheduling between different regions becomes necessary.
A termination transition is taken if all regions of the superstate have reached a final state.
Action in SCCharts are defined at the beginning of a state after the declarations.
An entry action is executed immediately when its state is entered. If the optional trigger is specified the effect(s) will only be executed if the trigger condition is true.
A during action is executed in each tick its state is active except when the state is entered. If an immediate during is used the action is also executed in the tick the state is entered. If the optional trigger is specified the effect(s) will only be executed if the trigger condition is true.
An entry action is executed when its state is left. Exit actions are considered inner behavior and are consequently suppressed if the state is strongly aborted. If the optional trigger is specified the effect(s) will only be executed if the trigger condition is true.
We will use the beep.sctx as example for referenced SCCharts.
If you want to use another SCChart inside your model, you must first include it with an import statement. For example, if you want to include beep into the comment example "root" from above, you can add import "beep" and include a state that references beep.
The keyword is indicates that R is a reference. When you are referencing, you have to bind the interface of the referenced SCChart model to variables of the actual on. You must do this in the parentheses after the referenced state. In the example second is bound to second, and the local speaker boolean is bound to the beep from beep's interface. You can read more about variable bindings in the next paragraph. Also, the content assist will help you with your bindings and inform you about missing bindings.
Details about Bindings
There are three different kinds of bindings: explicit bindings, order bindings, and implicit bindings. In the example we used explicit bindings, which are the safest way of bindings.
They state explicitly which local variable gets bound to which remote. The content assist will help you with errors.
If you know the order of the variables (and/or listen to the content assist), you can also use order bindings and simply state the list of local variables.
They will be bound to the interface in the order of declaration in the remote SCChart. However, be aware of the fact that the bindings will change, when the declarations of the referenced SCChart change.
In the example, the names of the local and referenced second variables are identical. Hence, you can also omit the binding completely.
SCCharts will then bind the variable implicitly. However, we also consider this kind of binding unsafe and the editor will warn you about any implicit bindings. They can be handy though when dealing with large interfaces.
As any state, referenced states are allowed to own transitions. However, if you are using terminations, you must make sure that the referenced SCChart terminates. Otherwise, the transition will never trigger. The content assist will help you with this issue.
You do not need to activate the Xtext nature as in previous versions of SCCharts. In fact, we recommend to deactivate the Xtext nature for SCCharts projects.
Example warnings from the content assist:
SCCharts support inheritance, similar to the concept of references.
Each root state can extend multiple base states (since the name super states is already used) by listing them after the extends keyword.
Such an state will inherit all declarations, action and regions of the base states. If conflicts arise or a state has a cyclic inheritance hierarchy, a warning will be displayed. If a state is contained multiple times in the inheritance hierarchy its content will inherited only once.
Declarations can have the private keyword to prevent extending SCCharts from accessing these variables.
Root-level regions of base states can be overriden with the override keyword and consequently replace the behavior by the new definition. Anonymous regions (defined without an ID) cannot be overridden.
Regions can also be references similar to states by using the is keyword. If the reference should refer to the implementation in the base state, the super keyword must be used.
You can convert a region into a dataflow region by replacing the region keyword with the keyword dataflow. Within a dataflow scope, you can simply write down your equations.
On the right you see several examples and their synthesized diagrams.
You can use all expressions in the kexpressions language. This includes standard operations such as arithmetics and binary/logical logic. A full set of operations can be found at the end of this page (in the future).
Just as before, you can declare references to other SCCharts. As before, use the ref keyword in your declaration section. Each variable represents an instance. Inputs and outputs are separated by a dot (.). Same wires are merged automatically in the diagram.
Input/Output Loops (df#0521)
Of course you can model loops in your wiring. However, depending on the consecutive compilation/scheduling the program may or may not be executable/schedulable.
You can use the aforementioned tuple syntax to assign all/some inputs at once. Hence, it is possible to construct complex models with only a few lines of code.
Skins (df#1000, df#1100)
You can use customized skins instead of the standard referenced SCCharts actor diagram. Since we are using Klighd, you have to specify your actor in Klighd's Graph Syntax (.kgt). Once you have created a custom .kgt, you can add it to an SCChart with the
@figure annotation. The annotation combined with a skinpath relative to the calling model points to the target .kgt.
For example: Imaging df#0007 is annotated with
@figure "and2AN.kgt". Now df#1000 can set a skinpath pragma. Together they point to the .kgt that should be used as actor diagram. In this case, we get an
and with a negated input.
Even if df#0007 was not annotated, you can archive the same result if you annotate the
ref declaration in df#1000.:
There are several ways to add hostcode to your models.
External References (hostcode#10)
You can declare a new object as external reference like before with (internal) references. Use the keyword extern to mark it as extern. Then use a
string to set the name of the function and an object which you will use to reference this hostcode snippet. As it is handled as a call, you can add parameters and they will be recognized by the dependency analysis.
Additionally, you can annotate your code snippets with the name of the code generator (e.g. C, Java) to tell the code generation which one should be used when. See the example on the rigt for more details.
As hostcode calls look like emissions they have to use the call keyword. This is not necessary if you use the reference inside an expression such as r = rand(), but mandatory in actions without assignment.
While an External Reference is the preferred way to declare a hostcode call, you can call any function without declaring it first. However, due to grammar limitations and platform-dependency this older features is considered deprecated. You should really use external references.
Nevertheless, you can still use this feature by using the extern keyword directly inside the expression (e.g. r = extern gettimeofday()) without declaring the call beforehand.
The dependency analysis will consider parameters.
Legacy Hostcode (hostcode#30)
You can simply place the host code in accent grave (`) quotes. The code is put as it is into the final code. There is no further processing and also no parameter list. You can of course put the parameters inside the host code quotes, but they will be copied as they are.
The textual SCCharts language supports several annotations to influence the visual representation of the model.
Annotation are processed in sequential order.
Sets the synthesis option identified by <key> to the given value.
The available synthesis options for a diagram are displayed in the sidebar of the diagram view.
The values from the sidebar will be ignored if a corresponding annotation is present.
Sets the layout property identified by <key> to the given value on the annotated element.
The available layout options are documented here.
Layout options will only affect the annotated element and no underlying hierarchy levels.
If a layout direction is specified with this annotation it overrides the layout direction set by HV-/VH-Layout in any parent element for this element.
Special case: If the direction is set on the scchart element (top level) it overrides the default alternating layout.
The layout option is identified by matching a postfix. Hence the key
Defines the order of the alternating layout directions.
The annotation can be mixed and nested in the SCChart and will only affect succeeding hierarchy levels.
The default is an implicit HVLayout starting at the top level state.
|The annotated region will be initially collapse or expanded.|
The annotated element will be excluded from the diagram.
Transitions with a hidden source or target state will be hidden as well.
Here you can see an SCCharts graphical notation overview.