Introduction

Purpose and Scope

This document describes the functionality of the DATAFLOW Code generator. This includes basic functionality, configuration and the command line interface.

The document has been written for developers that want to generate code using the generator by writing the DSL files by hand as well as for developers of the DATAFLOW Designer software. Please refer to the Tech Note for DATAFLOW Designer [1] if the generator is used in conjunction with that software.

It is assumed that the reader of the documentation is familiar with the DATAFLOW Architecture and terms such as Active Part, Protocols and the DATAFLOW Runtime, which are explained in [2].

Referenced Versions

The Tech Note has been written based on the following versions:

DATAFLOW Code Generator:           Version 2.2.1

Conventions used in this document

Command line: All command line examples are written with a mono space font and are highlighted with a gray background:

$ DffStudio.App.Generator.exe [arguments]

Syntax: All syntax DSL and configuration examples are written with a mono space font and are highlighted with a green background:

import "LegacyAPC.dff"
startupController (root:Legacy) {
}

There are few special characters used in the syntax sections:

Notes: Important remarks are highlighted with a blue background:

Document Overview

This document contains the following parts:

2 Overview                            Explains the concepts of the DATAFLOW Code Generator.

3 Basic Functionality                        Explains the functionality of the DATAFLOW Code Generator.

4 Installation                         Explains the installation of the code generator.

5 Usage                                 Contains step by step explanation of common use scenarios.

Overview

The DATAFLOW Code Generator is a command line utility that generates source code for types [1] and components [2] from the DATAFLOW DSL [3] Language. Using the generator allows the developer to focus on implementation at the level of component behavior instead of writing containers, connecting channels and serializing and de-serializing protocols. Because the generated code does not contain the typical errors made by a developer writing those classes by hand, it also reduces the risk of errors in the software.

Separation of generated code from user code

The generator generates two types of source code files:

1. Auto-Generated files. These files will always be overwritten upon generation. The user MUST NOT change these files in any way.
2. Handler files. These files are generated once for the user to fill in the behavior of the class. The generator will not overwrite existing handler files if it is not forced to do so in the generator configuration (see below).

Namespaces

The generator will create a folder for each namespace and place the generated classes and tests inside it.

For the root namespace, no folder is created when C++ code is generated. The creation of the root namespace folder can be forced in the generator configuration (see below).

In the configuration, the root namespace can be defined. The DSL syntax makes it possible to define a sub namespace for every generated type and component.

• This feature has not been validated for the current release. Use it at your own risk.

Verification of the code

The generator has been validated by DATAFLOW Software to ensure that a given DSL input will always result in the same generated source code. DATAFLOW Software cannot guarantee that the toolchain used to compile and link the source code will not produce any issues.

All generated code fulfills all known static code analysis requirements (e.g., MISRA C++).

Basic Functionality

The generator is able to generate protocols with the required identifiers and enumerations. It also generates Active Parts, Active Containers, Active Interrupts and startup controllers. All of those are explained in the following chapters.

Protocol

The generator is able to generate protocols. A protocol is a class with a number of fields that can be serialized to a byte stream and also de-serialized from a received byte stream. The generated class implements the Serializable interface from the Imt.Base library.

This makes it possible to send messages over any serial communication channel. It is also required to send messages in the DATAFLOW runtime. All generated protocol implementations are byte compatible over all generated languages. This means a message serialized with one language and de-serialized with another language using the same protocol contains the same fields as before serialization.

Protocol Generation

Protocol Fields

A protocol consists of fields. Each field can have one of the following basic types:

Protocol Fields

Any field can also be declared as an array instead of a scalar value. This includes enums and nested protocols.

Identifier

The generator generates constants for the protocol identifiers, which are used to identify the sent message type in the byte stream in order for the receiver to know which protocol must be used to de-serialize the received message.

Identifier Generation

Signals

The generator also supports signals. These are identifiers with no protocol assigned to them.

They are used in the DATAFLOW runtime to send a message with no fields by passing NULL as a second argument to the write method on a PortOutput in the Imt.Base.Dff.ActiveParts library.

Enumeration

For each defined enumeration, a type safe enumeration with range constants is generated. This makes it possible to iterate over the values and get the minimal and maximum values. Enumerations can be used directly in the code or as fields in protocols.

Enumeration Generation

Active Part

For each Active Part defined, the following is generated:

• main class
• interface
• handler
• unit test

Active Part Generation

Main class

The main class instantiates all output ports and timers that have been defined. It also implements the generated interface (see below) and creates the instance of the handler. The defined name, priority, stack size and time slice are also passed to the runtime in the constructor.

