Difference between revisions of "Kazoo"

From TASTE
Jump to: navigation, search
(Adding new platform to TASTE using Kazoo)
Line 70: Line 70:
 
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code>
 
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code>
 
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code>
 
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code>
 
== Adding new platform to TASTE using Kazoo ==
 
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].
 
  
 
== Code generation ==
 
== Code generation ==

Revision as of 15:38, 13 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 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 ~/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 (+ .asn/.acn models)

New templates for kazoo

To create new set of templates to be used by kazoo copy existing template subdirectory. For example to create new Concurrency View template, execute the following commands:

$ cd ~/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.

Templates locations:

  • Code skeletons: tool-src/kazoo/templates/skeletons
  • Glue code: tool-src/kazoo/templates/glue/language_wrappers
  • Concurrency View: tool-src/kazoo/templates/concurrency_view

Code generation

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

  • Build script - script responsible for final step of code generation and compilation,
  • Code skeletons - actual implementation of functions and their provided interfaces,
  • Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,
  • Concurrency View - the system.aadl and main.aadl files, which will be later used by Ocarina to generate code during build script execution.

Code is generated using input AADL models, parsed by Ocarina.

The system representation consists of three major structures:

  • InterfaceView
  • DeploymentView
  • ConcurrencyView

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

The DeploymentView consists 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 the rest of glue code and also middleware integration. See #Concurrency View.

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

For each function defined in Interface View Kazoo will process each skeleton template (each containing multiple template files). From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs). This processing algorithm is presented in more detail in the pseudocode below:

for function in InterfaceView:
    for skeleton_template_subdirectory in skeleton_directory:
        makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")
        function_filename = evaluate_optional_template_file("function-filename.tmplt")
        if evaluate_template_file("trigger.tmplt") is "TRUE":
            for interface in function.required_interfaces:
                evaluate_template_file("interface.tmplt")
            for interface in function.provided_interfaces:
                evaluate_template_file("interface.tmplt")
            if makefile_filename is not empty:
                evaluate_template_file("makefile.tmplt") and save as makefile_filename
            evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)
    if context_parameters in function:
        evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"

The skeletons templates are responsible for creating code skeletons, which are a placeholders for actual implementation of the functions, provided by the user.

Kazoo uses code skeletons to generate files in folder created according to <function name>/<language>/<src>/ scheme.

Available code skeletons templates

Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of tool-src/kazoo/templates/skeletons):

  • ada-body
  • ada-source
  • blackbox-c-body
  • blackbox-c-header
  • c-body
  • c-header
  • cpp-body
  • cpp-body-instance
  • cpp-body-type
  • cpp-context
  • cpp-header
  • cpp-header-instance
  • cpp-header-type
  • gui-body
  • gui-enum-defs
  • gui-header
  • gui-runtime-body
  • gui-runtime-debug-body
  • gui-runtime-debug-header
  • gui-runtime-header
  • opengeode-process-body
  • opengeode-structure
  • pragmadev_process_rdd
  • pragmadev_process_rdp
  • pragmadev_scheduled
  • pragmadev_sys_process_rdd
  • simulink
  • timer-manager-body
  • timer-manager-header
  • vdm-body
  • vdm-header

Glue code

For each function defined in Interface View Kazoo will process each glue template (each containing multiple template files). From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs). This processing algorithm is presented in more detail in the pseudocode below:

for function in InterfaceView:
    for glue_template_subdirectory in glue_directory:
        makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")
        function_filename = evaluate_optional_template_file("function-filename.tmplt")
        if evaluate_template_file("trigger.tmplt") is "TRUE":
            for interface in function.required_interfaces:
                evaluate_template_file("interface.tmplt")
            for interface in function.provided_interfaces:
                evaluate_template_file("interface.tmplt")
            if makefile_filename is not empty:
                evaluate_template_file("makefile.tmplt") and save as makefile_filename
            evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)

Available glue templates

Currently kazoo provides the glue code templates (each stored in separate subdirectory of tool-src/kazoo/templates/glue) listed in table:

Template name Generates
invoke_ri-body <function name>/<language>/<function name>_invoke_ri.c
mini-cv <function name>/<language>/<function name>_mini_cv.c
system_config <function name>/<language>/<function name>_system_config.h
vm_if-body <function name>/<language>/<function name>_vm_if.c
vm_if-header <function name>/<language>/<function name>_vm_if.h


Concurrency View

For each Concurrency View template kazoo processes each node of the view and creates set of files according to the presented algorithm in pseudocode:

for template_subdirectory in concurrency_view_directory:
    all_nodes = ""
    filesys = evaluate_template_file("filesys.tmplt")
    for node in ConcurrencyView:
        filenode = evaluate_optional_template_file("filenode.tmplt")
        if evaluate_template_file("trigger.tmplt") is "TRUE":
            for partition in node.partitions:
                filepart = evaluate_optional_template_file("filepart.tmplt")
                for thread in partition.threads:
                    filethread = evaluate_optional_template_file("filethread.tmplt")
                    evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)
                for block in partition.blocks:
                    fileblock = evaluate_optional_template_file("fileblock.tmplt")
                    for block.protected_interfaces:
                        evaluate_template_file("pi.tmplt")
                    for block.unprotected_interfaces:
                        evaluate_template_file("pi.tmplt")
                    for block.required_interfaces:
                        evaluate_template_file("ri.tmplt")
                    evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)
                partition_content = evaluate_template_file("partition.tmplt")
                if filepart is not empty:
                    save partition_content as filepart
        node_content = evaluate_template_file("node.tmplt")
        if filenode is not empty:
            save node_content as filenode
        all_nodes += node_content
    if filesys is not empty and all_nodes is not empty:
        evaluate_optional_template_file("system.tmplt") and save as filesys

Available Concurrency View templates

Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of tool-src/kazoo/templates/concurrency_view) listed in table:

Template name Generates Processed
aadl_2_threads build/system.aadl Always (Used later by Ocarina to create source code of Concurrency View)
aadl_3_main build/main.aadl Always (Used later by Ocarina to create source code of Concurrency View)
aadl_4_makefile build/Makefile.taste Always
ada_pohi_gpr
  • for every node: Makefike.<node name>
  • for every partition: <partition name>.gpr
Only when PolyORB-HI-Ada middleware should be used (default)
ada_wrappers_body for every partition: build/<partition name>/<partition name>_taste_interface.adb Only when PolyORB-HI-Ada middleware should be used (default)
ada_wrappers_source for every partition: build/<partition name>/<partition name>_taste_interface.ads Only when PolyORB-HI-Ada middleware should be used (default)
air_cgpr for every partition: build/<node name>/air.cgpr Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
air_gpr for every partition: build/<node name>/_air.gpr Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
air_makefile build/Makefile.air Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
air_port_polling for every partition: build/<node name>/<partition name>/air_polling.c Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
c_pohi_gpr
  • for every node: build/<node name>/Makefile.<node name>
  • for every partition build/<node name>/<partition name>.gpr
Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
c_pohi_rtems_with_ada_cgpr for every partition: build/<node name>/rtems_ada.cgpr Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
c_pohi_rtems_with_ada_gpr for every partition: build/<node name>/<partition name>_rtems_ada.gpr Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
drivers_config build/drivers_config.asn Always
pohic_makefile_workaround for every partition: build/<node name>/gather_<partition name>_filelist.sh Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
pohic_wrappers_body for every partition: build/<node name>/<partition name>_polyorb_interface.c Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).
pohic_wrappers_header for every partition: build/<node name>/<partition name>_polyorb_interface.h Only when PolyORB-HI-C middleware should be used (--polyorb-hi-c option).