Difference between pages "Technical topic: SDL2IF/OBS2IF" and "TASTE Communication Device"

From TASTE
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
= Introduction =
+
== Introduction ==
 +
CommunicationDevice (CD) is a new type of TASTE project, that allows to model low level system drivers and integrate CD driver with existing or new TASTE project. It comes with two pre-defined templates: Broker and Broker + Packetizer. Depending on a selected template CD allows to model either Broker or Broker and Packetizer communication components. CommunicationDevice is a part of the SpaceCreator and Kazoo projects.
  
sdl2if translates SDL processes representing the behavior of TASTE functions or TASTE observers into respectively IF processes or IF observers. 
+
== Capabilities ==
 +
The following functionalities are supported:
 +
* creation of new CD project from QTC wizard – SpaceCreator
 +
* modeling and implementation of broker and packetizer
 +
* CD code generation done be Kazoo templates
 +
* integration with full TASTE project
  
sdl2if is developed as a back-end of OpenGEODE, from which it re-uses the SDL parser and the AST representation.   It is developed in Python 3.x and uses single-dispatch generic functions (functools/singledispatch) to structure the translation.
+
==How to create CD project==
 +
Communication device project can be created form QT Creator wizard that can be opened with TASTE command. Then under File->New File or Project (Ctrl + N)
 +
[[File:Cd_wizard_2.png]]
  
= Usage =
 
  
sdl2if is invoked as follows
+
Non-Qt Project -> Communication Device Project
  
  $ sdl2if [--output-dir dir] file1.pr [ ... file_n.pr]
+
[[File:Cd wizard 1.png]]
  
and produces a unique .if file containing the translation of the SDL process defined in file1.pr (... file_n.pr) as an IF process.  The file will be created in the output-directory if specified, else in the current working directory.  The name of the .if file is the lowercase name of the SDL process.
 
  
 +
CD wizard starts with “Project Location” tab. User shall provide Name for the project and path under which project will be created.
  
= Key Features =
+
[[File:Cd_wizard_3.png]]
  
* supports a significant part of SDL including expressions on data variables with ASN.1 types, hierarchical and parallel states, inner procedures, task for loops, decisions, floating labels, etc
+
Next tab “Project Initialization” provides capabilities of selecting interface view template and CD board. Under IV template either “Broker” or “Broker_Packetizer” can be selected. Under Communication Device board either “x86 Linux CPP” or “SAM V71 FreeRTOS N7S” can be selected.
  
* preserves the structure of the input model, that is, each SDL concept is mapped 1-to-1 into an equivalent IF concept, whenever possible - e.g., variables, hierarchical states, transitions, actions - and therefore facilitates the inspection and the understanding of the generated code
+
[[File:Cd_wizard_4.png]]
  
* preserves the operational semantics, that is, traceability between executions in TASTE and executions in IF, as much as possible
+
Next tab is standard “Kit Selection” tab.
  
* generates IF processes slightly optimized for exhaustive model-checking, by limiting the increase of the state vector and/or state space due to auxiliary variables
+
[[File:Cd_wizard_5.png]]
  
* in observers, supports success, error and ignore states
+
Under last tab that is “Project Management” version control can be added. Also wizard displays all files that will be added to Communication Device project.
  
* in observers, supports both simple and generic input/output transition triggers; the generic triggers are expanded at translation using auto-generated -Event types in observer.asn
+
[[File:Cd_wizard_6.png]]
  
* in observers, translates SDL timers as IF clocks and allow checking properties dealing explicitly with real time
+
===Generated CD project files details===
 +
Communication Device Project wizard adds the following files to the project:
 +
{| class="wikitable"
 +
|-
 +
| --acn-filepath-prefix <prefix>
 +
| <prefix> to add at the beginning of the ACN output filepath
 +
|-
 +
| --asn1-filepath-prefix <prefix>
 +
| <prefix> to add at the beginning of the ASN.1 output filepath
 +
|}
  
 +
{| class="wikitable"
 +
|-
 +
|--taste.pro – empty taste.pro file that will be automatically generated during build
 +
|-
 +
|-- Makefile – entry build and clean procedure that includes Kazoo and SC dependencies definitions
 +
|-
 +
|-- deploymentvew.dv.xml – predefined deploymentview.dv.xml that includes CD build partition
 +
|-
 +
|*--interfaceview.xml – interfaceview with Broker, Packetizer and interfaces. In this file user shall model Broker or Broker and Packetizer (depending on a template) along with required and provided components interfaces.
 +
|-
 +
|-- <project name>.acn – ACN project model for custom binary encoding rules.
 +
|-
 +
|-- <project name>.asn – ASN non user-editable model that contains all the basic data types.
 +
|-
 +
|-- <project name>.pro/shared – QTC project files with custom user build settings.
 +
|-
 +
|-- <project name>configuration.acn - ACN project configuration model for custom binary encoding rules.
 +
|-
 +
|-- <project name>configuration.asn - ASN user-editable model that contains definition of Driver Configuration. This file will be used by ocarina-components.aadl and Board1.xml and shall be implemented by the user.
 +
|-
 +
|--<project name>privatedata.acn - ACN project privatedata model for custom binary encoding rules.
 +
|-
 +
|-- <project name>privatedata.asn - ASN user-editable model that contains definition of Private Data structure. This type shall be used in main.c[pp] to indicate the type of the variable that is passed as a private pointer to the driver. Shall be implemented by the user.
 +
|}
  
