Difference between pages "Technical topic: ASN2IF" 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.
  
''asn2if'' translates ASN.1 datatypes to IF language.
+
== 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
  
Within the TASTE IF model-checking framework, asn2if is used to translate the dataview-uniq.asn file generated for a TASTE system, although it can be used manually for translating any ASN.1 file.
+
==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]]
  
''asn2if'' is developed in Python 3 and is based on the ASN.1 AST produced by OpenGEODE's ''parse_asn1'' function.
 
  
= Usage =
+
Non-Qt Project -> Communication Device Project
  
$ asn2if dataview-uniq.asn [output.if]
+
[[File:Cd wizard 1.png]]
  
= Example =
 
  
Consider the following ASN.1 file (taken from the ''demoopngeode'' example):
+
CD wizard starts with “Project Location” tab. User shall provide Name for the project and path under which project will be created.
  
    TASTE-Dataview DEFINITIONS ::=
+
[[File:Cd_wizard_3.png]]
    BEGIN
 
    MyComplexType ::= SEQUENCE {
 
        a SEQUENCE { x INTEGER(0..255), y MyInteger }
 
    }
 
    MyComplexSeqOf ::= SEQUENCE(SIZE(2)) OF SEQUENCE { x INTEGER (0..255) }
 
    MyComplexChoice ::= CHOICE { a SEQUENCE { x INTEGER (0..255) } }
 
    EnableDisable ::= ENUMERATED {scrubon, scruboff}
 
    MyRefSeqOf ::= SEQUENCE { seqof MySeqOf }
 
    -- A few simple types to start with ASN.1
 
    MyInteger  ::= INTEGER (-255..255)
 
    MyReal     ::= REAL (-10.0 .. 1000.0)
 
    MyEnum     ::= ENUMERATED { hello, world, howareyou }
 
    MySeq     ::= SEQUENCE {
 
                a MyInteger,
 
                b ENUMERATED { taste(1), welcomes(2), you(3) }
 
    }
 
    MyChoice    ::= CHOICE {
 
                a BOOLEAN,
 
                b MySeq
 
    }
 
    MySeqOf     ::= SEQUENCE (SIZE (2)) OF MyEnum
 
    MyPossiblyEmptySeqOf ::= SEQUENCE(SIZE(0..2)) OF INTEGER (1..2)
 
    MySeqWithEmbeddedSeqOf ::= SEQUENCE {
 
        a SEQUENCE(SIZE(0..2)) OF BOOLEAN
 
    }
 
    MyOctStr    ::= OCTET STRING (SIZE (3))
 
    -- Include an embedded choice
 
    MyChoice2 ::= CHOICE {
 
        a BOOLEAN,
 
        b CHOICE {
 
        c BOOLEAN,
 
        d MyInteger
 
        }
 
    }
 
    END
 
    TASTE-BasicTypes DEFINITIONS ::=
 
    BEGIN
 
    -- Set of TASTE predefined basic types
 
    T-Int32 ::=  INTEGER (-2147483648 .. 2147483647)
 
    T-UInt32 ::= INTEGER (0 .. 4294967295)
 
    T-Int8 ::= INTEGER (-128 .. 127)
 
    T-UInt8 ::= INTEGER (0 .. 255)
 
    T-Boolean ::= BOOLEAN
 
    END
 
  
Following is the IF translation for this file:
+
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.
  
  type MyComplexType_a_x = range 0 .. 255;
