Difference between revisions of "Kazoo"

From TASTE
Jump to: navigation, search
Line 1: Line 1:
 
Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.
 
Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.
  
= Overview =
+
== Overview ==
  
 
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.
 
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.
Line 8: Line 8:
 
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.
 
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.
  
= Installation and updating =
+
== Installation and updating ==
  
 +
=== Updating sources ===
 
To update kazoo run the following commands in the terminal:
 
To update kazoo run the following commands in the terminal:
 
  <nowiki>$ cd ~/tool-src/kazoo
 
  <nowiki>$ cd ~/tool-src/kazoo
Line 15: Line 16:
 
When command succeeds, kazoo needs to be rebuild to complete installation.
 
When command succeeds, kazoo needs to be rebuild to complete installation.
  
To do so run the following commands in the terminal:
+
=== Rebuilding from source ===
 +
 
 +
To build kazoo from sources so run the following commands in the terminal:
 
  <nowiki>$ cd ~/tool-src/kazoo
 
  <nowiki>$ cd ~/tool-src/kazoo
 
$ make install</nowiki>
 
$ make install</nowiki>
  
= Using kazoo =
+
== Using kazoo ==
  
 
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.
 
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.
  
== Basic usage ==
+
=== Basic usage ===
  
 
Run the following commands in the terminal.
 
Run the following commands in the terminal.
 
  <nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki>
 
  <nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki>
