This Guide Article has been written for Version 2.1 of the DATAFLOW Software. For Previous Releases use the version selection in the navigation bar at the top of this page.

Installation

The ‘installation’ of DATAFLOW Runtime can be split into three parts: Prepare, Configuration and Setup Toolchain. Those steps are described in detail in the following chapters.

Note It is highly recommended to use DATAFLOW Designer to install and use DATAFLOW Runtime.

 

Prepare Imt.Base

The DATAFLOW Runtime package is provided as a bulk of ZIP archives that contain all required files for a specific architecture. The zip naming convention is described in Table 2.

The first step to use DATAFLOW Runtime in the project is to extract all ZIP files. The ZIP file contains at least an Imt.Base folder with one or more Imt.Base projects. These contains header files and Visual Studio 2015 projects. For source code variant, the source files are also included. For binary packages, all libs will be provided in the “lib” folder.

Note If required, the Visual Studio projects can be retargeted to VS2017 or VS2019

 

The ‘installation’ of the runtime is done by extracting all necessary zip files to your project folder and adding the folder under version control. The application (in Figure 8 as “MyApp”) and unit test project (in Figure 8 as “MyAppTest”) can then reference the required Imt.Base files. The “lib” folder in Figure 8 is only available if binary variant is extracted.

There is no need to install or deploy the runtime on the target, because it is compiled into the application binary and is deployed as that.

Example contents of DATAFLOW Runtime Package

 

Folder	Contents	Type	Target	Unit Test
Imt.Base	Main folder contains all files for the DATAFLOW Runtime and supporting libraries as packages.	Folder	-	-
doc	Contains the documentation as PDF.	PDF	-	-
lib	Contains all binary libraries for both the unit test and target build.	Binary	-	-
lib\<Platform>	Contains all binary libraries for target build. There are three types with different suffix: ·          *_d.a contains debug information ·          *_s.a contains debug and static analytics information ·          .a is used for release build without any additional information	Binary	X	-
lib\TestLib	Contains all binary libraries for the unit test build.	Binary	-	X
Example	Contains platform specific example projects.	Folder	-	-

Element Catalog DATAFLOW Runtime Package

 

Note With DATAFLOW Designer V1.4 and later, the installation of the Imt.Base packages can be automated. The ZIP packages will be installed in DATAFLOW Designer and are automatically deployed to your project when code is generated. See [1] for further documentation.

 

Note Ensure package attributes <language> and <toolchain> are identical to all installed packages, otherwise Imt.Base cannot built successfully! See chapter 3.1 for naming conventions!

 

Configuration Imt.Base

The next step is to configure the Imt.Base. Please continue in chapter 4.2.1 if you use source code variant, otherwise for binary variant to chapter 4.2.2.

 

Configure Source Code variant

This chapter describes the configuration when DATAFLOW Runtime is compiled from source code.

 

Configuration Files

Certain Imt.Base packages require a configuration file that defines for example the size of static buffers in internal implementation at compile time. The following configuration files must be copied to the specific target Location in Imt.Base folders prior to compilation when using the manual approach:

File	Used in Package	Target Location	Remarks
DiagnosticsConfigApp.h	Core	Imt.Base/Imt.Base.Core.Diagnostics/	Optional configuration of assertions.
PlatformConfigApp.h	Core	Imt.Base/Imt.Base.Core.Platform/	Defines target platform and optional headers
RuntimeConfigApp.h	Core	Imt.Base/Imt.Base.Dff.Runtime/	Defines static buffer size for the runtime.
RemotingConfigApp.h	Libremoting	Imt.Base/Imt.Base.Lib.Remoting/	Defines static buffer size for the library.

Configuration Files

 

As starting point, the files at the following location can be used:

cpp-gneric.runtime.source.core_x.y.z.0.zip\Imt.Base\CopyProject

It is recommended that the application specific configuration files are placed in a Config folder inside the project and copied before each build.

Note It is recommended to create a batch-script (or any other preferred scripting language like PowerShell, Python etc) to copy the configuration files from an application folder to Imt.Base. See also chapter “4.3.1.1 - CopyProject” for more information.

 

