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.

 

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.

 

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

 

Element Catalog DATAFLOW Runtime Package

 

 

 

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:

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.

 

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:

 

 

PlatformConfigApp description

 

RuntimeConfigApp.h

 

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

RuntimeConfigApp description

 

RemotingConfigApp

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

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

 

 

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

 

 

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