+
[[File:Cd_wizard_4.png]]
  type MyInteger = range -255 .. 255;
 
  type MyComplexType_a = record
 
    x MyComplexType_a_x;
 
    y MyInteger;
 
  endrecord;
 
  type MyComplexType = record
 
    a MyComplexType_a;
 
  endrecord;
 
  type MyComplexSeqOf_elem_x = range 0 .. 255;
 
  type MyComplexSeqOf_elem = record
 
    x MyComplexSeqOf_elem_x;
 
  endrecord;
 
  type MyComplexSeqOf = array[2] of MyComplexSeqOf_elem;
 
  type MyComplexChoice_a_x = range 0 .. 255;
 
  type MyComplexChoice_a = record
 
    x MyComplexChoice_a_x;
 
  endrecord;
 
  type MyComplexChoice_selection = enum MyComplexChoice_a_PRESENT endenum;
 
  type MyComplexChoice = record
 
    present MyComplexChoice_selection;
 
    a MyComplexChoice_a;
 
  endrecord;
 
  type EnableDisable = enum EnableDisable_scrubon, EnableDisable_scruboff endenum;
 
  m4_enum_val(EnableDisable,(EnableDisable_scrubon, 0), (EnableDisable_scruboff, 1))
 
  type MyEnum = enum MyEnum_hello, MyEnum_world, MyEnum_howareyou endenum;
 
  m4_enum_val(MyEnum,(MyEnum_hello, 0), (MyEnum_world, 1), (MyEnum_howareyou, 2))
 
  type MySeqOf = array[2] of MyEnum;
 
  type MyRefSeqOf = record
 
    seqof MySeqOf;
 
  endrecord;
 
  type MyReal = range -10.000000000 .. 1000.000000000;
 
  type MySeq_b = enum MySeq_b_taste, MySeq_b_welcomes, MySeq_b_you endenum;
 
  m4_enum_val(MySeq_b,(MySeq_b_taste, 1), (MySeq_b_welcomes, 2), (MySeq_b_you, 3))
 
  type MySeq = record
 
    a MyInteger;
 
    b MySeq_b;
 
  endrecord;
 
  type MyChoice_selection = enum MyChoice_a_PRESENT, MyChoice_b_PRESENT endenum;
 
  type MyChoice = record
 
    present MyChoice_selection;
 
    a boolean;
 
    b MySeq;
 
  endrecord;
 
  type MyPossiblyEmptySeqOf_elem = range 1 .. 2;
 
  type MyPossiblyEmptySeqOf = string[2] of MyPossiblyEmptySeqOf_elem;
 
  type MySeqWithEmbeddedSeqOf_a = string[2] of boolean;
 
  type MySeqWithEmbeddedSeqOf = record
 
    a MySeqWithEmbeddedSeqOf_a;
 
  endrecord;
 
  type OctetStringElement = range 0 .. 255;
 
  type MyOctStr = array[3] of OctetStringElement;
 
  type MyChoice2_b_selection = enum MyChoice2_b_c_PRESENT, MyChoice2_b_d_PRESENT endenum;
 
  type MyChoice2_b = record
 
    present MyChoice2_b_selection;
 
    c boolean;
 
    d MyInteger;
 
  endrecord;
 
  type MyChoice2_selection = enum MyChoice2_a_PRESENT, MyChoice2_b_PRESENT endenum;
 
  type MyChoice2 = record
 
    present MyChoice2_selection;
 
    a boolean;
 
    b MyChoice2_b;
 
  endrecord;
 
  type T_Int32 = range -2147483648 .. 2147483647;
 
  type T_UInt32 = range 0 .. 4294967295;
 
  type T_Int8 = range -128 .. 127;
 
  type T_UInt8 = range 0 .. 255;
 
  type T_Boolean = boolean;
 
  
 +
Next tab is standard “Kit Selection” tab.
  
= Implementation =
+
[[File:Cd_wizard_5.png]]
  
''asn2if'' is implemented as a Python 3 module, based on the AST generated by OpenGEODE's ''parse_asn1'' function. The functionality is contained in the file ''asn2if/asn2if/asn2if.py'', which mainly consists of a class (''TypeVisitor'') implementing the Visitor pattern over the AST. ''TypeVisitor'' has one method for each ASN.1 type kind, which generates the equivalent IF type.  
+
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.
  
= About predefined operators on ASN.1 types =
+
[[File:Cd_wizard_6.png]]
  
Operators are implemented in IF via abstract types, and need to be implemented in C (in the .i file corresponding to the .if file of the system). For example, the math operators are defined by the following abstract type in IF:
+
===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
 +
|}
  
    type math = abstract
+
{| class="wikitable"
        integer abs(integer);
+
|-
        real abs(real);
+
|--taste.pro – empty taste.pro file that will be automatically generated during build
        integer fix(real);
+
|-
        real power(real, real);
+
|-- Makefile – entry build and clean procedure that includes Kazoo and SC dependencies definitions
        integer Shift_Left(integer, integer);
+
|-
        integer Shift_Right(integer, integer);
+
|-- deploymentvew.dv.xml – predefined deploymentview.dv.xml that includes CD build partition
        integer ceil(real);
+
|-
        integer floor(real);
+
|*--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.
        real float(integer);
+
|-
        integer round(real);
+
|-- <project name>.acn – ACN project model for custom binary encoding rules.
        real sin(real);
+
|-
        real cos(real);
+
|-- <project name>.asn – ASN non user-editable model that contains all the basic data types.
        integer trunc(real);
+
|-
    endabstract;
+
|-- <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.
 +
|}
  