Preprocessor Defines

The source code of the Imt.Base library uses the preprocessor defines listed below. These defines must be set in the project configuration because they are used in the Platform.h. (Some defines will be automatically added by the toolchain / IDE).

 

PlatformConfigApp.h:

Build specific defines
Define	Purpose	Remarks
_DEBUG	Debugs Build	Enables debug asserts. Enables additional debug code. Also defines DEBUG.   Note: this will slow down runtime and should not be active in a productive system. See NDEBUG define.
NDEBUG	Releases Build	Disables debug asserts. Disables additional debug code. Undefines DEBUG and _DEBUG
_UNITTEST	Unit Tests Build	Enables unit test instrumentation code.

 

Application specific defines
Define	Purpose	Remarks
_PC_LINT	Analyzes Static Code	Can be used to hide low level code from static check.
USE_STL	Enables STL support	Uses STL containers. Provides methods for STL integration.
DATAFLOW_BSP	Builds BSP.	Sets OMIT_HARDWARE_EXCEPTION_HANDLERS. This will remove any interrupt handlers from the runtime code so that they can be implemented elsewhere (e.g. in a BSP). NOTE: The runtime will no longer work when this is set and not all required interrupts are implemented by the application code.
OMIT_HARDWARE_EXCEPTION_HANDLERS	Does not compile hardware exception handlers.	Used by HAL code to omit the definition of exception handlers so that application (or BSP) code can define them. (see above).
OMIT_EXPORT_TO_GLOBAL_NAMESPACE	Does not add using in-header files.	No use of declarations in header files that export types to the global namespace. Fully scoped names must be used to access types defined by the DATAFLOW Runtime.

 

Platform specific defines
Define	Purpose	Remarks
__CC_ARM	Defines Platform in Platform.h	Defined by the uVision (Keil) toolchain.
__IAR_SYSTEMS_ICC__	Defines Platform in Platform.h	Defined by the IAR Embedded Workbench for ARM (EWARM) toolchain.
__QNXNTO__	Defines Platform in Platform.h	Defined by the QNX Momentix toolchain.
WINCE	Defines Platform in Platform.h	Windows CE/Compact
WIN32	Defines Platform in Platform.h	Using WINDOWS (WIN32 or WINCE with SDK) and visual studio
_WINDOWS	Defines Platform in Platform.h	General Windows application (Desktop or CE/Compact)
_WIN32_GNU	Defines Platform in Platform.h	Uses the MinGW 32 GNU Toolchain.
_NIOS2	Defines Platform in Platform.h	NIOS2 Eclipse based Toolchain.
_UNICODE	Uses Unicode	Uses the Unicode version of string methods in visual studio. Also defines UNICODE

PlatformConfigApp description

 

RuntimeConfigApp.h

Defines
Define	Purpose	Remarks
USE_SMALL_EVENT_BUFFER	Enables small event buffer.	Used with constants EVENTDATA_SMALL_SIZE_BYTES.
RUNTIME_STATISTICS	Enables runtime statistics.	See chapter 6.8

 

Ensure following constants are defined in imt.base.dff.runtime c++ namespace!

Constants
Constant	Purpose	Remarks
int16_t EXECUTABLES_MAX	Sets executable (Active part) buffer size.	Defines the maximum number of active parts allowed.
int32_t EVENTPOOL_SIZE	Sets event buffer size.	Sets maximum number of events that can be queued. See also EVENTPOOL_SMALL_SIZE
int32_t EVENTPOOL_SMALL_SIZE	Sets small event buffer size.	Sets size of the additional small event buffer. Only used if USE_SMALL_EVENT_BUFFER is defined.
int32_t EVENTDATA_SIZE_BYTES	Sets size of a message slot in the event buffer.	Sets size of the largest message that can be used. See also EVENTDATA_SMALL_SIZE_BYTES
int32_t EVENTDATA_SMALL_SIZE_BYTES	Sets size of a message slot in the small event buffer.	Must be less than EVENTDATA_SIZE_BYTES. Only used if USE_SMALL_EVENT_BUFFER is defined.
int16_t TIMEPOOL_SIZE	Sets timer buffer size.	Defines the maximum number of timers allowed.
size_t STACK_SIZE_DEFAULT	Sets size of the default stack.	Can only be used for runtimes on RTOS that allow a stack per executable. Can be overridden with the ExecutableConfig in the active part constructor.
size_t STACKPOOL_SIZE	Sets size of the memory area reserved for stacks.	Must be large enough for all stacks.

