Difference between revisions of "Kazoo"
(→New templates for kazoo) |
|||
(38 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | Kazoo is a part of TASTE | + | Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models. |
+ | == Overview == | ||
+ | |||
+ | Kazoo is a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system. | ||
+ | It uses [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser 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 | ||
+ | $ git pull | ||
+ | When command succeeds, kazoo needs to be rebuild to complete installation. | ||
+ | |||
+ | === Rebuilding from source === | ||
+ | |||
+ | To build and install kazoo from sources so run the following commands in the terminal: | ||
+ | $ cd ~/tool-src | ||
+ | $ ./install/87_kazoo.sh | ||
+ | |||
+ | == Using kazoo == | ||
+ | |||
+ | Kazoo is a command line tool, executed from terminal and configured by a list of parameters. | ||
+ | |||
+ | === Basic usage === | ||
+ | |||
+ | Kazoo is integrated in TASTE as one of the main tools for generating and building the code of the system under development. The calls to kazoo are normally hidden to the user and should rarely be done manually. To start a project using Kazoo, user normally run a single command: | ||
+ | |||
+ | $ taste | ||
+ | |||
+ | If user would like to use kazoo directly, or tweak it's behaviour, the following example Makefile presents the calls to kazoo that generate the code skeletons and glue. | ||
+ | |||
+ | <syntaxhighlight lang="Makefile"> | ||
+ | KAZOO?=kazoo | ||
+ | |||
+ | all: c | ||
+ | |||
+ | c: work/glue_built | ||
+ | $(MAKE) -C work | ||
+ | |||
+ | skeletons: InterfaceView.aadl DataView.aadl | ||
+ | $(KAZOO) --gw -o work | ||
+ | $(MAKE) -C work dataview | ||
+ | |||
+ | work/glue_built: InterfaceView.aadl DeploymentView.aadl DataView.aadl | ||
+ | $(KAZOO) -p --glue --gw -o work | ||
+ | touch work/glue_built | ||
+ | |||
+ | clean: | ||
+ | $(MAKE) -C work clean | ||
+ | |||
+ | .PHONY: clean skeletons c | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | 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 (''work''), <code>--gw</code> enables models and code skeletons generation, <code>--glue</code> enables glue code generation and <code>-p</code> or <code>--polyorb-hi-c</code> turns on use of [[PolyORB-HI-C]] runtime. | ||
+ | |||
+ | In the result directory '''work''' will be created and filled with generated models and source files. | ||
+ | |||
+ | To build the generated system run following commands in the terminal: | ||
+ | $ make | ||
+ | |||
+ | The output binary files will be located in the directory '''work/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 -j | ||
+ | |||
+ | === Kazoo help === | ||
+ | To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>. | ||
+ | |||
+ | === Input files === | ||
+ | Kazoo uses default TASTE AADL models as input: | ||
− | |||
* InterfaceView.aadl | * InterfaceView.aadl | ||
* DeploymentView.aadl | * DeploymentView.aadl | ||
− | * DataView.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 [[#Rebuilding from source|rebuild]] kazoo. | ||
+ | For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]]. | ||
+ | |||
+ | Templates locations: | ||
+ | * Code skeletons: <code>tool-src/kazoo/templates/skeletons</code> | ||
+ | * Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code> | ||
+ | * Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code> | ||
+ | |||
+ | |||
− | == | + | === Templates documentation === |
− | + | ||
− | The | + | The up to date list list of tags available for each template file is documented here: [[Kazoo Templates Documentation]] |
+ | |||
+ | == Code generation == | ||
+ | |||
+ | Kazoo uses provided AADL models to generate four major parts of the final system implementation: | ||
+ | * Makefiles/Project Files/ - to build the system incrementally, | ||
+ | * Code skeletons - actual implementation of functions and their provided interfaces, | ||
+ | * Glue code - the source code responsible for exchanging parameters and results between interfaces, via a middleware and operating system, | ||
+ | * 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 | * InterfaceView | ||
* DeploymentView | * DeploymentView | ||
* ConcurrencyView | * ConcurrencyView | ||
− | The InterfaceView | + | The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters. |
− | The InterfaceView | + | The InterfaceView contains also connections between provided interfaces and required interfaces. |
− | The InterfaceView | + | The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons|code skeletons]] and [[#Glue code|glue code]] generation algorithms. |
− | The DeploymentView | + | The DeploymentView consists of Nodes, Buses and connections between them. |
The Node contains Partitions, Processors and Drivers. | The Node contains Partitions, Processors and Drivers. | ||
The Partition contains a list of bounded functions. | The Partition contains a list of bounded functions. | ||
− | |||
The ConcurrencyView is generated from DeploymentView. | The ConcurrencyView is generated from DeploymentView. | ||
Line 31: | Line 133: | ||
Every Thread has a list of assigned functions from InterfaceView. | 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. | + | The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View|Concurrency View processing]]. |
+ | |||
+ | === Build script === | ||
+ | A build script named <code>build-script.sh</code> is generated from <code>build-script.tmplt</code> template file. | ||
+ | It is however kept only for legacy reasons and backward compatibility with the former build system named ''buildsupport''. Kazoo primarily generates a Makefile for automatic the build of TASTE systems and the default content of the build-script.sh file is to call the <code>make</code> command. | ||
+ | |||
+ | === Code skeletons === | ||
+ | For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|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: | ||
+ | <syntaxhighlight lang="Python"> | ||
+ | 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" | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | 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 <code><function name>/<language>/<src>/</code> scheme. | |
− | |||
− | |||
− | == | + | ==== Available code skeletons templates ==== |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>): | ||
+ | * 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 | + | === Glue code === |
− | [[Kazoo skeletons and glue templates| | + | For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|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: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | <syntaxhighlight lang="Python"> | ||
+ | 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) | ||
+ | </syntaxhighlight> | ||
− | == | + | ==== Available glue templates ==== |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table: | |
− | |||
− | |||
{| class="wikitable" | {| class="wikitable" | ||
− | ! | + | !Template name |
− | ! | + | !Generates |
|- | |- | ||
− | | | + | |invoke_ri-body |
− | | | + | |<code><function name>/<language>/<function name>_invoke_ri.c</code> |
|- | |- | ||
− | | | + | |mini-cv |
− | |. | + | |<code><function name>/<language>/<function name>_mini_cv.aadl</code> |
|- | |- | ||
− | | | + | |system_config |
− | |. | + | |<code><function name>/<language>/<function name>_system_config.h</code> |
|- | |- | ||
− | | | + | |vm_if-body |
− | |. | + | |<code><function name>/<language>/<function name>_vm_if.c</code> |
|- | |- | ||
− | | | + | |vm_if-header |
− | + | |<code><function name>/<language>/<function name>_vm_if.h</code> | |
− | |||
− | | | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
− | === | + | |
− | + | === Concurrency View === | |
− | + | For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files | |
− | + | according to the presented algorithm in pseudocode: | |
− | + | ||
− | + | <syntaxhighlight lang="Python"> | |
− | + | 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") | |
− | === templates | + | 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 | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | ==== Available Concurrency View templates ==== | ||
+ | |||
+ | Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table: | ||
{| class="wikitable" | {| class="wikitable" | ||
− | ! | + | !Template name |
− | ! | + | !Generates |
+ | !Processed | ||
|- | |- | ||
− | | | + | |aadl_2_threads |
− | | | + | |<code>build/system.aadl</code> (the actual Concurrency View) |
+ | |Always (Used later by [[Ocarina]] to create middleware source code from the Concurrency View) | ||
|- | |- | ||
− | | | + | |aadl_3_main |
− | | | + | |<code>build/main.aadl</code> (AADL project entry point) |
+ | |Always (Used later by [[Ocarina]] to process the Concurrency View) | ||
|- | |- | ||
− | | | + | |aadl_4_makefile |
− | | | + | |<code>build/Makefile.taste</code> |
+ | |Always | ||
|- | |- | ||
− | | | + | |ada_pohi_gpr |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
| | | | ||
+ | * for every node: <code>Makefike.<node name></code> | ||
+ | * for every partition: <code><partition name>.gpr</code> | ||
+ | |Only when [[PolyORB-HI-Ada]] middleware should be used (default) | ||
|- | |- | ||
− | | | + | |ada_wrappers_body |
− | | | + | |for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code> |
+ | |Only when [[PolyORB-HI-Ada]] middleware should be used (default) | ||
|- | |- | ||
− | | | + | |ada_wrappers_source |
− | | | + | |for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code> |
+ | |Only when [[PolyORB-HI-Ada]] middleware should be used (default) | ||
|- | |- | ||
− | | | + | |air_cgpr |
− | | | + | |for every partition: <code>build/<node name>/air.cgpr</code> (Cross-compiler configuration for the TSP/AIR hypervisor) |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |air_gpr |
− | | | + | |for every partition: <code>build/<node name>/_air.gpr</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |air_makefile |
− | | | + | |<code>build/Makefile.air</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |air_port_polling |
− | | | + | |for every partition: <code>build/<node name>/<partition name>/air_polling.c</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |c_pohi_gpr |
| | | | ||
+ | * for every node: <code>build/<node name>/Makefile.<node name></code> | ||
+ | * for every partition <code>build/<node name>/<partition name>.gpr</code> | ||
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |c_pohi_rtems_with_ada_cgpr |
− | | | + | |for every partition: <code>build/<node name>/rtems_ada.cgpr</code> |
− | + | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |- | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
− | | | + | |c_pohi_rtems_with_ada_gpr |
− | | | + | |for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |drivers_config |
− | | | + | |<code>build/drivers_config.asn</code> |
+ | |Always | ||
|- | |- | ||
− | | | + | |pohic_makefile_workaround |
− | | | + | |for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |pohic_wrappers_body |
− | | | + | |for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|- | |- | ||
− | | | + | |pohic_wrappers_header |
− | | | + | |for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code> |
+ | |Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option). | ||
|} | |} |
Latest revision as of 09:55, 17 April 2020
Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.
Contents
Overview
Kazoo is a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system. It uses 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 $ git pull
When command succeeds, kazoo needs to be rebuild to complete installation.
Rebuilding from source
To build and install kazoo from sources so run the following commands in the terminal:
$ cd ~/tool-src $ ./install/87_kazoo.sh
Using kazoo
Kazoo is a command line tool, executed from terminal and configured by a list of parameters.
Basic usage
Kazoo is integrated in TASTE as one of the main tools for generating and building the code of the system under development. The calls to kazoo are normally hidden to the user and should rarely be done manually. To start a project using Kazoo, user normally run a single command:
$ taste
If user would like to use kazoo directly, or tweak it's behaviour, the following example Makefile presents the calls to kazoo that generate the code skeletons and glue.
KAZOO?=kazoo
all: c
c: work/glue_built
$(MAKE) -C work
skeletons: InterfaceView.aadl DataView.aadl
$(KAZOO) --gw -o work
$(MAKE) -C work dataview
work/glue_built: InterfaceView.aadl DeploymentView.aadl DataView.aadl
$(KAZOO) -p --glue --gw -o work
touch work/glue_built
clean:
$(MAKE) -C work clean
.PHONY: clean skeletons 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 (work), --gw
enables models and code skeletons generation, --glue
enables glue code generation and -p
or --polyorb-hi-c
turns on use of PolyORB-HI-C runtime.
In the result directory work will be created and filled with generated models and source files.
To build the generated system run following commands in the terminal:
$ make
The output binary files will be located in the directory work/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 -j
Kazoo help
To obtain complete list of kazoo parameters and options type kazoo --help
.
Input files
Kazoo uses 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
Templates documentation
The up to date list list of tags available for each template file is documented here: Kazoo Templates Documentation
Code generation
Kazoo uses provided AADL models to generate four major parts of the final system implementation:
- Makefiles/Project Files/ - to build the system incrementally,
- Code skeletons - actual implementation of functions and their provided interfaces,
- Glue code - the source code responsible for exchanging parameters and results between interfaces, via a middleware and operating system,
- 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 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 processing.
Build script
A build script named build-script.sh
is generated from build-script.tmplt
template file.
It is however kept only for legacy reasons and backward compatibility with the former build system named buildsupport. Kazoo primarily generates a Makefile for automatic the build of TASTE systems and the default content of the build-script.sh file is to call the make
command.
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.aadl
|
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 (the actual Concurrency View)
|
Always (Used later by Ocarina to create middleware source code from the Concurrency View) |
aadl_3_main | build/main.aadl (AADL project entry point)
|
Always (Used later by Ocarina to process the Concurrency View) |
aadl_4_makefile | build/Makefile.taste
|
Always |
ada_pohi_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 (Cross-compiler configuration for the TSP/AIR hypervisor)
|
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 |
|
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).
|