Interface

The interface contains a type safe send method for every protocol assigned to a port. This method will send the message over the correct port using the correct identifier.

For ports with no protocol, a generic send method is created that takes a protocol identifier and a serializable interface. A getter method is created for every timer so that the handler or any of its children can access them.

handler

The handler contains an empty method for every protocol assigned to the input port and for every timer event. It receives a reference to the interface as a constructor parameter. The developer should implement the behavior of the Active Part in the handler methods. It is also possible to add additional classes like state machines and pass the interface to them.

Since V2.1, the handler can also be replaced with C style functions. These are assigned to certain events and will then be called by the main class when this event occurs. The generated interface is passed as an argument to these methods.

Unit Test

The generated test makes sure that the priority of the Active Part is set as defined.

Tests for behavior must be either added to this file or provided in a separate file.

If the tests are added to the same file the generator should not overwrite existing test classes. This can be achieved by NOT setting the following command line argument: OverwriteTests:

(See also 5.1).

Active Interrupt

For each Active Interrupt defined, the following is generated:

• main class
• interface
• handler
• unit test

Interrupt Active Part Generation

Main class

The main class instantiates all output ports that have been defined. It also implements the generated interface (see below) and creates the instance of the handler. The interrupt handler methods are also created with the defined name. A static instance of the class is created so that it can be accessed from the handler. The implementation will call applicationIsrEntry, the handler method and applicationIsrExit of the DATAFLOW runtime.

Interface

The interface contains a type safe send method for every protocol assigned to a port. This method will send the message over the correct port using the correct identifier.

For ports with no protocol, a generic send method is created that takes a protocol identifier and a serializable interface.

Handler

The handler contains an empty method that is called whenever the interrupt occurs. It also receives a reference to the interface as constructor parameter. The developer should implement the behavior of the interrupt Active Part in the handler methods.

Unit Test

The generated test makes sure that generated interrupt handler calls the enter/exit interrupt methods of the runtime.

Tests for behavior must be either added to this file or provided in a separate file.

If the tests are added to the same file the generator should not overwrite existing test classes. This can be achieved by NOT setting the following command line argument: OverwriteTests: (See also 5.1).

Active Part Container

For each Active Part container defined, the following is generated:

• main class
• unit test

Active Container Generator

Main class

The main class instantiates all children of the container (other containers, Active Parts and interrupt Active Parts). It also contains references to the port of those children so that they can be accessed from outside of the container. All channels between children of the container are created and connected.

Unit Test

The test verifies that

• all channels are connected as defined
• all connectors reference the defined port
• Each child is initialized on initialization of the container
• Each child is started on start of the container

Startup Controller

For each startup controller defined, the following is generated:

• main class

Startup Controller Generator

Main class

The main class contains the application main method. There must not be more than one startup controller per application.

The generated startup controller performs the following:

• Register assertion handlers for ASSERT_EX and ASSERT_DEBUG
• Initialize static Application class (from BSP)
• Instantiate given root APC
• Call Application.run and pass root APC instance.
• Trigger ASSERT_EX when run exits (must not happen).

Supported Languages

The current Code-Generator version supports the languages listed in the table below. Please note that not every feature is available for every language in the current version. If required by a certain project, additional features or languages can be added in newer versions.

Supported Features by Language

Installation

The DATAFLOW Code Generator is part of the DATAFLOW Designer installation explained in the DATAFLOW Designer Tech Note [1].

Release Notes

The up-to-date release notes for all released generator versions can be found in [4].

Licensing

The DATAFLOW Code Generator requires a DATAFLOW License with enabled code generation option. When the generator is used from within DATAFLOW Designer, the same license is used for the generator as well.

If the generator is used on the command line, the user must make sure that he signs in with a valid DATAFLOW user first.

Usage

The Generator is usually called directly from DATAFLOW Designer. If it is used from the command line, then it is recommended to create a batch file. This file calls the Generator and passes one or more DSL files and the configuration directory to be used.

@ECHO OFF

DffStudio.Generator.App.exe -configdir ./config –SourceFile MyAp.dff –user test

pause

This batch file can then be configured as a pre-build process in your favorite IDE.

CLI Arguments

The code generator is controlled using a command line interface (CLI). The following table shows all supported arguments. The arguments are case insensitive.

CLI Arguments

Example output with no arguments

$ ./DffStudio.App.Generator.exe
DffStudio.App.Generator - Version 2.1.1.0

Usage: DffStudio.App.Generator[arguments]

Arguments:

-Help                               Displays this message and exits.
-Version                            Displays the version and exits.
-SourceFile [path]                  Defines the input file (mandatory).
-ConfigDir  [path]                  Defines the config directory (optional, defaults
                                    to working directory).
-CmdFormat  [dataflow|standalone]   Defines the output format (optional, 
                                    defaults to standalone).
-OverwriteHandlers                  Overwrites APHandler files.
-OverwriteTests                     Overwrites UnitTest files.
-Verbose                            Enables additional output
-SignIn [Email] [Password] [Server] Signs in to execute DATAFLOW Generator.
-SignOut                            Signs out the current user from all dataflow applications.
-User                               The username that is used to overwrite the 
                                    logged-in user’s e-mail address.

Configuration

The configuration is read from the given configuration folder or from the working directory, if not specified. The following configuration files are supported:

• Generator configuration
• Parser configuration
• Style configuration
• File header templates

Generator Configuration

The generator configuration controls the code generation. Changes to those parameters will lead to a change of functionality in the generated code. For all omitted parameters, the default value given below is used.

File:               generator.json

Version:        4

Generator Configuration Parameters

Example of a Generator Configuration

{
"GeneratorOptions": {
   "Version": 4,
   "Data": {
     "Language": "CPP98",
     "Platform": "STM32_F103_HD",
     "Runtime": "ARM_CORTEX_M3",
     "RuntimeVersion": "2.5",
     "RootNamespace": "dataflow.example",
     "ComponentNamespace": "components",
     "TypeNamespace": "protocols",
     "GenerateTests": true,
     "RootPathSrc": "src/MyApp/App",
     "RootPathTests": "src/MyApp/Unittest",
     "CppFolderForRootNamespace": true,
     "CustomCtorMaxArgs": 3
   }
}
}

Language

The following values are supported for the Language parameter:

This parameter can also be printed in the file header. See ‘File Header Templates’.

Additional languages may be added for future versions.

Platform

The following values are supported for the Platform parameter:

1) Startup controller is adapted to platform.

2) This feature has not been validated for the current release. Use it at your own risk.

This parameter can also be printed in the file header, see ‘File Header Templates’.

Additional platforms may be added for future versions.

Runtime

The following values are supported for the Runtime parameter:

1) Startup controller is adapted to runtime type.

2) This feature has not been validated for the current release. Use it at your own risk.

This parameter can also be printed in the file header. See ‘File Header Templates’.

Additional runtime types may be added for future versions.

• RuntimeVersion

The RuntimeVersion parameter must define the major version of the supported runtime in the format ‘X.Y’. This will affect the generation of the startup controller. This parameter can also be printed in the file header. See ‘File Header Templates’.

• Namespaces

The generator configuration allows you to define the namespace for all generated types and components. Each component can also add a sub namespace in its DSL description.

The final namespace of a component is defined as follows:

RootNamespace + ComponentNamespace + DSL Namespace

The final namespace of a type is defined as follows:

RootNamespace + TypeNamespace + DSL Namespace

• Generate Flags

The generator only generates source files (for both types and components) when the GenerateSrc parameter is set to true.

The generator only generates unit test files (for both types and components) when the GenerateTests parameter is set to true.

• File Paths

The generator will place each generated file at the configured location. The path can be configured individually for source, test and meta files.

The path for a source file is defined as follows:

RootPathSrc + Full Namespace (see above)

The path for a test file is defined as follows:

RootPathTests + Full Namespace (see above)

The path for a meta file is defined as follows:

RootPathMeta

• C++ Test Framework

Defines the unit test framework for all generated C++ unit tests.

The following values are supported for the CppTestFramework parameter:

   1) All C++ unit tests are generated for the given unit test framework.

• Test Categories

If supported by the configured test framework (see above), each generated unit test will be added to the given category using an attribute or similar mechanic of the test framework. The category can be specified for each generated artifact independently using the parameters TestCategoryProtocol, TestCategoryAP, TestCategoryAPC and TestCategoryAPIrq.

• C++ Specific configuration

When the Language is set to C++11 or newer, the Cpp11TrailingReturnType parameter will enable the generation of trailing return types in the form:

auto method(int8_t arg) -> int32_t;

If set to false, the C++98 style is used:

int32_t method(int8_t arg);

Functions with the return type void are not affected.

• Parser Configuration

The parser configuration controls the DSL parser. For all omitted parameters, the default value given below is used.

File:               parser.json

Version:        1

Table 5 - Parser Configuration Parameters

Example Parser Configuration

• Style Configuration

The generator configuration controls the generated coding style. Changes of those parameters will not change the functionality in the generated code. For all omitted parameters, the default value given below is used.