Following IF's conventions, these are defined by equivalent C functions, provided in the .i file corresponding to the .if file of the system, as shown in the snippet below:
+
==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.  
  
#ifdef __math__
+
===CD IV file specifics – fixed system elements===
#include <stdlib.h>
+
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.
#include <math.h>
 
    if_integer_type if_abs_function(if_integer_type p) {
 
        return abs(p);
 
    }
 
    ...
 
#endif
 
  
''asn2if'' does not deal with the generation of this code, as the definition for these operators is the same for all TASTE systems, therefore it is included by AADL2IF in the skeleton of the IF system and its associated .i file (see [https://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_AADL2IF]).
+
[[File:Cd_broker_pack_iv_1.png|1100px]]
  
One exception regards enumerated types, the treatment of which is described below.
+
User can’t remove those element neither the interfaces and will be informed about that while trying to do so.
  
== Predefined operators for enum types ==
+
[[File:Cd_broker_pack_iv_2.png]]
  
Enum types defined in ASN.1 come with two predefined operators to convert to/from integer: ''num'' and ''val''. Since  IF does not support the specification of numerical values for the enum literals, the conversion operators to/from integer, have to be explicitly generated.  
+
===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.
  
AADL2IF generates the following abstract type, which is then filled with the operators generated by ''asn2if'':
+
[[File:Cd_broker_pack_iv_3.png|1100px]]
  
    type enum_functions = abstract
 
    undivert(7)
 
    endabstract;
 
  
Note that the <code>undivert(7)</code> refers to the m4 divert buffer number 7, which is used to store the declarations of ''num'' and ''val'' operators for all enum types. These are generated by the calls to ''m4_enum_val'' that appear in the IF translation example above. In fact, the definition of ''m4_enum_val'' (provided in AADL2IF's templates.m4 file, see [https://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_AADL2IF]), is as follows:
+
[[File:Cd_pack_params_1.png|t300px]]
 +
[[File:Cd_pack_params_2.png|500px]]
  
    define(`m4_enum_val',`
+
To avoid build errors another function can be connected to Broker and it’s implementation is not required.
    divert(7)
 
        integer num($1);
 
        $1 val_$1(integer);   
 
    divert(1)
 
    ')
 
  
For the example above, once the IF code is processed by m4, the following will appear in the generated IF file:
+
===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.
  
  type enum_functions = abstract
 
    integer num(EnableDisable);
 
    EnableDisable val_EnableDisable(integer);   
 
    integer num(MySeq_b);
 
    MySeq_b val_MySeq_b(integer);   
 
    integer num(MyEnum);
 
    MyEnum val_MyEnum(integer);   
 
  endabstract;
 
  
The generated .i file will contain the following:
+
[[File:Cd_mypack_code_2.png|t300px]]
 +
[[File:Cd_mypack_code_1.png|400px]]
  
#ifdef __enum_functions__
+
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.
if_integer_type if_num_function(if_EnableDisable_type p) {
 
    switch (p) {
 
        case if_EnableDisable_scrubon_constant: return 0;
 
        case if_EnableDisable_scruboff_constant: return 1;
 
    }
 
    return 0;
 
}
 
...
 
#endif
 
  
  
= Evolutionary maintenance =
+
[[File:Cd_mypack_code_6.png|t300px]]
If asn2if needs to be extended to support other ASN.1 type kinds, this can be done by adding a method visit_Kind, where Kind is replaced by the name of the type kind in the ASN.1 AST. Any additional operators related to the new type kind need to be generated by AADL2IF (see section 6.2).
+
[[File:Cd_mypack_code_5.png|400px]]
Regression testing is performed using the script asn2if/tests/runtests.sh. Additional tests can be added as subdirectories of tests. A tests subdirectory has to contain the following two files:
+
 
* dataview-uniq.asn : ASN.1 declarations
+
Communication Device project with packetizer component implementation is ready to be integrated wit full TASTE project. See another chapters to follow TASTE project integration.
* oracle.if : intended result of the ASN2IF 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.