RuntimeConfigApp description

 

RemotingConfigApp

Ensure following constants are defined in imt.base.lib.remoting c++ namespace!

Constants
Define	Purpose	Remarks
uint16_t REMOTING_MAX_MESSAGE_SIZE	Sets size of largest remoting message.	Defines the maximum message size that can be produced by a remote object.
uint32_t DATA_FRAME_SIZE	Sets the data frame size.	Defines the allowed data frame size.
uint32_t REMOTE_OBJECT_MAX	The maximal number of remoting objects.	maximum number of remote objects.

RemotingConfigApp description

 

Configure binary variant

This chapter explains the configuration for a binary release of DATAFLOW Runtime.

For binary releases, the build configuration is fixed and all configuration files can be found in the package. The configuration in those files MUST NOT be changes, otherwise the header files will no longer match the provided binary library and linker errors may occur.

To still provide some flexibility the memory footprint of the runtime can be controlled by providing a MessageDataPool to the runtime.

 

MessageDataPool

To provide the required memory for the static buffers to the runtime, the MessageDataPool.h header found in the Runtime package of the target platform (Imt.Base\Imt.Base.Dff.Runtime.<Platform>) must be implemented. The upper limit for the pool size can be found in Imt.Base\Imt.Base.Dff.Runtime\RuntimeConfigApp.h

Example:

// Main include
#include <Imt.Base.Dff.Runtime.NIOS2/MessageDataPool.h>

// Imt.Base includes
#include <Imt.Base.Core.Diagnostics/Diagnostics.h>

static const size_t MESSAGE_SIZE_BYTES = 100U;
static const size_t NUMBER_OF_MESSAGES = 64U;

static uint8_t s_messagePool[NUMBER_OF_MESSAGES * MESSAGE_SIZE_BYTES];

void MessageDataPool::clearMessageData(const size_t index) {
   ASSERT_EX(index < NUMBER_OF_MESSAGES);
   memset(reinterpret_cast<void*>(&s_messagePool[index * MESSAGE_SIZE_BYTES]), 0, 
   MESSAGE_SIZE_BYTES);
}

uint8_t* MessageDataPool::getMessageData(const size_t index) {
    ASSERT_EX(index < NUMBER_OF_MESSAGES);
    return reinterpret_cast<uint8_t*>(&s_messagePool[index * MESSAGE_SIZE_BYTES]);
}

size_t MessageDataPool::getMaximumMessageSize() {
    return MESSAGE_SIZE_BYTES;
}

size_t MessageDataPool::getMaximumNumberOfMessages() {
    return NUMBER_OF_MESSAGES;
}

 

Setup IDE for Imt.Base

As third and last step a toolchain for Imt.Base must be setup. If an IDE setup already exists you can include Imt.Base packages in the already existing solution otherwise a new setup is required.

 

Visual Studio

For visual studio, add all required Imt.Base projects to your solution and set a dependence from the application project to the Imt.Base projects.

VisualStudio example solution structure

 

For Binary Releases, there are no Imt.Base projects to add. The headers can be added to the solution.

The HAL projects are provided as source code in binary releases as well. These projects must be added as shown above.

In the following figure the customer application project has been configured, ensure “Additional Include Directories” is referenced to Imt.Base folder in all VisualStudio projects, otherwise the #include <..> will not work.

Visual Studio customer project setup

 

NOTE This can be automated when the DATAFLOW Frames Project generator module is used in DATAFLOW Designer.

 