File:               style.json

Version:        3

Table 6 - Style Configuration Parameters

Example Style Configuration

• Brace Style

The following values are supported for the BraceStyle parameter:

Example ALLMAN

Example KR

Example IMT

When CppForceNewlineAfterInitializerList is set to true, the opening brace after a constructor initializer list is placed on a new line while ignoring the BraceStyle parameter.

Example

BraceStyle KR, CppForceNewlineAfterInitializerList False

BraceStyle KR, CppForceNewlineAfterInitializerList True

• Line Endings

The following values are supported for the LineEnding parameter:

• Indentations

The code generator will write IndentCount number of spaces (ASCII 0x20) for each indention level. If IndentWithTabs is set to true, the same number of tabs (ASCII 0x0x11) will be used instead.

The number of indent levels can be configured independently for several cases:

IndentAccessSpecifiers will indent all access specifiers in C++ classes.

IndentBraces will indent braces x (x can be set by the user) times. This will not affect the contents of a block formed by the braces.

IndentBlockContents will indent the content of blocks x times. This will not affect the contents of namespaces or classes because there is a specific parameter for that.

IndentClassContents will indent the content of classes x times.

IndentCaseContents will indent the content of a case in a switch case statement x times. Note that a block inside a case is also indented with IndentBlockContents.

IndentCaseLabels will indent the case label in a switch case statement x times.

IndentNamespaceContents will indent the content of a namespace x times.

IndentInitializerLists will indent the constructor initializer list x times.

Examples

IndentCount                                          1

IndentWithTabs                                    True

IndentBraceContents                          0

IndentBraces:                                        0

IndentNamespaceContents               1

IndentCaseContents                           1

IndentCaseLabels                                0¨

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          1

IndentBraces:                                        0

IndentNamespaceContents               0

IndentCaseContents                           0

IndentCaseLabels                                0

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          2

IndentCaseContents                           0

IndentCaseLabels                                1

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          1

IndentCaseContents                           1

IndentCaseLabels                                1

void Unit01AP::execute(const uint16_t protocolIdentifier, Deserializer& deserializer) {

˽˽switch(protocolIdentifier) {

˽˽˽˽case RuntimeProtocolIdentifiers::TIMER: {

˽˽˽˽˽˽RuntimeTimerEvent timerEventArgs(deserializer);

˽˽˽˽˽˽handleTimer(timerEventArgs);

˽˽˽˽}

˽˽˽˽break;

˽˽˽˽default:

˽˽˽˽˽˽// Ignores all other protocols

˽˽˽˽˽˽ASSERT_DEBUG1(false, "Unknown protocol in Unit01AP.");

˽˽˽˽˽˽break;

˽˽}

}

• Padding Flags

The number and placement of spaces inside of braces, brackets and parentheses is controlled using the padding flags BracePadding, PracketPadding and ParenthesePadding.

The following flags are supported:

• The example is given for parentheses, but it will work the same way for the other paddings.

For operators and keywords, only the INSIDE_BEFORE and INSIDE_AFTER has an effect.

The flags can be combined, and there will be no more than one space at one of the possible locations.

Example

ParenthesePadding AFTER_OPEN,INSIDE_BEFORE,INSIDE_AFTER

• Documentation Style

The following values are supported for the CppDocStyle parameter:

Example JAVADOC

Example QT

• Static Check Excludes

The following values are supported for the CppStaticCheckExcludes parameter:

• File Header Templates

The generator allows the definition of header templates (see Style Configuration). These are ASCII files with placeholders that are replaced by the values from the generator.

For all C++ Header files, the file from HeaderFileHeaderTemplate is used.

For all C++ Source files, the file from SourceFileHeaderTemplate is used.

For all C++ Unit Test files, the file from TestFileHeaderTemplate is used.

The following placeholders are supported:

Example of a File Header Template

• DSL Files

The generator uses version 2 of the DATAFLOW DSL. The complete syntax is specified in [3] and will not be duplicated in this document. This document can be provided by IMT AG if required.

• Meta File

The generator writes a meta file for each generated artifact parsed from DSL. This file contains details on the generated files and the full path. This is used for integration in DATAFLOW Designer or other tools.

• Glossary
  
  

[1] Types is a short form for Protocol and Enumeration

[2] Components is a short form for Active Part, Active Container and Active Interrupt

[3] Domain-specific-Language

This Article has been written based on V2.2.1 of the DATAFLOW Code Generator software. 
Latest update 2022-04-09 by WUM.

Required Module: DATAFLOW Code