Kazoo will read the default [[#Input files for kazoo|input AADL models]] and generate code to the selected output directory.
+
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.
 
Parameter <code>--output</code> chooses the output directory for generated files (''out''), <code>--gw</code> enables models and code skeletons generation, <code>--glue</code> enables glue code generation and <code>--polyorb-hi-c</code> turns on use of [[PolyORB-HI-C]] runtime.
 
Parameter <code>--output</code> chooses the output directory for generated files (''out''), <code>--gw</code> enables models and code skeletons generation, <code>--glue</code> enables glue code generation and <code>--polyorb-hi-c</code> turns on use of [[PolyORB-HI-C]] runtime.
  
Line 37: Line 40:
 
The output binary files will be located in the directory '''out/binaries'''.
 
The output binary files will be located in the directory '''out/binaries'''.
  
== Kazoo example ==
+
=== Kazoo example ===
 
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.
 
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.
 
Every example project contains Makefile, which simplifies the process of the build.
 
Every example project contains Makefile, which simplifies the process of the build.
Line 44: Line 47:
 
$ make</nowiki>
 
$ make</nowiki>
  
== Input files for kazoo ==
+
=== Kazoo help ===
 +
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.
 +
 
 +
=== Input files ===
 +
Kazoo used default TASTE AADL models as input:
 +
 
 
* InterfaceView.aadl
 
* InterfaceView.aadl
 
* DeploymentView.aadl
 
* DeploymentView.aadl
* DataView.aadl
+
* DataView.aadl<br/>Derived files:
* DataView.asn
+
** DataView.asn
* DataView.acn
+
** DataView.acn
  
== Internal representation of system within kazoo ==
+
== New templates for kazoo ==
Taste uses Ocarina library to parse input aadl files.
+
To create new set of templates to be used by kazoo copy existing template subdirectory:
The internal representation of system consists of thre major structures:
+
<nowiki>$ cd /home/taste/tool-src/kazoo/templates/concurrency_view
* InterfaceView
+
$ cp -r aadl_2_threads <new subdirectory></nowiki>
* DeploymentView
 
* ConcurrencyView
 
  
The InterfaceView representation contains of list of functions. Every function contains provided interfaces and required interfaces. Optionally a function may contain context parameters.
+
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.
The InterfaceView representation contains also connections between provided interfaces and required interfaces.
+
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].
The InterfaceView representation is used to create skeletons and glue code. See [[Kazoo#Code skeletons generation|Code skeletons generation]] and [[Kazoo#Glue code generation|Glue code generation]].
 
  
The DeploymentView constists of Nodes, Buses and connections between them.
+
== Code generation ==
The Node contains Partitions, Processors and Drivers.
 
The Partition contains a list of bounded functions.
 
The DeploymentView is not directly used for code generation.
 
  
The ConcurrencyView is generated from DeploymentView.
+
Kazoo uses provided models to generate three major parts of the final system implementation:
The ConcurrencyView consists of list of Nodes.
+
* Code skeletons <!-- TODO: Some notes describing each of the parts? -->
Every Node consists of list of Partitions and list of Drivers.
+
* Glue code <!-- TODO -->
Every Partition consists of list of Threads.
+
* Build script - script responsible for final step of code generation and compilation.
Every Thread has a list of assigned functions from InterfaceView.
 
  
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].
+
=== Build script ===
 +
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.
 +
The template files: <code>build-script-gen.tmplt</code>, <code>build-script-func.tmplt</code> and <code>build-script-zip.tmplt</code> are evaluated earlier, and their output is passed to main template as parameters.
  
== build-script.sh generation ==
+
=== Code skeletons ===
The file build-script.sh is generated from build-script.tmplt.
+
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the following algorithm presented in pseudocode:
The template files: build-script-gen.tmplt, build-script-func.tmplt and build-script-zip.tmplt are evaluated earlier, and the output is passed to main template as parameters.
+
  <nowiki>for every function from InterfaceView:
 
 
== Code skeletons generation ==
 
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the presented algorithm in pseudocode:
 
  <nowiki>
 
for every function from InterfaceView:
 
 
     for every subdirectory
 
     for every subdirectory
 
         evaluate template trigger.tmplt
 
         evaluate template trigger.tmplt
Line 93: Line 91:
 
             evaluate template function.tmplt and optionally save output to file
 
             evaluate template function.tmplt and optionally save output to file
 
     if function has context parameters then
 
     if function has context parameters then
         evaluate template context_parameters.tmplt and save the output to file
+
         evaluate template context_parameters.tmplt and save the output to file</nowiki>
</nowiki>
 
  
== Glue code generation ==
+
=== Glue code ===
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the presented algorithm in pseudocode:
+
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the following algorithm presented in pseudocode:
Algorithm in pseudocode:
+
  <nowiki>for every function from InterfaceView:
  <nowiki>
 
for every function from InterfaceView:
 
 
     for every subdirectory
 
     for every subdirectory
 
         evaluate template trigger.tmplt
 
         evaluate template trigger.tmplt
Line 109: Line 104:
 
             evaluate template interface.tmplt for provided interfaces of function
 
             evaluate template interface.tmplt for provided interfaces of function
 
             evaluate template makefile.tmplt and optionally save output to file
 
             evaluate template makefile.tmplt and optionally save output to file
             evaluate template function.tmplt and optionally save output to file
+
             evaluate template function.tmplt and optionally save output to file</nowiki>
</nowiki>
 
  
=== Existing Glue templates ===
+
==== Existing Glue templates ====
  
==== invoke_ri-body ====
+
===== invoke_ri-body =====
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''
  
==== mini-cv ====
+
===== mini-cv =====
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''
  
==== system_config ====
+
===== system_config =====
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''
  
==== vm_if-body ====
+
===== vm_if-body =====
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''
  
==== vm_if-header ====
+
===== vm_if-header =====
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''
 
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''
  
Line 227: Line 221:
  
  
== How to create new template for kazoo ==
+
== Under the hood ==
Copy existing template subdirectory:
+
Kazoo uses Ocarina library to parse input AADL models.
<nowiki>
+
The internal representation of system consists of three major structures:
$ cd /home/taste/tool-src/kazoo/templates/concurrency_view
+
* InterfaceView
$ cp -r aadl_2_threads <new subdirectory>
+
* DeploymentView
</nowiki>
+
* ConcurrencyView
After editing new templates kazoo needs to be [[#How to build kazoo|rebuild]].
+
 
 +
The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.
 +
The InterfaceView representation contains also connections between provided interfaces and required interfaces.
 +
The InterfaceView representation is used to create skeletons and glue code. See [[Kazoo#Code skeletons generation|Code skeletons generation]] and [[Kazoo#Glue code generation|Glue code generation]].
 +
 
 +
The DeploymentView constists of Nodes, Buses and connections between them.
 +
The Node contains Partitions, Processors and Drivers.
 +
The Partition contains a list of bounded functions.
 +
The DeploymentView is not directly used for code generation.
 +
 
 +
The ConcurrencyView is generated from DeploymentView.
 +
The ConcurrencyView consists of list of Nodes.
 +
Every Node consists of list of Partitions and list of Drivers.
 +
Every Partition consists of list of Threads.
 +
Every Thread has a list of assigned functions from InterfaceView.
 +
 
 +
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].

Revision as of 13:58, 12 December 2019

Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.

Overview

Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system. It facilitates Ocarina for AADL parsing and templates-parser for templates processing and files generation. Standard library of components used by templates is defined by TASTE common models from ocarina_components.aadl file, which includes supported processors, devices, drivers etc. Generated build scripts apart from calling code compilers also run other tools like ocarina and aadl2glueC to create rest of the source code.

Installation and updating

Updating sources

To update kazoo run the following commands in the terminal:

$ cd ~/tool-src/kazoo
$ git checkout master

When command succeeds, kazoo needs to be rebuild to complete installation.

Rebuilding from source

To build kazoo from sources so run the following commands in the terminal:

$ cd ~/tool-src/kazoo
$ make install

Using kazoo

Kazoo is a command line tool, executed from terminal and configured by a list o parameters.

Basic usage

Run the following commands in the terminal.

$ kazoo --output=out --gw --glue --polyorb-hi-c

Kazoo will read the default input AADL models and generate code to the selected output directory. Parameter --output chooses the output directory for generated files (out), --gw enables models and code skeletons generation, --glue enables glue code generation and --polyorb-hi-c turns on use of PolyORB-HI-C runtime.

In the result directory out will be created and filled with generated models and source files.

To build the generated system run following commands in the terminal:

$ cd out
$ make

The output binary files will be located in the directory out/binaries.

Kazoo example

Kazoo comes with a lot of helpful examples.The examples are located in the directory /home/taste/tool-src/kazoo/test/. Every example project contains Makefile, which simplifies the process of the build. For an example, to build project Demo_C run following commands in the terminal:

$ cd /home/taste/tool-src/kazoo/test/Demo_C
$ make

Kazoo help

To obtain complete list of kazoo parameters and options type kazoo --help.

Input files

Kazoo used default TASTE AADL models as input:

  • InterfaceView.aadl
  • DeploymentView.aadl
  • DataView.aadl
    Derived files:
    • DataView.asn
    • DataView.acn

New templates for kazoo

To create new set of templates to be used by kazoo copy existing template subdirectory:

$ cd /home/taste/tool-src/kazoo/templates/concurrency_view
$ cp -r aadl_2_threads <new subdirectory>

Edit newly created templates and rebuild kazoo. For more details see note about adding new target to TASTE.

Code generation

Kazoo uses provided models to generate three major parts of the final system implementation:

  • Code skeletons
  • Glue code
  • Build script - script responsible for final step of code generation and compilation.

Build script

Build script is a single file named build-script.sh which is generated from build-script.tmplt template file. The template files: build-script-gen.tmplt, build-script-func.tmplt and build-script-zip.tmplt are evaluated earlier, and their output is passed to main template as parameters.

Code skeletons

Kazoo skeletons templates are processed according to the following algorithm presented in pseudocode:

for every function from InterfaceView:
    for every subdirectory
        evaluate template trigger.tmplt
        if result is equal to “TRUE” then
            evaluate template function-filename.tmplt if exists
            evaluate template makefile-filename.tmplt if exists
            evaluate template interface.tmplt for required interfaces of function
            evaluate template interface.tmplt for provided interfaces of function
            evaluate template makefile.tmplt and optionally save output to file
            evaluate template function.tmplt and optionally save output to file
    if function has context parameters then
        evaluate template context_parameters.tmplt and save the output to file

Glue code

Kazoo glue templates are processed according to the following algorithm presented in pseudocode:

for every function from InterfaceView:
    for every subdirectory
        evaluate template trigger.tmplt
        if result is equal to “TRUE” then
            evaluate template function-filename.tmplt if exists
            evaluate template makefile-filename.tmplt if exists
            evaluate template interface.tmplt for required interfaces of function
            evaluate template interface.tmplt for provided interfaces of function
            evaluate template makefile.tmplt and optionally save output to file
            evaluate template function.tmplt and optionally save output to file

Existing Glue templates

invoke_ri-body

This subdirectory creates files with name build/<function name>/<language>/<function name>_invoke_ri.c

mini-cv

This subdirectory creates files with name build/<function name>/<language>/<function name>_mini_cv.c

system_config

This subdirectory creates files with name build/<function name>/<language>/<function name>_system_config.h

vm_if-body

This subdirectory creates files with name build/<function name>/<language>/<function name>_vm_if.c

vm_if-header

This subdirectory creates files with name build/<function name>/<language>/<function name>_vm_if.h

Concurrency View generation

Kazoo concurrency view templates are processed according to the presented algorithm in pseudocode:

for every subdirectory
    for every node from ConcurrencyView
        evaluate template filesys.tmplt
        evaluate template filenode.tmplt
        evaluate template trigger.tmplt
        if result is equal to “TRUE” then
            for every partition from node:
                evaluate template filepart.tmplt
                evaluate template thread.tmplt and optionally save output to the file
                evaluate template filethread.tmplt
                evaluate template fileblock.tmplt
                evaluate template pi.tmplt
                evaluate template pi.tmplt (with other parameters)
                evaluate template ri.tmplt
                evaluate template block.tmplt and optionally save output to file
                evaluate template partition.tmplt and optionally save output to file
        evaluate template node.tmplt and optionally save output to file
    evaluate template system.tmplt and optionally save output to file

Existing Concurrency View subdirectories

aadl_2_threads

This subdirectory creates file build/system.aadl, which is used by ocarina to create source code of Concurrency View. This subdirectory is processed always.

aadl_3_main

This subdirectory creates file build/main.aadl, which is used by ocarina to create source code of Concurrency View. This subdirectory is processed always.

aadl_4_makefile

This subdirectory creates file build/Makefile.taste. This subdirectory is processed always.

ada_pohi_gpr

This subdirectory creates following files:

  • for every node file with name Makefike.<node name>
  • for every partition file with name <partition name>.gpr

This subdirectory is processed when option -p or --polyorb-hi-c was not used.

ada_wrappers_body

This subdirectory creates files with name build/<partition name>/<partition name>_taste_interface.adb for every partition This subdirectory is processed when option -p or --polyorb-hi-c was not used.

ada_wrappers_source

This subdirectory creates files with name build/<partition name>/<partition name>_taste_interface.ads For every partition. This subdirectory is processed when option -p or --polyorb-hi-c was not used.

air_cgpr

This subdirectory creates files with name build/<node name>/air.cgpr for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

air_gpr

This subdirectory creates files with name build/<node name>/<parition name>_air.gpr for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

air_makefile

This subdirectory creates file build/Makefile.air. This subdirectory is processed when option -p or --polyorb-hi-c was used.

air_port_polling

This subdirectory creates files with name build/<node name>/<partition name>/air_polling.c for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

c_pohi_gpr

This subdirectory creates following files:

  • For every node build/<node name>/Makefile.<node name>
  • For every partition build/<node name>/<partition name>.gpr

This subdirectory is processed when option -p or --polyorb-hi-c was used.

c_pohi_rtems_with_ada_cgpr

This subdirectory creates files with name build/<node name>/rtems_ada.cgpr for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

c_pohi_rtems_with_ada_gpr

This subdirectory creates files with name build/<node name>/<partition name>_rtems_ada.gpr for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

drivers_config

This subdirectory creates file build/drivers_config.asn. This subdirectory is processed always.

pohic_makefile_workaround

This subdirectory creates files with name build/<node name>/gather_<partition name>_filelist.sh for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

pohic_wrappers_body

This subdirectory creates files with name build/<node name>/<partition name>/<partition name>_polyorb_interface.c for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.

pohic_wrappers_header

This subdirectory creates files with name build/<node name>/<partition name>/<partition name>_polyorb_interface.h for every partition. This subdirectory is processed when option -p or --polyorb-hi-c was used.


Under the hood

Kazoo uses Ocarina library to parse input AADL models. The internal representation of system consists of three major structures:

  • InterfaceView
  • DeploymentView
  • ConcurrencyView

The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters. The InterfaceView representation contains also connections between provided interfaces and required interfaces. The InterfaceView representation is used to create skeletons and glue code. See Code skeletons generation and Glue code generation.

The DeploymentView constists of Nodes, Buses and connections between them. The Node contains Partitions, Processors and Drivers. The Partition contains a list of bounded functions. The DeploymentView is not directly used for code generation.

The ConcurrencyView is generated from DeploymentView. The ConcurrencyView consists of list of Nodes. Every Node consists of list of Partitions and list of Drivers. Every Partition consists of list of Threads. Every Thread has a list of assigned functions from InterfaceView.

The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See Concurrency View generation.