CopyProject (Only Source Code)

It is recommended to create an empty c/c++ VisualStudio Project called “CopyProject” and add them to the Application Solution. The CopyProject must be executed as the first project when the solution is built. This can be done by setting a build dependency from Imt.Base.Platform to the CopyProject.

It must contain a pre build step that copies the configuration header files (explained in chapter 4.2.1.1) to target location:

Visual Studio 2015 - CopyProject configuration

 

CopyProject -> Properties -> Build Events -> Pre-Build Event -> Command Line:

copy "$(SolutionDir)CopyProject\PlatformConfigApp.h" "$(SolutionDir)Imt.Base.Core.Platform" /Y
copy "$(SolutionDir)CopyProject\DiagnosticsConfigApp.h" 
"$(SolutionDir)Imt.Base.Core.Diagnostics" /Y
copy "$(SolutionDir)CopyProject\RuntimeConfigApp.h" "$(SolutionDir)Imt.Base.Dff.Runtime" /Y
copy "$(SolutionDir)CopyProject\RemotingConfigApp.h" "$(SolutionDir)Imt.Base.Lib.Remoting" /Y

 

Note This can be automated when the DATAFLOW Frames Project generator module in DATAFLOW Designer is used.

 

IAR Workbench

For IAR Workbench for ARM, it is recommended to add all required Imt.Base files to the same project as the application source code.

IAR Project Workspace

 

For Binary Releases, there are no source files to add, but the procedure remains the same.

The HAL projects are provided as source code in binary releases as well. These source files must be added as shown above.

To support Imt.Base ensure c++ is enabled and the “Additional include directories” includes are be configured to the Imt.Base location.

To copy the required configuration files, a simple batch script can be used and in IAR a Pre-Build step configure:

IAR configure build action

 

For binary releases, the linker configuration must contain all used libraries from the package.

IAR Linker config

 

Stack Usage

The stack usage can be monitored with the following approach:

• Enable graphical stack display and stack usage tracking inside IAR Embedded Workbench for ARM (Tools/Options/Stack)

Enable graphical stack display and stack usage tracking

• Run the application software with IAR Embedded Workbench for ARM
• Display the stack view (View/Stack/Stack 1)
• Interact with the device
• Break the software an examine the stack usage

Example stack usage

 

Flash/RAM Usage

The flash and the RAM usage can be monitored with the following approach:

• Enable generating linker map file inside IAR Embedded Workbench for ARM if not already done (Project/Options/Linker/List)

Enable generating linker map file

• Generate the .map file through a rebuild of the project.
• Inside the .map file navigate to the “MODULE SUMMARY” section (remark: inside rw data the reserved stack memory is also included)

Example static ROM, RAM usage of a .map file

 

SYSTEM Load

The CPU load (=time while the microprocessor is not in idle) can be monitored in hardware with the following approach:

• Use a free debugging output pin and attach an oscilloscope
• When entering an interrupt (RuntimeInterrupts::applicationIsrEntry), set the output pin to high
• When entering the idle callback, set the output pin to low

The resulting high time of the signal is the overall CPU load in %.

 

Debug Binary Runtime

When an application built with the binary runtime is debugged, the IAR workbench requires a path to the header files provided in the Imt.Base package.

When a symbol of the runtime is selected, the following dialog may be displayed:

IAR Debug Path

 

Select the header file located in the Imt.Base folder to solve this issue.

 

Hardware Specific Setup

The remaining setup of the IAR depends on the used target hardware. If an RTOS variant of the DATAFLOW Runtime is used, a HAL for the specific target hardware must also be added to the project.

Please refer to the IAR documentation and the reference manual for the used microprocessor for more information.

 

Other IDE

For Other IDE such as Eclipse-Based IDE, it is recommended to add all required Imt.Base files to the same project as the application source code.

To copy the required configuration files, a simple

 

Required Module: DATAFLOW Runtime

This Article has been written based on V2.1.1 of the DATAFLOW software. 
Latest update 2023-05-31 by WUM.