= Known Limitations =
+
==Exemplary CD broker and packetizer modeling and implementation==
 
+
Based on selected CD “Interface view template” either broker or broker and packetizer can be modeled and implemented. In this example second template will be used.
* no entry/exit procedures in hierarchical state machines
 
 
 
* no mutually recursive inner procedures
 
 
 
* no 'NEXTSTATE -' in transitions from / with floating labels
 
  
* restricted input/output event triggers and/or system state expressions in observers
+
===CD IV file specifics – fixed system elements===
 +
After opening IV file in the editor user can find (depending on selected template) Broker and Packetizer components. These are virtual components that are not taken for final code generation. Purpose of those elements is to provide “must have” set of interfaces. Those are required to match newly created and modeled communication components to existing in TASTE runtime calls.
  
 +
[[File:Cd_broker_pack_iv_1.png|1100px]]
  
= Examples =
+
User can’t remove those element neither the interfaces and will be informed about that while trying to do so.
  
== An SDL process ==
+
[[File:Cd_broker_pack_iv_2.png]]
  
[[File:memoryscrub.png]]
+
===Modeling Packetizer component===
 +
While modeling Packetizer user shall provide a TASTE function that implements needed interfaces and connect that function to pre-defined virtual Packetizer component. Also each interface shall contain set of input and output parameters. The easiest way to do so is by dragging each interface from virtual Packetizer with left Ctrl key pressed and drop it on custom function. This way each interface will be copied along with set of parameters.
  
process memoryscrub(1);
+
[[File:Cd_broker_pack_iv_3.png|1100px]]
 
var running boolean := true public;
 
var sender pid := nil;
 
var par EnableDisable public;
 
 
state start #start ;
 
  task running := false;
 
    nextstate disabled;
 
endstate;
 
 
state disabled;
 
  input memoryscrub_enableordisable (par, sender);
 
    nextstate u_decision_1;
 
endstate;
 
 
state u_decision_1 #unstable ;
 
  provided (par = EnableDisable_scrubon);
 
    task running := false;
 
    nextstate enabled;
 
  provided (par = EnableDisable_scruboff);
 
    task running := false;
 
    nextstate disabled;
 
endstate;
 
 
state enabled;
 
  input memoryscrub_enableordisable (par, sender);
 
    nextstate u_decision_2;
 
  provided (not running) and true;
 
    task running := true;
 
    informal "input_none";
 
    // writeln ;
 
    task running := false;
 
    nextstate enabled;
 
endstate;
 
 
state u_decision_2 #unstable ;
 
  provided (par = EnableDisable_scrubon);
 
    task running := false;
 
    nextstate enabled;
 
  provided (par = EnableDisable_scruboff);
 
    task running := false;
 
    nextstate disabled;
 
endstate;
 
 
endprocess;
 
  
== An SDL observer ==
 
  
[[File:droppick.png]]
+
[[File:Cd_pack_params_1.png|t300px]]
 +
[[File:Cd_pack_params_2.png|500px]]
  
intrusive observer droppick;
+
To avoid build errors another function can be connected to Broker and it’s implementation is not required.
 
var running boolean := true public;
 
var sender pid := nil;
 
var aux_signal t_if_signal;
 
var cmd Roboticarmstatus public;
 
 
state start #start ;
 
  task running := false;
 
    nextstate wait;
 
endstate;
 
 
state checkdrop;
 
  provided (not running);
 
    match input rarmcontrol_roboticarm_request (cmd, sender) in {rarmcontrol}0;
 
    task running := true;
 
    nextstate u_decision_1;
 
endstate;
 
 
state u_decision_1 #unstable ;
 
  provided (cmd.predicate = RoboticarmPred_roboticarm_picking);
 
    task running := false;
 
    nextstate error;
 
  provided (cmd.predicate = RoboticarmPred_roboticarm_dropping);
 
    task running := false;
 
    nextstate wait;
 
  provided not ((cmd.predicate = RoboticarmPred_roboticarm_picking) or (cmd.predicate = RoboticarmPred_roboticarm_dropping));
 
    task running := false;
 
    nextstate checkdrop;
 
