Difference between revisions of "Technical topic: SedsConverter"

From TASTE
Jump to: navigation, search
(Introduction)
m (Minor fixes in `Limitations` section)
 
(16 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
SedsConverter is a tool that provides EDS import/export capabilities to TASTE:  
 
SedsConverter is a tool that provides EDS import/export capabilities to TASTE:  
* generation of TASTE compliant ASN.1/ACN, AADL and SDL from EDS;  
+
* generation of TASTE compliant ASN.1/ACN, InterfaceView and SDL from EDS;  
* generation of EDS from TASTE AADL and ASN.1.
+
* generation of EDS from TASTE InterfaceView and ASN.1.
  
SedsConverter is a part of the [https://gitrepos.estec.esa.int/taste/spacecreator SpaceCreator] project. It can be used either from the command line interface or from SpaceCreator GUI.
+
InterfaceView XML files can be then converted to AADL with the usage of the SpaceCreator.
 +
 
 +
SedsConverter is a part of the [https://gitrepos.estec.esa.int/taste/spacecreator SpaceCreator] project. It can be used either from the command line interface or from the SpaceCreator GUI.
 +
 
 +
== Capabilities ==
 +
The following conversion directions are supported:
 +
* SEDS → ASN.1
 +
* SEDS → InterfaceView
 +
* SEDS → SDL
 +
* ASN.1 → SEDS
 +
* InterfaceView → SEDS
  
 
== Building and updating ==
 
== Building and updating ==
  
 
=== Building from sources ===
 
=== Building from sources ===
SedsConverter is being built as a part of the SpaceCreator. For the SpaceCreator building instructions please consult it's [https://gitrepos.estec.esa.int/taste/spacecreator/-/blob/master/README.md README] file.
+
SedsConverter is built as a part of the SpaceCreator. For the SpaceCreator building instructions please consult its [https://gitrepos.estec.esa.int/taste/spacecreator/-/blob/master/README.md README] file.
  
 
=== Updating with SpaceCreator ===
 
=== Updating with SpaceCreator ===
SedsConverter is being updated as a part of the SpaceCreator. To perform an update run the following commands in the terminal:
+
SedsConverter is updated as a part of the SpaceCreator. To perform an update run the following commands in the terminal:
 
     $ cd ~/tool-src
 
     $ cd ~/tool-src
 
     $ ./install/88_spaceCreator.sh
 
     $ ./install/88_spaceCreator.sh
  
 
== Console interface usage ==
 
== Console interface usage ==
 +
SedsConverter can be accessed through the SpaceCreator AppImage
 +
    $ spacecreator.AppImage --sedsconverter --help
 +
 +
If SedsConverter was built from sources, then the console interface can be found in the build directory
 +
    $ <build_dir>/bin/sedsconverter --help
 +
 +
=== Basic usage ===
 +
 +
Conversion requires input filename and conversion direction to be passed via options
 +
    $ spacecreator.AppImage --in <filename> --from <input models> --to <output models>
 +
i.e to convert a SEDS file to ASN.1 type the following command:
 +
    $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to ASN.1
 +
 +
 +
Models could also have dependencies. Those dependencies can be resolved in two ways:
 +
# User provides input files for all models that are required for the given conversion
 +
# SedsConverter tries to resolve dependencies using available inputs
 +
 +
Example: SEDS to InterfaceView conversion requires an ASN.1 model. User can either:
 +
provide ASN.1 input file to be used during the conversion
 +
    $ spacecreator.AppImage --sedsconverter --in input.xml,input.asn --from SEDS,ASN.1 --to InterfaceView
 +
or use SEDS input to create an intermediate ASN.1 model
 +
    $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to InterfaceView
 +
 +
 +
Additionally the intermediate models can be also exported using ''--aux'' option:
 +
    $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to InterfaceView --aux ASN.1
 +
 +
=== Available commands ===
 +
 +
==== ASN.1 ====
 +
{| 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
 +
|-
 +
| --asn1-sequence-size-threshold <threshold>
 +
| Maximum SEQUENCE size (values be clamped)
 +
|-
 +
| --patcher-functions-filepath-prefix <prefix>
 +
| <prefix> to add at beginning of the patcher functions output filepath
 +
|-
 +
| --mapping-functions-module-filename <prefix>
 +
| Name of the header including other patcher function files
 +
|}
 +
 +
==== InterfaceView ====
 +
{| class="wikitable"
 +
|-
 +
| --iv-config <file>
 +
| Specify config xml <file> for InterfaceView
 +
|-
 +
| --iv-generate-parent-functions
 +
| Generate parent functions for each SEDS package
 +
|-
 +
| --iv-data-types-seds-filepath <filepath>
 +
| Path to the SEDS file containing data types used in output IV
 +
|}
 +
 +
==== SDL ====
 +
{| class="wikitable"
 +
|-
 +
| --sdl-filepath-prefix <prefix>
 +
| SDL filepath <prefix>
 +
|}
 +
 +
==== SEDS ====
 +
{| class="wikitable"
 +
|-
 +
| --seds-preprocessed-filepath
 +
| Path to the intermediate file that will be created during preprocessing
 +
|-
 +
| --seds-schema
 +
| Specify schema <file> for SEDS
 +
|-
 +
| --seds-ext-ref <references>
 +
| Specify external <references> for SEDS, e.g. foo:bar,foo2:bar2,foo3:bar3,...
 +
|-
 +
| --seds-ext-ref-file <file>
 +
| Specify <file> with an external references for SEDS
 +
|-
 +
| --skip-validation
 +
| Skip validation for SEDS
 +
|-
 +
| --keep-intermediate-files
 +
| Keep SEDS intermediate files
 +
|-
 +
| --no-mangling
 +
| No mangling for interfaces names in SEDS to IV translation
 +
|-
 +
| --multiple-asn-models
 +
| Enable translation of single asn file with multiple asn models - DataSheet as an output
 +
|-
 +
| --skip-empty-sequences
 +
| Enable skipping of empty asn sequences during asn to seds translation
 +
|-
 +
| --seds-transaction-name-type <type>
 +
| Specify which ASN.1 <type> should be used for SEDS transaction name
 +
|-
 +
| --seds-enable-failure-reporting
 +
| Enable SEDS failure reporting
 +
|-
 +
| --seds-failure-reporting-type <type>
 +
| Specify which ASN.1 <type> should be used for SEDS failure reporting
 +
|-
 +
|  --seds-array-dimension-indexing-type <type>
 +
| Specify which ASN.1 <type> should be used for creating index type in SEDS ArrayDimension
 +
|}
  
 
== GUI usage ==
 
== GUI usage ==
 +
[[File:sedsconverter.png|350px|thumb|right|Menu with SedsConverter options available via GUI]]
 +
SEDS import and export operations are accessible through graphical user interface. The following options are available:
 +
* '''Import InterfaceView''' - a user selects a SEDS file containing component definitions; SedsConverter adds described functions and imports required ASN.1 data types to the currently open project
 +
* '''Import SDL''' - a user selects a SEDS file containing component implementations; SedsConverter converts this implementation to SDL and outputs it to dedicated .pr files
 +
* '''Import ASN.1''' - a user selects a SEDS file containing data type definitions; SedsConverter converts data type definitions and creates .asn and .acn files in the current project directory
 +
* '''Export InterfaceView''' - a user selects IV functions from the current project which will be exported to SEDS .xml file; a user selects a destination directory, where the output shall be placed by SedsConverter
 +
* '''Export ASN.1''' - a user selects ASN.1 and ACN files to be exported to SEDS .xml file; a user selects a destination directory, where the output shall be placed
 +
 +
 +
=== Import from SEDS ===
 +
 +
==== InterfaceView ====
 +
To import InterfaceView choose ''Tools -> SEDS -> Import InterfaceView'' and select SEDS file which contains definitions of the components that shall be imported. SedsConverter will merge imported IV and the one present in the project. Required ASN.1 data types and ACN descriptions will also be imported (corresponding .asn and .acn files will also be created).
 +
 +
[[File:sedsconverter_import_iv.png|t450px]]
 +
[[File:sedsconverter_import_iv_select_src.png|450px]]
 +
 +
==== SDL ====
 +
To import SDL choose ''Tools -> SEDS -> Import SDL'' and select SEDS file which contains implementations of the components that shall be imported. Required ASN.1 type definitions and ACN descriptions as well as required InterfaceView will also be imported (corresponding .asn and .acn files will also be created and InterfaceView will be merged with the current one).
 +
 +
[[File:sedsconverter_import_sdl.png|450px]]
 +
[[File:sedsconverter_import_sdl_select_src.png|450px]]
 +
 +
==== ASN.1 ====
 +
To import ASN.1 data types choose ''Tools -> SEDS -> Import ASN.1'' and select SEDS file which contains data type definitions that shall be imported.
 +
 +
[[File:sedsconverter_import_asn1.png|450px]]
 +
[[File:sedsconverter_import_asn1_select_src.png|450px]]
 +
 +
=== Export to SEDS ===
 +
==== InterfaceView ====
 +
To export InterfaceView functions choose ''Tools -> SEDS -> Export InterfaceView'' and select IV functions which shall be exported to SEDS. Click ''export to SEDS'' and in the next dialog select a destination directory for the output file.
 +
 +
[[File:sedsconverter_export_iv.png|350px]]
 +
[[File:sedsconverter_export_iv_select_function.png|280px]]
 +
[[File:sedsconverter_export_iv_select_dst.png|350px]]
 +
 +
==== ASN.1 ====
 +
To export ASN.1 data types choose ''Tools -> SEDS ->  Export ASN.1'' and select .asn and .acn files which shall be exported to SEDS. In the next dialog select a destination directory for the output file.
 +
 +
[[File:sedsconverter_export_asn1.png|350px]]
 +
[[File:sedsconverter_export_asn1_select_files.png|350px]]
 +
[[File:sedsconverter_export_asn1_select_dst.png|350px]]
 +
 +
== Limitations ==
 +
* AlternateSet works only for async commands
 +
** each Alternate shall have a single GenericTypeMap element with a fixed value
 +
** for each Alternate, the GenericTypeMap with a fixed value shall have the same name and type
 +
** the applicable Alternate element shall be chosen based on the value of this GenericTypeMap element
 +
* LengthEntry and ErrorControlEntry mapping functions are generated only for C
 +
* Async parameters are not allowed when using SEDS failure reporting mechanism
 +
* Type specification of component variables only includes ArrayDimensions
 +
* TypeCondition works only for ContainerDataType
 +
* Calibration splines with varying point orders are not supported
 +
* Sync commands with no associated transitions are not supported
 +
* VariableRef mapping is not supported for sync parameters
 +
* Nested swap operator is not supported in an expression
 +
* Cross-package container inheritance is not supported
 +
* Enumeration lowest value must be a 0
 +
* Exclusive min-max ranges are not supported for floating point values
 +
* Only single state machine is supported

Latest revision as of 13:22, 6 December 2022

Introduction

SedsConverter is a tool that provides EDS import/export capabilities to TASTE:

  • generation of TASTE compliant ASN.1/ACN, InterfaceView and SDL from EDS;
  • generation of EDS from TASTE InterfaceView and ASN.1.

InterfaceView XML files can be then converted to AADL with the usage of the SpaceCreator.

SedsConverter is a part of the SpaceCreator project. It can be used either from the command line interface or from the SpaceCreator GUI.

Capabilities

The following conversion directions are supported:

  • SEDS → ASN.1
  • SEDS → InterfaceView
  • SEDS → SDL
  • ASN.1 → SEDS
  • InterfaceView → SEDS

Building and updating

Building from sources

SedsConverter is built as a part of the SpaceCreator. For the SpaceCreator building instructions please consult its README file.

Updating with SpaceCreator

SedsConverter is updated as a part of the SpaceCreator. To perform an update run the following commands in the terminal:

   $ cd ~/tool-src
   $ ./install/88_spaceCreator.sh

Console interface usage

SedsConverter can be accessed through the SpaceCreator AppImage

   $ spacecreator.AppImage --sedsconverter --help

If SedsConverter was built from sources, then the console interface can be found in the build directory

   $ <build_dir>/bin/sedsconverter --help

Basic usage

Conversion requires input filename and conversion direction to be passed via options

   $ spacecreator.AppImage --in <filename> --from <input models> --to <output models>

i.e to convert a SEDS file to ASN.1 type the following command:

   $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to ASN.1


Models could also have dependencies. Those dependencies can be resolved in two ways:

  1. User provides input files for all models that are required for the given conversion
  2. SedsConverter tries to resolve dependencies using available inputs

Example: SEDS to InterfaceView conversion requires an ASN.1 model. User can either: provide ASN.1 input file to be used during the conversion

   $ spacecreator.AppImage --sedsconverter --in input.xml,input.asn --from SEDS,ASN.1 --to InterfaceView

or use SEDS input to create an intermediate ASN.1 model

   $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to InterfaceView


Additionally the intermediate models can be also exported using --aux option:

   $ spacecreator.AppImage --sedsconverter --in input.xml --from SEDS --to InterfaceView --aux ASN.1

Available commands

ASN.1

--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
--asn1-sequence-size-threshold <threshold> Maximum SEQUENCE size (values be clamped)
--patcher-functions-filepath-prefix <prefix> <prefix> to add at beginning of the patcher functions output filepath
--mapping-functions-module-filename <prefix> Name of the header including other patcher function files

InterfaceView

--iv-config <file> Specify config xml <file> for InterfaceView
--iv-generate-parent-functions Generate parent functions for each SEDS package
--iv-data-types-seds-filepath <filepath> Path to the SEDS file containing data types used in output IV

SDL

--sdl-filepath-prefix <prefix> SDL filepath <prefix>

SEDS

--seds-preprocessed-filepath Path to the intermediate file that will be created during preprocessing
--seds-schema Specify schema <file> for SEDS
--seds-ext-ref <references> Specify external <references> for SEDS, e.g. foo:bar,foo2:bar2,foo3:bar3,...
--seds-ext-ref-file <file> Specify <file> with an external references for SEDS
--skip-validation Skip validation for SEDS
--keep-intermediate-files Keep SEDS intermediate files
--no-mangling No mangling for interfaces names in SEDS to IV translation
--multiple-asn-models Enable translation of single asn file with multiple asn models - DataSheet as an output
--skip-empty-sequences Enable skipping of empty asn sequences during asn to seds translation
--seds-transaction-name-type <type> Specify which ASN.1 <type> should be used for SEDS transaction name
--seds-enable-failure-reporting Enable SEDS failure reporting
--seds-failure-reporting-type <type> Specify which ASN.1 <type> should be used for SEDS failure reporting
--seds-array-dimension-indexing-type <type> Specify which ASN.1 <type> should be used for creating index type in SEDS ArrayDimension

GUI usage

Menu with SedsConverter options available via GUI

SEDS import and export operations are accessible through graphical user interface. The following options are available:

  • Import InterfaceView - a user selects a SEDS file containing component definitions; SedsConverter adds described functions and imports required ASN.1 data types to the currently open project
  • Import SDL - a user selects a SEDS file containing component implementations; SedsConverter converts this implementation to SDL and outputs it to dedicated .pr files
  • Import ASN.1 - a user selects a SEDS file containing data type definitions; SedsConverter converts data type definitions and creates .asn and .acn files in the current project directory
  • Export InterfaceView - a user selects IV functions from the current project which will be exported to SEDS .xml file; a user selects a destination directory, where the output shall be placed by SedsConverter
  • Export ASN.1 - a user selects ASN.1 and ACN files to be exported to SEDS .xml file; a user selects a destination directory, where the output shall be placed


Import from SEDS

InterfaceView

To import InterfaceView choose Tools -> SEDS -> Import InterfaceView and select SEDS file which contains definitions of the components that shall be imported. SedsConverter will merge imported IV and the one present in the project. Required ASN.1 data types and ACN descriptions will also be imported (corresponding .asn and .acn files will also be created).

t450px Sedsconverter import iv select src.png

SDL

To import SDL choose Tools -> SEDS -> Import SDL and select SEDS file which contains implementations of the components that shall be imported. Required ASN.1 type definitions and ACN descriptions as well as required InterfaceView will also be imported (corresponding .asn and .acn files will also be created and InterfaceView will be merged with the current one).

Sedsconverter import sdl.png Sedsconverter import sdl select src.png

ASN.1

To import ASN.1 data types choose Tools -> SEDS -> Import ASN.1 and select SEDS file which contains data type definitions that shall be imported.

Sedsconverter import asn1.png Sedsconverter import asn1 select src.png

Export to SEDS

InterfaceView

To export InterfaceView functions choose Tools -> SEDS -> Export InterfaceView and select IV functions which shall be exported to SEDS. Click export to SEDS and in the next dialog select a destination directory for the output file.

Sedsconverter export iv.png Sedsconverter export iv select function.png Sedsconverter export iv select dst.png

ASN.1

To export ASN.1 data types choose Tools -> SEDS -> Export ASN.1 and select .asn and .acn files which shall be exported to SEDS. In the next dialog select a destination directory for the output file.

Sedsconverter export asn1.png Sedsconverter export asn1 select files.png Sedsconverter export asn1 select dst.png

Limitations

  • AlternateSet works only for async commands
    • each Alternate shall have a single GenericTypeMap element with a fixed value
    • for each Alternate, the GenericTypeMap with a fixed value shall have the same name and type
    • the applicable Alternate element shall be chosen based on the value of this GenericTypeMap element
  • LengthEntry and ErrorControlEntry mapping functions are generated only for C
  • Async parameters are not allowed when using SEDS failure reporting mechanism
  • Type specification of component variables only includes ArrayDimensions
  • TypeCondition works only for ContainerDataType
  • Calibration splines with varying point orders are not supported
  • Sync commands with no associated transitions are not supported
  • VariableRef mapping is not supported for sync parameters
  • Nested swap operator is not supported in an expression
  • Cross-package container inheritance is not supported
  • Enumeration lowest value must be a 0
  • Exclusive min-max ranges are not supported for floating point values
  • Only single state machine is supported