Technical topic: Add a new target platform to TASTE

Introduction

This section is a step by step tutorial for adding a new target (CPU + operating system) based on one of the existing TASTE runtimes. The process is made of two steps:

1. Making the new target visible for the user in the toolchain and recognized by the parsers
2. Updating the templates for the actual use of the new target when generating code

For the first step we have to create a target identifier, and add it at different places of the toolchain so that it is eventually made visible to the hardware library in Space Creator. While there are multiple files to update, this process it straightforward:

• update of the AADL meta-models (add a new platform)
• update of the AADL parser (Ocarina)
• update of the AADL library of components (add a new CPU board for the given platform)
• update of Space Creator list of platforms

The second step is a bit more technical as it relates to the actual configuration of the target for the build process:

• update of the script that checks if the platform-dependent tooling (cross-compiler, RTOS) is installed
• update of the generated project files (configuration of the cross-compiler)
• selection/update of the templates to map the selected TASTE runtime to the new target

The paths are relative to ~/tool-src in the TASTE VM.

The tutorial is based on an example: adding support for a generic ZynQ platform with the RTEMS operating system, using the PolyORB-HI-C (*) runtime.

(*) PolyORB-HI-C is one of TASTE's middleware components. It runs on top of a set of operating systems like Linux and RTEMS, and is charge of the scheduling and message passing of a system/.

Update of Ocarina

1. Edit ocarina/src/backends/ocarina-backends-properties.ads, and look for “Supported_Execution_Platform”. Add a platform as shown below

2. Edit ocarina/src/backends/ocarina-backends-properties.adb, and add the string that the parser needs to read, like this

Also update the API:

3. You must specify the endianness of the platform in ocarina/src/backends/po_hi_c/ocarina-backends-po_hi_c-deployment.adb

4. In ocarina-backends.po_hi_c.adb, add this:

(NOTE: it is related to the Ocarina-generated Makefile, that is not used in TASTE. However, it is essential to modifiy the code to avoid an error at compile time)

Update of AADL files

1. Add the platform in the AADL metamodel: ocarina/resources/deployment.aadl

2. Create a new board in tool-src/misc/aadl-library/ocarina_components.aadl

Update of Space Creator

Once the platform has been added to ocarina_components.aadl it can be made available to Space Creator (the TASTE user interface). Edit the following file:

  $ vi misc/space-creator/Board1.xml

And add the board by making reference to the corresponding model in ocarina_components.aadl:

If your board has IO ports (serial, ethernet..) mimick the constructs in this file to add them.

Update of Kazoo

At this point we need to select a runtime for the new target. The runtime makes the layer between the user code and the underlying operating system. A part of the runtime is a generic library providing functionality such as message handling, while another part is generated during the build: the runtime threads, communication buffers, and other artefacts that are specific to the user project.

Runtimes have a part that hooks to an underlying operating system and the selection of a runtime depends on the possibly already existing support for the API of an OS (FreeRTOS, RTEMS, Linux ...).

In this tutorial we use the PolyORB-HI-C runtime which already supports the POSIX API of the RTEMS operating system. Another TASTE runtime supports the native RTEMS API. At the end of the tutorial we give instructions to add support to a Linux runtime for non-x86 targets.

We will now configure the cross-compiler for RTEMS on this target

1. Go to ~/tool-src/kazoo/templates/concurrency_view and copy from existing templates:

2. Go to c_pohi_zync_rtems_cgpr and edit filepart.tmplt to specify the filename you want to generate:

3. Edit partition.tmplt to specify the compiler and compilation flags:

Note: the template format is the one of the "templates-parser" library. Documentation can be found here: http://docs.adacore.com/live/wave/aws/html/template_parser/index.html

4. Do the same for the "gpr" folder

The generated gpr file is based on the "gprbuild" build system. Extensive documentation is available online.

5. Last step, the Makefile.<node_name> must call the newly generated gpr file for this platform. Edit:

~/tool-src/kazoo/templates/concurrency_view/c_pohi_gpr/node.tmplt

Build and installed the modified libraries

1. Build and install kazoo

2. Build and install Ocarina

Update the platform check script