endstate;
 
 
state error #error ;
 
endstate;
 
 
state wait;
 
  provided (not running);
 
    match input rarmcontrol_roboticarm_request (cmd, sender) in {rarmcontrol}0;
 
    task running := true;
 
    nextstate u_decision_2;
 
endstate;
 
 
state u_decision_2 #unstable ;
 
  provided (cmd.predicate = RoboticarmPred_roboticarm_picking);
 
    task running := false;
 
    nextstate checkdrop;
 
  provided (cmd.predicate = RoboticarmPred_roboticarm_dropping);
 
    task running := false;
 
    nextstate error;
 
  provided not ((cmd.predicate = RoboticarmPred_roboticarm_picking) or (cmd.predicate = RoboticarmPred_roboticarm_dropping));
 
    task running := false;
 
    nextstate wait;
 
endstate;
 
 
endobserver;
 
  
 +
===Implementation of Packetizer component===
 +
At this point CD project is able to generate source code for MyPacketizer function that can be extended with user implementation. Screens below presents empty mypacketizer.c/h files.
  
= Implementation =
 
  
The sdl2if implementation is located under the [https://gitrepos.estec.esa.int/taste/if-model-checking Taste / IF Model Checking] git repository within the [https://gitrepos.estec.esa.int/taste/if-model-checking/-/tree/master/modules/sdl2if modules/sdl2if] directory.
+
[[File:Cd_mypack_code_2.png|t300px]]
 +
[[File:Cd_mypack_code_1.png|400px]]
  
The tool entry point is defined within [https://gitrepos.estec.esa.int/taste/if-model-checking/-/blob/master/modules/sdl2if/sdl2if/sdl2if.py sdl2if.py] and the core implementation is located within [https://gitrepos.estec.esa.int/taste/if-model-checking/-/blob/master/modules/sdl2if/sdl2if/sdl2if/IfGenerator.py IfGenerator.py].  At top level, sdl2if uses the opengeode parser to construct the AST of the input SDL files, then it proceeds with the transformation on the first SDL process, by doing:
+
For this example simple implementations of “Packetize” and “Depacketize” functions will be implemented and Init function will not be used. Screens bellow presents exemplary implementation of those functions.
  
ast, warnings, errors = opengeode.parse(options.files)
 
IfGenerator.generate(ast.processes[0], output_dir=options.output_dir)
 
  
The implementation of the model transformation is recursive on the AST representation of the SDL process as constructed by opengeode. Single-dispatch generic functions are used to handle the various AST objects, and produce (fragments of) the IF process(es) and related IF definitions, as summarized below:
+
[[File:Cd_mypack_code_6.png|t300px]]
 +
[[File:Cd_mypack_code_5.png|400px]]
  
{| class="wikitable" style="margin:auto"
+
Communication Device project with packetizer component implementation is ready to be integrated wit full TASTE project. See another chapters to follow TASTE project integration.
|+ Single-dispatch generic transformation functions
 
|-
 
! Function !! ogAST Classes
 
|-
 
| ''tr_process'' || ''ogAST.Process'', ''ogAST.Procedure''
 
|-
 
| ''tr_state_machine'' || ''ogAST.Process'', ''ogAST.CompositeState'', ''ogAST.Procedure''
 
|-
 
| ''tr_state'' || ''ogAST.Process'', ''ogAST.CompositeState'', ''ogAST.Procedure'', ''ogAST.FloatingLabel''
 
|-
 
| ''tr_transition'' || ''ogAST.Input'', ''ogAST.ContinuousSignal'', ''ogAST.Transition'', ''ogAST.Terminator''
 
|-
 
| ''tr_action'' || ''ogAST.Input'', ''ogAST.ContinuousSignal'', ''ogAST.Label'', ''ogAST.Task*'', ''ogAST.Output'', ''ogAST.ProcedureCall'', ''ogAST.Decision''
 
|-
 
| ''tr_expression'' || ''ogAST.Expr*'', ''ogAST.Prim*''
 
|}
 
 
 
The resulting IF process(es) and related definitions are represented using dedicated data structures.  That is, in a first step, an IF model is progressively constructed while traversing the AST, then, in a second step, the IF model is written into a textual .if file.
 
 
 
The implementation provides the classes ''IfSignal'', ''IfVariable'', ''IfGuard'', ''IfAction'', ''IfTransition'', ''IfState'', ''IfProcess'' to represents structurally the corresponding IF concepts. In addition, the class ''IfWeb'' allows to store an IF state machine fragment with potentially any number of pending entry and exit transitions and provides specific methods to glue such fragments into bigger ones, ultimately leading to complete state machines.
 
 
 
Finally, the implementation relies on several helper functions with dedicated functionalities, the most important being summarized in the table below:
 
 
 
{| class="wikitable" style="margin:auto"
 
|+ Helper functions
 
|-
 
! Functions !! Provided Functionality
 
|-
 
| ''ctxt_*'' || access information about the transformation context
 
|-
 
| ''if_*_name'' || get names for different concepts at IF level
 
|-
 
| ''idx_*'' || unique indexing of AST objects
 
|-
 
| ''auxvar_*'' || handling auxiliary variables
 
|-
 
| ''forloopvar_*'' || handling TaskForLoop variables
 
|-
 
| ''inosig_*'' || handle output forwarding from inner procedures
 
|-
 
| ''is_input_*'', ''*_discard_*'' || handle auto-completion with discard transitions
 
|-
 
| ''*_observer_*'', ''*_match_*'' || observer specific access and/or transformation
 
|}
 

Revision as of 17:47, 29 November 2022

Introduction

CommunicationDevice (CD) is a new type of TASTE project, that allows to model low level system drivers and integrate CD driver with existing or new TASTE project. It comes with two pre-defined templates: Broker and Broker + Packetizer. Depending on a selected template CD allows to model either Broker or Broker and Packetizer communication components. CommunicationDevice is a part of the SpaceCreator and Kazoo projects.

Capabilities

The following functionalities are supported:

  • creation of new CD project from QTC wizard – SpaceCreator
  • modeling and implementation of broker and packetizer
  • CD code generation done be Kazoo templates
  • integration with full TASTE project

How to create CD project

Communication device project can be created form QT Creator wizard that can be opened with TASTE command. Then under File->New File or Project (Ctrl + N) Cd wizard 2.png


Non-Qt Project -> Communication Device Project

Cd wizard 1.png


CD wizard starts with “Project Location” tab. User shall provide Name for the project and path under which project will be created.

Cd wizard 3.png

Next tab “Project Initialization” provides capabilities of selecting interface view template and CD board. Under IV template either “Broker” or “Broker_Packetizer” can be selected. Under Communication Device board either “x86 Linux CPP” or “SAM V71 FreeRTOS N7S” can be selected.

Cd wizard 4.png

Next tab is standard “Kit Selection” tab.

Cd wizard 5.png

Under last tab that is “Project Management” version control can be added. Also wizard displays all files that will be added to Communication Device project.

Cd wizard 6.png

Generated CD project files details

Communication Device Project wizard adds the following files to the project:

--acn-filepath-prefix <prefix> <prefix> to add at the beginning of the ACN output filepath
--asn1-filepath-prefix <prefix> <prefix> to add at the beginning of the ASN.1 output filepath
*--interfaceview.xml – interfaceview with Broker, Packetizer and interfaces. In this file user shall model Broker or Broker and Packetizer (depending on a template) along with required and provided components interfaces.

Exemplary CD broker and packetizer modeling and implementation

Based on selected CD “Interface view template” either broker or broker and packetizer can be modeled and implemented. In this example second template will be used.

CD IV file specifics – fixed system elements

After opening IV file in the editor user can find (depending on selected template) Broker and Packetizer components. These are virtual components that are not taken for final code generation. Purpose of those elements is to provide “must have” set of interfaces. Those are required to match newly created and modeled communication components to existing in TASTE runtime calls.

Cd broker pack iv 1.png

User can’t remove those element neither the interfaces and will be informed about that while trying to do so.

Cd broker pack iv 2.png

Modeling Packetizer component

While modeling Packetizer user shall provide a TASTE function that implements needed interfaces and connect that function to pre-defined virtual Packetizer component. Also each interface shall contain set of input and output parameters. The easiest way to do so is by dragging each interface from virtual Packetizer with left Ctrl key pressed and drop it on custom function. This way each interface will be copied along with set of parameters.

Cd broker pack iv 3.png


t300px Cd pack params 2.png

To avoid build errors another function can be connected to Broker and it’s implementation is not required.

Implementation of Packetizer component

At this point CD project is able to generate source code for MyPacketizer function that can be extended with user implementation. Screens below presents empty mypacketizer.c/h files.


t300px Cd mypack code 1.png

For this example simple implementations of “Packetize” and “Depacketize” functions will be implemented and Init function will not be used. Screens bellow presents exemplary implementation of those functions.


t300px Cd mypack code 5.png

Communication Device project with packetizer component implementation is ready to be integrated wit full TASTE project. See another chapters to follow TASTE project integration.