When building a project in TASTE there is a check that verifies that nodes can actually be compiled, i.e. that the new target runtime (cross compiler, OS) is installed on the build machine. The script is in misc/helper-scripts/, you have to edit it:

  $ vi misc/helper-scripts/check_deployment_target_cli.py

There is a map with the key being the name of the platform, and the value being a function that is in charge of checking the installation:

The key is formed by the name you set in the Ocarina files before. Add the function to make the check:

If the target is not installed you must raise a NotImplementedError exception and pass as parameter the name of another function, that is in charge of the installation itself:

It is important to fill in the documentation of the function (the first line) as it is used to tell the user how to install manually.

You can then save this file and update your installation:

  ./install/90_misc.sh

Reuse the C++ runtime for Linux targets

In this tutorial we presented the templates that had to be updated to add a target reusing the PolyORB-HI-C runtime. TASTE also provides a C++ runtime that is optimal for generating Linux-based applications. It is possible to use this runtime on various targets that run Linux: if you have a cross-compiler available, adding support is easy. For example, Debian 11 provides cross-compilers for a large number of processors: aarch64, alpha, arm (32 bits), hppa, i686, m68k, mips, riscv64, sparc64, etc...

TASTE comes with pre-configured support for x86 and ARM processors, but you can add yours easily. The only things you have to do are:

• enabling the C++ runtime templates for the new target
• adding a template where you specify which cross-compiler you need
• disabling the templates that generate the (default) PolyORB-HI related code

Enable the C++ runtime for the new target

Go to the kazoo/concurrency_view folder. There is a number of subfolders here that contain the templates used to generate the code of the C++ runtime. In each subfolder there is a file named "trigger.tmplt". This file contains a flag set to TRUE to enable the template generation depending on a condition. The condition can be the platform name (as defined earlier. for example to add the support to the ARM platform the following was added:

@@IF@@ @_CPU_Platform_@ = PLATFORM_GENERIC_LINUX or @_CPU_Platform_@ = PLATFORM_ARM_LINUX_CPP
TRUE
@@END_IF@@

You have to apply this exact pattern to the following template folders:

generic_system_spec_body    
generic_system_spec_header
generic_routing_table_initializer
generic_routing_table_header
generic_routing_table_body

Note: these five folders are shared between several runtimes - they deal with packet routing, making sure that a packet sent e.g. from Linux/ARM will be properly decoded by a runtime on FreeRTOS/MSP430.

Then the Linux-specific template folders for the C++ runtime also have to be enabled the same way:

generic_linux_wrappers_header
generic_linux_wrappers_body
generic_linux_transport_header
generic_linux_transport_body
generic_linux_thread_header
generic_linux_thread_body
generic_linux_runtime
generic_linux_request_size
generic_linux_main                 # generate main.cc

Set the cross-compiler

Copy the folder named "generic_linux_gpr" to a new folder with a different name:

$ cp -a generic_linux_gpr arm_linux_cpp_gpr  # to support the ARM cross-compiler

then inside the new folder, change (as above the trigger.tmplt'file) and edit the file named partition.tmplt. You will find a placeholder to set your cross compiler name for C, C++ and Ada:

  package Compiler is
     for Driver ("C") use "arm-linux-gnueabihf-gcc";
     for Driver ("Ada") use "arm-linux-gnueabihf-gcc";
     for Driver ("C++") use "arm-linux-gnueabihf-g++";

Do the same for the Linker in the dedicated section:

  package Linker is
     for Driver use "arm-linux-gnueabihf-g++";

You may browse through the file and add possible compliler and linker flags, if needed.

Disable POHIC

Unless explicitely specified kazoo will generate code for the default PolyORB-HI-C (POHIC) runtime. Since the C++ runtime is not based on POHIC, we need to disable it in a few places:

c_pohi_gpr            # change the trigger.tmplt file
aadl_4_makefile       # in system.tmplt, edit the condition to filter the generation of the call to "ocarina -x"
pohic_wrapperS_body   # change the trigger.tmplt file
pohic_wrapperS_header # change the trigger.tmplt file

That's it, you can try your new C++-based runtime support!