https://taste.tuxfamily.org/wiki/api.php?action=feedcontributions&user=Kgrochowski&feedformat=atomTASTE - User contributions [en]2024-03-28T20:00:13ZUser contributionsMediaWiki 1.29.0https://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=789Technical topic: TASTE on MSP430 with FreeRTOS2020-11-19T13:49:13Z<p>Kgrochowski: /* Hardware Description */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation and middleware use is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also a compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on GitHub with this port was submitted.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>. It implies <code>-mcode-region=lower -mdata-region=lower</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also, the total size of Telemetry should be bigger than total size of Telecommand. Otherwise, the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artefacts, a custom stub msp430-elf-adabind utility is provided.<br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=787Technical topic: TASTE on MSP430 with FreeRTOS2020-11-19T10:02:29Z<p>Kgrochowski: /* Implementation */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on Github with this port was submitted.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>. It implies <code>-mcode-region=lower -mdata-region=lower</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artefacts, a custom stub msp430-elf-adabind utility is provided.<br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=786Technical topic: TASTE on MSP430 with FreeRTOS2020-11-18T10:16:14Z<p>Kgrochowski: /* FreeRTOS port for MSP430FR5969 */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on Github with this port was submitted.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>. It implies <code>-mcode-region=lower -mdata-region=lower</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=785Technical topic: TASTE on MSP430 with FreeRTOS2020-11-18T10:12:29Z<p>Kgrochowski: /* FreeRTOS port for MSP430FR5969 */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on Github with this port was submitted.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=784Technical topic: TASTE on MSP430 with FreeRTOS2020-11-18T10:01:40Z<p>Kgrochowski: /* FreeRTOS port for MSP430FR5969 */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on Github with this port was submitted.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=783Technical topic: TASTE on MSP430 with FreeRTOS2020-11-18T10:01:04Z<p>Kgrochowski: /* FreeRTOS port for MSP430FR5969 */</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel FreeRTOS-kernel] repository on Github with this port was submited.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=782Technical topic: TASTE on MSP430 with FreeRTOS2020-11-17T16:51:27Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addresses: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel | FreeRTOS-kernel] repository on Github with this port was submited.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=781Technical topic: TASTE on MSP430 with FreeRTOS2020-11-17T16:50:34Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
Since the <code>msp430-elf-ld</code> does not allow to set the stack size the bash script presented below checks this memory constraint on compiled executable.<br />
<syntaxhighlight lang="bash"><br />
#!/bin/bash<br />
<br />
if [ -z $1 ]<br />
then<br />
echo "No executable specified."<br />
echo "Usage:"<br />
echo " check_stack.sh <elf file>"<br />
exit 1<br />
fi<br />
<br />
stack_ptr=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__stack' | cut -d ' ' -f1)<br />
heap_limit=$(msp430-elf-nm -n -S --special-syms --synthetic $1 | grep '__HeapLimit' | cut -d ' ' -f1)<br />
<br />
printf "Stack addrres: 0x%s\n" $stack_ptr<br />
printf "Heap limit: 0x%s\n" $heap_limit<br />
<br />
available_stack_memory=$((16#$stack_ptr - 16#$heap_limit))<br />
<br />
printf "Available memory for stack: %d bytes \n" $available_stack_memory<br />
</syntaxhighlight><br />
<br />
Possible usage:<br />
<syntaxhighlight><br />
$ bash check_stack.sh work/binaries/msp430fr5969_partition <br />
Stack addrres: 0x00002400<br />
Heap limit: 0x00001c06<br />
Available memory for stack: 2042 bytes <br />
</syntaxhighlight><br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The TASTE runtime for MSP430 requires the FreeRTOS port for GCC (msp430-elf-gcc) and the architecture MSP430X.<br />
The suitable port was prepared as a part of this project by N7Space team.<br />
Currently this port is installed by <code>taste-setup</code> as a patch to the FreeRTOS, but Pull Request to [https://github.com/FreeRTOS/FreeRTOS-Kernel | FreeRTOS-kernel] repository on Github with this port was submited.<br />
<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated Task Control Block structure (TCB) and actual stack buffers (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.<br />
<br />
== Ada support ==<br />
<br />
=== Implementation ===<br />
<br />
Ada in TASTE can be used as: <br />
* a function implementation language, <br />
* SDL generation target language, <br />
* a device driver implementation language. <br />
<br />
Providing Ada support in TASTE requires integration of an Ada compiler for the target platform within the TASTE environment. Several candidates were considered (the presented status is as of the beginning of 2020):<br />
* Texas Instruments GCC for MSP430 - does not support Ada, <br />
* AdaCore GNAT Community Edition - does not support MSP430, <br />
* GNU GCC available in Debian repositories - is out of date and contains bugs affecting MSP430FRXXX chips. <br />
<br />
Proprietary compilers were not considered, as their licensing may put constraints on distribution and usage within TASTE. <br />
<br />
In order to enable Ada support on the MSP430FR5969 chip, a new Ada compilation toolchain was assembled – [https://github.com/n7space/adac-hybrid-msp430 adac-hybrid-msp430]. It works by combining [https://github.com/AdaCore/gnat-llvm AdaCore GNAT LLVM project], the [https://llvm.org/ LLVM project] and [https://www.ti.com/tool/MSP430-GCC-OPENSOURCE Texas Instruments GCC] (TI GCC). The compilation process is as follows: <br />
* Ada files are compiled into LLVM Intermediate Representation (encoded as BitCode) using GNAT LLVM, <br />
* the BitCode is translated into MSP430 assembly using LLC utility of the LLVM project <br />
* the generated assembly is postprocessed, <br />
* the processed assembly is compiled using TI GCC. <br />
<br />
The use of TI GCC allows to use the compiler with all MSP430 family chips. The modular architecture of the toolchain offers the possibility to swap its parts e.g. to support different MCU architectures (by changing LLC generation target and replacing TI GCC with an MCU specific last stage compiler). <br />
<br />
The introduced assembly postprocessing is responsible for finding all Ada elaboration functions and putting them into .init_array section. This way the elaboration functions are handled exactly as C constructors/initializers, allowing seamless integration with C code - adac-hybrid-msp430 can be used exactly as GCC, without the need for an Ada binder, simply using standard GCC linker scripts. <br />
<br />
The LLVM IR generated from Ada files relies on the presence of several Ada-specific library functions – the GNAT runtime. Similarly, the MSP430 assembly generated by LLC relies on several LLVM-specific library functions. These are provided by '''libgnatmsp430''' and '''libllvmmsp430''' respectively. <br />
<br />
'''Libgnatmsp430''' is derived from libgnat sourced from GCC with additions from [https://sourceforge.net/p/msp430ada/wiki/Home/ MSP430-Ada] project (mainly system configuration). It provides several functions related to e.g. bound checking, math operations, as well as pointer sizes and basic types. <br />
<br />
'''Libllvmmsp430''' is derived from llvm-runtime and focuses on emulating several high-level operations absent from the MSP430 Instruction Set Architecture (ISA). However, as the linking process is done by TI GCC, most of the required functions are provided by gcc-runtime. Therefore, libllvmmsp430 provides just the missing ones. <br />
<br />
Both '''libgnatmsp430''' and '''libllvmmsp430''' are precompiled for MSP430 and MSP430X ISAs and tested with MSP430FR5969 and emulated MSP430G2553. <br />
<br />
[https://github.com/n7space/adac-hybrid-msp430 Adac-hybrid-msp430] is designed so that it can be used together with TI GCC and in similar fashion to TI GCC, with any build system – its repository contains multiple tests, which demonstrate both Ada standalone compilation, as well as C to Ada and Ada to C interop, all using simple Makefiles. However, many Ada based projects, as well as TASTE, rely on gprbuild build system, which assumes the presence of an Ada binder. As the assembly postprocessing handles the elaboration handling, the work normally performed by the binder is not needed. However, in order to provide gprbuild with the required intermediate artifacts, a custom stub msp430-elf-adabind utility is provided. <br />
<br />
=== Usage ===<br />
<br />
Please refer to adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README]. <br />
<br />
=== Known limitations ===<br />
<br />
The MSP430 specific assembly is generated by LLC, which (for version 9.0.49 of LLVM used within the project) does not support MSP430 large memory model. This limits the available address space to 64 kB, which in turns restricts the available memory to a maximum of 48 kB, as part of the address space is reserved for peripherals. If large memory support is added to LLC in the future, adac-hybrid-msp430 should be able to take advantage of it, by passing additional flags to LLC (see adac-hybrid-msp430 [https://github.com/n7space/adac-hybrid-msp430/blob/master/README.md README] for details). Please note that given the current constraints of the toolchain and the need for consistency within a linked binary, if Ada language is used within an MSP430 partition in a TASTE project, the partition will be built with small memory model.<br />
<br />
=== Challenges ===<br />
<br />
==== ABI ==== <br />
<br />
MSP430 is a 16-bit MCU – this implies that “base” integer types, enumerations and pointers are 16-bit (20-bit pointers were not tested, as the large memory model is not supported). The Ada code that the toolchain was tested with assumed certain constructs to be 32- or 64-bit. AdaCore’s GNAT LLVM also assumes 32-bit as a “base” size. This led to suboptimal memory layout and more importantly, type size mismatches when combining Ada and C (user-provided or runtime) code. This was resolved by: <br />
* requiring Ada code to explicitly state data type sizes when used together with user-provided C code (this affected ASN1SCC runtime), <br />
* adjusting '''libllvm430''' runtime and Ada system configuration to match the ABI. <br />
<br />
==== GNAT runtime ====<br />
<br />
The GNAT runtime provided by GCC cannot be used as-is on an MSP430 MCU. The System.ads had to be adjusted (which was done with the help of MSP430 Ada project code) for a bare-metal MSP430. Several modules had to be modified to work with 32- and 64-bit floats provided on MSP430. Also, AdaCore GNAT LLVM cannot compile some of the modules – they had to be removed from the runtime. However, their removal shouldn’t affect embedded applications. <br />
<br />
==== Memory consumption ====<br />
<br />
The GNAT runtime is quite large considering the memory available on MSP430 targets. Most of the toolchain validation was done on an emulated MSP430G2553, which provides only 16 kB of flash. While MSP43FR5969 provides 64 kB of FRAM, the assumed priority is to provide as much space for user code as possible. Therefore, '''libgnatmsp430''' is compiled with <code>–ffunction-sections</code> and <code>–fdata-sections</code>, so that the unneeded code (in practice, a great majority of the library) can be trimmed during the linking process, resulting in binaries fitting the target MCUs. <br />
<br />
==== Testing ====<br />
<br />
In order to ensure that the provided toolchain works correctly, multiple test cases were provided. The testing is performed by compiling Ada source code and verifying that it works as expected on an MSP430 target. While testing on real hardware provides a higher degree of certainty, it is also more difficult to setup (especially when considering a Continuous Integration server) and more time consuming (while 16 MHz, 16-bit MCU is slow by itself, the code upload takes seconds and needs to be repeated for each test). With continuous testing in mind, it was decided to deploy most of the tests on an emulator. The emulator of choice was [https://github.com/RudolfGeosits/MSP430-Emulator MSP43-Emulator by Rudolf Geosits]. The project was [https://github.com/n7space/MSP430-Emulator forked] in order to provide several modifications: <br />
* enable command-line usage (for use in automated testing), <br />
* USCI module rewrite (for use in automated testing using files/pipes), <br />
* memory access flags (for more accurate support of peripherals), <br />
* several bugfixes (SR register handling, long jumps, program entry point), <br />
* integrations tests and Dockerfile. <br />
<br />
The use of an emulator also enabled faster and simpler debugging - especially instruction and call trace was a great help in resolving some issues. However, the emulator itself caused some issues on its own – the original version contained several unexpected bugs, which needed to be fixed. Also, the presence of the discovered bugs decreased the confidence in the results of the emulation. Therefore, automated testing on the hardware is a must to raise the confidence in the correctness of the toolchain. However, for performance and setup reasons, most of the tests are still executed on the emulator. Hardware testing is assumed to be the “final” validation. <br />
<br />
It must be noted that the emulator does not implement all MSP430G2553 peripherals, as well as interrupts, and so it is unable to run FreeRTOS-based applications, such as complete MSP430 based TASTE projects. Therefore, only bare-metal use cases are subject to testing with the scope of the toolchain project. Further development of the emulator could remove this limitation. <br />
<br />
End-to-end validation of the toolchain, within TASTE environment and on the target MSP430FR5969 hardware, was done using a sample TASTE project. TASTE repositories contain [https://gitrepos.estec.esa.int/taste/kazoo/-/tree/msp430-ada-support/test/msp430_sdl_ada a skeleton project] for integration testing.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Main_Page&diff=692Main Page2020-06-24T10:51:23Z<p>Kgrochowski: Technical topic: TASTE on MSP430 with FreeRTOS added</p>
<hr />
<div>= TASTE =<br />
Welcome to the [http://taste.tuxfamily.org/ TASTE] wiki! Please edit the wiki at your convenience.<br />
<br />
== TASTE Ecosystem, Overview and Screenshots ==<br />
* [[Latest news]]<br />
* [[Overview]]<br />
* [[TASTE consortium]]<br />
<br />
== Tool availability ==<br />
<br />
* [[Virtual Machine]]<br />
* [[Manual installation on a native platform]]<br />
<br />
== Documentation and presentations ==<br />
* [[Architecture Overview]]<br />
* [[Case studies]]<br />
* [[Media]] and [[Publications related to TASTE]]<br />
* [[Tools documentation]]<br />
* [[Technical topic: Advanced testing with MSC and Python scripts]]<br />
* [[Technical topic: OpenGEODE, an SDL editor for TASTE]]<br />
* [[Technical topic: OpenGEODE - Design pattern: How to emulate the SAVE symbol]]<br />
* [[Technical topic: OpenGEODE - SDL Operators: How to work with data]]<br />
* [[Technical topic: ASN1SCC - ESA's ASN.1 Compiler for safety-critical embedded platforms]]<br />
* [[Technical topic: ASN.1 - An introduction to ACN]]<br />
* [[Technical topic: Hints to model complex packet encodings with ASN.1 and ACN]]<br />
* [[Technical topic: ASN.1 and ACN - How to add a CRC value to an encoded packet]]<br />
* [[Technical topic: ASN.1 and SQL mapping]]<br />
* [[Technical topic: Using SQL Databases in TASTE]]<br />
* [[Technical topic: Customizing the ASN.1 compiler (ASN1SCC) with your own templates]]<br />
* [[Technical topic: Use of timers in user code with TASTE]]<br />
* [[Technical topic: Extend your models with your own property sets to hook your own tools]]<br />
* [[Technical topic: Test your Leon2/Leon3 applications with QEMU]]<br />
* [[Technical topic: Manage interface priorities]]<br />
* [[Technical topic: Work with sockets]]<br />
* [[Technical topic: FPGAs in TASTE]]<br />
* [[Technical topic: Code Coverage]]<br />
* [[Technical topic: Add a new target platform to TASTE]]<br />
* Technical topic: [[Kazoo]] templating engine<br />
* Technical topic: [[Understand the code generation strategy]]<br />
* Technical topic: use the new qualifiable [[QGen]] code generator for Simulink with TASTE<br />
* [[Technical topic: TASTE on MSP430 with FreeRTOS]]<br />
* [[Work in progress: Integrating SDL and VDM]]<br />
<br />
== Management and release process ==<br />
* [[Obtain the code and stay in sync]]<br />
* [[The TASTE VM update mechanism in detail]]<br />
* [[Regression checking suites]]<br />
* [[Repackaging of the VM]]<br />
* [[Merging into stable]]<br />
* [[Building a TASTE-y RTEMS]]<br />
* [[Taming the stack usage of embedded applications]]<br />
<br />
== Support ==<br />
* [[Contribute to the wiki]]<br />
* [[Submit a bug]]<br />
* [[Technical FAQ]]<br />
* [[taste-users]] mailing-list<br />
* [[taste-dev]] mailing-list<br />
* [https://www.openhub.net/p/taste-esa Source code metrics] on [https://www.openhub.net OpenHub]<br />
* [[Troubleshooting Device Driver issues on the Gaisler Boards]]<br />
<br />
== Other information ==<br />
<br />
* [[ASN.1 generators|ASN.1 Compiler and ASN.1 glue generators]]<br />
* [[Ocarina]]<br />
* [[Orchestrator]]<br />
* [[PolyORB-HI-Ada]]<br />
* [[PolyORB-HI-C]]<br />
* [[tasted]] (TASTE daemon - deprecated)<br />
* [[Cross-development toolchains]]<br />
* [[TASTE GUI for Windows]] (experimental)<br />
* [[Software requirements for TASTE GUI for Windows]] (experimental)<br />
* [[Using TASTE GUI for Windows]] (experimental)<br />
* [[Build TASTE on QEMU 1.0 for Windows platforms]] (experimental)<br />
* [[Software requirements for MSC Editor]]<br />
* [[Create an .exe file from the TASTE GUI for Windows sources]] (experimental)<br />
* [[Create an installer for TASTE GUI for Windows]] (experimental)<br />
* [[Create a binary file from the TASTE GUI for Windows sources for Linux]] (experimental)<br />
<br />
* [[ESA Summer of Code in Space - Project ideas]]</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP-430_with_FreeRTOS&diff=691Technical topic: TASTE on MSP-430 with FreeRTOS2020-06-24T10:46:54Z<p>Kgrochowski: Kgrochowski moved page Technical topic: TASTE on MSP-430 with FreeRTOS to Technical topic: TASTE on MSP430 with FreeRTOS</p>
<hr />
<div>#REDIRECT [[Technical topic: TASTE on MSP430 with FreeRTOS]]</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=690Technical topic: TASTE on MSP430 with FreeRTOS2020-06-24T10:46:53Z<p>Kgrochowski: Kgrochowski moved page Technical topic: TASTE on MSP-430 with FreeRTOS to Technical topic: TASTE on MSP430 with FreeRTOS</p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
''' TBD''' Script which checks this constraint since the <code>msp430-elf-ld</code> does not allow to set the stack size (The TI compiler allows to do this).<br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated TCB and actual stacks (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=689Technical topic: TASTE on MSP430 with FreeRTOS2020-06-24T10:46:32Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
''' TBD''' Script which checks this constraint since the <code>msp430-elf-ld</code> does not allow to set the stack size (The TI compiler allows to do this).<br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer should provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer should allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 Runtime limitations and trade-offs ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 Runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is limited. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic interfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provided sporadic interfaces in the node should have the parameter of one exact type.<br />
For an example, the Satellite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) node may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enough for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' of requests. Every request has size equal to the size of the largest of parameters.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE Runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 Runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achieved by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enough to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of function for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code should create timer and message queue, and<br />
* if the interface is sporadic, the generated code should create message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thread the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the generated code should include driver implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory (required FreeRTOS version can be installed using TASTE add-ons scripts).<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the build process is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
The file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated TCB and actual stacks (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared semaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incoming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generated for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into corresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is described in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achieved via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=688Technical topic: TASTE on MSP430 with FreeRTOS2020-06-24T10:33:48Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE Runtime based on FreeRTOS, which is included in the current releases of the TASTE. <br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
''' TBD''' Script which checks this constraint since the <code>msp430-elf-ld</code> does not allow to set the stack size (The TI compiler allows to do this).<br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer shoud provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer shoud allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 runtime limitations ==<br />
The origins of all problems discovered during development of the demo application can be traced back to limited memory on the device.<br />
Although many potentials problems can be resolved using larger memory model or static allocation, as described above, some limitations to MSP430 runtime still applies.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is very small. There are 5 available priorities: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic iterfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provides sporadic interfaces in the nodenode should have the parameter of one exact type.<br />
For an example, the Sattelite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enaugh for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' requests. Every request has size equal to largest size of parameter.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achived by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enaugh to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of funnction for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code shoud create timer and message queue, and<br />
* if the interface is sporadic, the generated code should creater message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thead the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the genrated code should include drived implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory.<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the process of building is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The sole purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
this file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated TCB and actuall stacks (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared samaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The sole purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incomming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generted for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into conresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is descibed in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achived via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=687Technical topic: TASTE on MSP430 with FreeRTOS2020-06-22T15:12:08Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE runtime based on FreeRTOS.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In the small memory model only 48 KB of FRAM are available for programmer with additional 2 KB of SRAM (default location of stack and ''.bss'').<br />
This limitation is caused by 16-bit addressing mode available in the small memory model.<br />
Although 16-bit should allow to address 64 KB of memory, some addressing areas are reserved for bootloader and peripherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives total 64 KB of FRAM memory and additional 2 KB of SRAM for stack and ''.bss''.<br />
In this model all 20 bits of address line are used but as a result the size of pointers is bigger - 4 bytes instead of 2. This memory model also enforces different instruction set.<br />
It means that change from small memory model to large memory model gives access to more memory but at cost of increased size of generated code and data structures containing pointers.<br />
<br />
In small memory model the global variables are allocated in the 2KB of so called RAM segment (representing SRAM memory), which may not be enough to hold all variables.<br />
The selected variables may be allocated inside the FRAM segment instead by adding the special attribute, as in the example bellow:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
As those variables survive reset of the device, their values should be manually reinitialized after reset if necessary.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment (SRAM), which allows the programmer to declare larger number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only higher memory segment for data and as a result leave whole RAM segment for stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enough space for stack in the RAM segment after building the partition image.<br />
<br />
''' TBD''' Script which checks this constraint since the <code>msp430-elf-ld</code> does not allow to set the stack size (The TI compiler allows to do this).<br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer shoud provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer shoud allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 runtime limitations ==<br />
During the development of demo application the origin of all problem were the memory issues.<br />
Many of them was resolved and are described in previous chapter. However, there's few limitations.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is very small. There are 5 available priorites: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic iterfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provides sporadic interfaces in the nodenode should have the parameter of one exact type.<br />
For an example, the Sattelite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enaugh for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' requests. Every request has size equal to largest size of parameter.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achived by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enaugh to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of funnction for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code shoud create timer and message queue, and<br />
* if the interface is sporadic, the generated code should creater message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thead the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the genrated code should include drived implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory.<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the process of building is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The sole purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
this file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated TCB and actuall stacks (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared samaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The sole purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incomming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generted for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into conresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is descibed in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achived via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=686Technical topic: TASTE on MSP430 with FreeRTOS2020-06-22T14:56:45Z<p>Kgrochowski: </p>
<hr />
<div>MSP430 is a family of cheap, ultra-low-power, mixed-signal microcontrollers, which includes space-grade radiation hardened parts (e.g. MSP430FR5969 rated for 50krad, with non-volatile FRAM).<br />
The above traits make them good candidates for deployment in small satellites.<br />
<br />
FreeRTOS is a real-time operating system for embedded microcontrollers. FreeRTOS provides API for threads, mutexes, semaphores, queues and timers with very low memory requirements.<br />
<br />
This page describes MSP430 TASTE runtime based on FreeRTOS.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
=== Memory models in MSP430FR5969 ===<br />
The MSP430FR5969 can operate in two memory models:<br />
* small memory model;<br />
* large memory model.<br />
<br />
In small memory model only 48 KB of FRAM are available for programmer with additional 2 KB for stack and global or static variables.<br />
This limitation is caused by the fact, that in small memory model, only 16 bits for addressing are avaiable.<br />
The 16 bit should allow to address 64 KB of memory, but some memory areas are used by bootlader or perpherals.<br />
<br />
In large memory model, the programmer can use additional 16 KB of FRAM, which gives 64 KB of memory + additional 2 KB for stack and bss.<br />
In this model all 20 bits of address line are used and also the size of pointers are bigger - 4 bytes instead of 2 and the different instruction set is used.<br />
It means that simple change from small memory model to large memory model increases size of generated code.<br />
<br />
In small memory model the static and global variables are allocated in 2KB of RAM, which may be too small memory segment of are variables.<br />
The variables may be allocated outside the RAM segment by adding the special attribute, bellow is the example<br />
but it can be changed by additing special attribute. For an example:<br />
<syntaxhighlight lang="C"><br />
__attribute__ ((persistent)) int global_variable = 0;<br />
</syntaxhighlight><br />
The programmes should reintialize value of this variable after reset of the MCU.<br />
<br />
In large memory model the variables may be allocated outside the RAM memory segment, which allows the programmer to declare large number of variables.<br />
There's also an compiler option <code>-mdata-region=upper</code> to use only memory segment from higher memory, the almost whole RAM segment may be used by stack.<br />
<br />
The problem with 2 KB of RAM segment is that the stack may overwrite the other variables allocated in this segment during runtime.<br />
This may happen before start of FreeRTOS scheduler, during initialization. Currently about 200 bytes of stack are required. The programmer should make sure that, there's enaugh space for stack in the RAM segment after building the partition image.<br />
<br />
''' TBD''' Script which checks this constraint since the <code>msp430-elf-ld</code> does not allow to set the stack size (The TI compiler allows to do this).<br />
<br />
=== FreeRTOS port for MSP430FR5969 ===<br />
The FreeRTOS port for MSP430FR5969 supports both small memory model and large memory model.<br />
When large memory model is used the following options should be passed to the compiler:<br />
* <code>-D__LARGE_DATA_MODEL__=1</code><br />
* <code>-mlarge</code><br />
There are options to specify in which memory segment the code and data should be placed:<br />
* <code>-mcode-region=[either,lower,upper]</code><br />
* <code>-mdata-region=[either,lower,upper]</code><br />
The options <code>-mcode-region=either,lower,upper -mdata-region=upper</code> are recommended for TASTE.<br />
<br />
For small memory model, the only required compiler option is <code>-msmall</code>.<br />
<br />
=== Memory allocation in FreeRTOS ===<br />
FreeRTOS may be configured to use dynamic memory allocation or static memory allocation or both.<br />
When the dynamic memory allocation is used the programmer shoud provide memory region for special FreeRTOS heap.<br />
When static memory allocation is used the programmer shoud allocate required structures before creating FreeRTOS objects. <br />
For TASTE the dynamic memory allocation is disabled, the generated code uses only static memory allocation.<br />
<br />
More information at [https://www.freertos.org/Static_Vs_Dynamic_Memory_Allocation.html Static Vs Dynamic Memory Allocation].<br />
<br />
== MSP430 runtime limitations ==<br />
During the development of demo application the origin of all problem were the memory issues.<br />
Many of them was resolved and are described in previous chapter. However, there's few limitations.<br />
<br />
===Available priorities of threads===<br />
To ensure low memory usage the number of available priorities is very small. There are 5 available priorites: from 0 (lowest priority) to 4 (highest priority).<br />
<br />
===Parameters of remote sporadic iterfaces===<br />
The node may provide multiple sporadic interfaces and may require multiple sporadic interfaces.<br />
The UART driver for Linux (linux-serial-minimal) imposes a requirement that all provides sporadic interfaces in the nodenode should have the parameter of one exact type.<br />
For an example, the Sattelite (MSP430) node may provide many sporadic interfaces with parameter of type Telecommand while the EGSE (Linux) may provide sporadic interfaces with parameter of type Telemetry.<br />
Also the total size of Telemetry should be bigger than total size of Telecommand. Otherwise the Linux driver will not be able to decode the message.<br />
<br />
===Stack sizes of threads===<br />
The default stack size for the thread in TASTE is 50kb. This value almost exceeds the available memory. The user should manually set the appropriate stack size for every thread on MSP430 partition.<br />
The minimal value is 280 bytes for small memory model and 340 bytes for large memory model. This should be enaugh for small projects, however for more complex examples the value may be increased to 1024 bytes and more. During the development the programmer may use FreeRTOS API for detecting stack overflows [https://www.freertos.org/Stacks-and-stack-overflow-checking.html].<br />
<br />
===Number of threads and sizes of queues===<br />
There's no strict limitation of number of threads or sizes of queues. The only limitation is available memory.<br />
Following parameters have an impact on total memory consumption:<br />
* The largest size of parameter sporadic interface after encode;<br />
* The sizes of queues;<br />
* The number of threads and its stacks.<br />
<br />
Every thread has own stack of size '''Stack_Size''' and own queue. Every queue contains '''Queue_Size''' requests. Every request has size equal to largest size of parameter.<br />
This coarse estimation shows how these parameters have an influence on total memory usage by TASTE MSP430 Runtime.<br />
<br />
Nevertheless, the MSP430 TASTE runtime should handle about 10 threads and there should be a free memory for implementation of all interfaces in C.<br />
<br />
== MSP430 runtime implementation details ==<br />
<br />
=== AADL library modifications ===<br />
The image below shows the modification in ''ocarina_components.aadl'' required to add new runtime to the TASTE toolchain.<br />
<br />
[[File:Msp430_ocarina_processor.PNG]]<br />
<br />
This requires some changes in the Ocarina source code which are described at [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
=== Kazoo templates for MSP430 ===<br />
Kazoo generates multiplatform [[Kazoo#Code_skeletons|skeletons]] and [[Kazoo#Glue_code|glue]] source code for function blocks.<br />
The [[Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms|asn1scc]] generates code responsible for encoding/decoding data, which is also platform agnostic.<br />
<br />
The rest of the code, which should be generated to create image of the partition, comes from '''Concurrency View'''.<br />
This code is responsible for device initialization, the initialization of drivers and function blocks from ''Interface View'', and communication between these objects.<br />
To cope with this the following entities should be used:<br />
* Threads;<br />
* Queues;<br />
* Timers;<br />
* Mutexes/Semaphores.<br />
<br />
Before support for MSP430 this was achived by using code generated by [[Ocarina]] which uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as middleware.<br />
<br />
Support for MSP430 is based on FreeRTOS constructs:<br />
* For threads the [https://www.freertos.org/a00019.html FreeRTOS Task] API;<br />
* For queues the [https://www.freertos.org/a00018.html FreeRTOS Queues] are used.<br />
* For timers the [https://www.freertos.org/FreeRTOS-Software-Timer-API-Functions.html Software Timers] are used;<br />
* For semaphores/mutexes [https://www.freertos.org/a00113.html Semaphores] API is used.<br />
This set of constructs is enaugh to create code which ensures cooperation of function blocks and communication with remote partitions.<br />
<br />
For every function block from ''Interface View'' the generated code should create mutex or semaphore, which is used for synchronization.<br />
For every interface of the function block, the set of funnction for passing messages should be generated, and in additional:<br />
* if the interface is cyclic, the generated code shoud create timer and message queue, and<br />
* if the interface is sporadic, the generated code should creater message queue;<br />
* if the interface is protected, the code should acquire and release lock before calling the function;<br />
* if the interface is unprotected there's no additional constrains.<br />
<br />
For every thead the <code>Stack_Size</code> and <code>Priority</code> properties should be included.<br />
<br />
For every queue the property <code>Queue_Length</code> should be taken into account.<br />
<br />
If the node from ''Deployment View'' contains devices, then the genrated code should include drived implementation code.<br />
<br />
The templates should also generate the <code>Makefile</code> and ''GNAT Project Manager'' configuration file, which are responsible for building process of the partition image.<br />
<br />
Following sections describes the kazoo templates.<br />
<br />
=== msp430_freertos_gpr ===<br />
The sole purpose of this template is to create following files:<br />
* <code>build/node/Makefile.node</code>;<br />
* <code>build/node/partition_partition.gpr</code>.<br />
<br />
The only purpose of Makefile is to run grpbuild to build whore partition binary<br />
and to run script which copies required FreeRTOS source files into partition source directory.<br />
<br />
The generated gpr file contains configuration for GNAT project manager.<br />
In this file following sections are generated:<br />
* List of directories of source files, relative to the location of gpr file , see Source_Dirs<br />
* Directory for object files, relative to the location of gpr file, see Object_Dir<br />
* Directory for outpt file, relative to the location of gpr file, see Exec_Dir<br />
* Configuration of the compilers see package Compiler, which includes:<br />
** paths to the compiler executables<br />
** flags for the compilers<br />
* Configuration of the linker, see package Linker, <br />
** path to the linker executable<br />
** flags for the linker<br />
<br />
See other templates like <code>c_pohi_gpr</code>.<br />
<br />
=== msp430_freertos_files ===<br />
<br />
This template generates file <code>build/node/gather_freertos_files.sh</code>, which is executed by <code>Makefile.node</code>.<br />
The sole purpose of this file is to copy required FreeRTOS source files to the partition directory.<br />
The location of FreeRTOS directory is expressed by <code>FREERTOS_PATH</code> environment variable.<br />
<br />
If the files cannot be copied, the script prints an error message, and the process of building is terminated.<br />
<br />
=== msp430_freertos_config ===<br />
<br />
The sole purpose of this template is to produce file <code>build/node/partition/FreeRTOSCOnfig.h</code>. This file is required by FreeRTOS.<br />
this file determines minimal set of FreeRTOS construct, which are required to build partition.<br />
Almost all options are disabled.<br />
<br />
=== msp430_freertos_main ===<br />
This template generates file <code>build/node/partition/main.c</code>, which is entry point for the partition.<br />
<br />
This file contains following functions:<br />
* function prvSetupHardware, which configures MSP430FR5969 MCU and calls device drivers initialization routines.<br />
* function vApplicationStackOverflowHook, which may be used to check stack overflow during debugging (see [https://www.freertos.org/Stacks-and-stack-overflow-checking.html]).<br />
* function vApplicationSetupTimerInterrupt, which configures Timer A for FreeRTOS system ticks.<br />
* function vApplicationGetIdleTaskMemory and vApplicationGetTimerTaskMemory, which provides memory for Ilde task and Timer task. Before these function there's allocated TCB and actuall stacks (see [https://www.freertos.org/a00110.html#configSUPPORT_STATIC_ALLOCATION])<br />
* declaration of semaphores for all function blocks from interface view<br />
* functions which initializes all the threads (see thread.tmplt) with their stacks and queues.<br />
* the function ''main'', which is actual entry point of the partition. The ''main'' function:<br />
** calls function prvSetupHardware<br />
** initializes all previously declared samaphores (see [https://www.freertos.org/xSemaphoreCreateMutexStatic.html xCreateMutexStatic]).<br />
** After hardware initialization the subroutine ''main'' calls initialization subroutines for every function block from the Interface View<br />
** calls previously defined functions which initializes all the tasks<br />
** calls [https://www.freertos.org/a00132.html vTaskStartScheduler].<br />
<br />
The subroutine prvSetupHardware initializes oscillators and clocks:<br />
* oscillator DCO frequency is set to 8 MHz;<br />
* oscillator LFXTCLK frequency is set to 32768 Hz;<br />
* clock MCLK uses DCO with divider 1;<br />
* clock SMCLK uses DCO with divider 1;<br />
* clock ACLK uses LFXTCLK with divider 1.<br />
<br />
=== msp430_freertos_thread_header and msp430_freertos_thread_body ===<br />
These templates generates following files for each thread:<br />
* <code>build/node/partition/thread_$thread_name$.h</code><br />
* <code>build/node/partition/thread_$thread_name$.c</code><br />
<br />
These files contains definition of ''thread entry subroutine'':<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@Task(void* prParameters);<br />
</syntaxhighlight><br />
<br />
If the coresponding interface from InterfaceView is cyclic interface then additional timer callback function is generated:<br />
<syntaxhighlight lang="C"><br />
void prv_@_Thread_Name_@_Timer_Callback(TimerHandle_t timer)<br />
</syntaxhighlight><br />
The sole purpose of this function is to create an new <Request> and put it into thread queue using FreeRTOS function [https://www.freertos.org/a00117.html xQueueSend].<br />
This function is passed as a callback to the timer created using [https://www.freertos.org/xTimerCreateStatic.html xTimerCreateStatic] from FreeRTOS API.<br />
The created timer is started using [https://www.freertos.org/FreeRTOS-timers-xTimerStart.html xTimerStart] function.<br />
<br />
The generated thread entry function contains a loop which waits for incomming tasks using [https://www.freertos.org/a00118.html xQueueReceive] and calls subroutine <code>call_@_LOWER:Thread_Name_@</code> to execute the task.<br />
<br />
=== msp430_freertos_wrappers_header and msp430_freertos_wrappers_body ===<br />
These templtes creates following files:<br />
* <code>build/node/partition/partition_interface.h</code><br />
* <code>build/node/partition/partition_interface.h</code><br />
<br />
These files contains:<br />
Functions with name with prefix <code>pro_</code>, which are generted for corresponding protected interfaces.<br />
These functions are generated by ''pi.tmplt'' file.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void pro_@_Parent_Function_@_@_Name_@<br />
</syntaxhighlight><br />
This function is responsible for acquiring and releasing lock on function block mutex.<br />
The functions [https://www.freertos.org/a00122.html | xSemaphoreTake] and [https://www.freertos.org/a00123.html | xSemaphoreGive] from FreeRTOS API are used to lock and unlock mutex.<br />
<br />
Every provided interface has corresponding function with prefix <code>vm_</code>.<br />
These functions are generated by file ''ri.tmplt''.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void vm_@_LOWER:Parent_Function_@_@_LOWER:Name_@<br />
</syntaxhighlight><br />
These functions are used by code skeletons for calling required interfaces.<br />
The body of the function depends on type of the provided interface.<br />
If the interface is sporadic, then the structure <code>Request</code> is created and filled with parameter value. Then, the function with prefix <code>deliver_to_</code> is called, which is responsible for putting the task into conresponding queue or passing the task to the device driver.<br />
If the interface is protected, then the sole purpose of this function is to call corresponding function with prefix <code>pro_</code> (see above).<br />
If the interface is unprotected, then the function calls directly corresponding skeleton function.<br />
<br />
The functions with prefix <code>call_</code> are generated for sporadic interfaces.<br />
Following part of code show how the name of the function is generated:<br />
<syntaxhighlight lang="C"><br />
void call_@_LOWER:Thread_Name_@ (const char* buf, size_t len)<br />
</syntaxhighlight><br />
The file ''thread.tmplt'' is responsible for generation of these functions.<br />
This function is responsible for acquiring and releasing lock on function mutex.<br />
<br />
=== msp430_freertos_transport_body msp430_transport_header ===<br />
These templates generates following files:<br />
* <code>build/node/partition/transport.h</code><br />
* <code>build/node/partition/transport.c</code><br />
<br />
The <code>transport.h</code> contains generated structure <code>MSPAllParameters</code>.<br />
This structure is used only to calculate the size of the filed <code>m_data</code> in the structures <code>Request</code> and <code>Message</code><br />
<br />
The structure <code>Request</code> is used to pass task to the task queues in local partition.<br />
The structure <code>Message</code> is used to pass task to the sporadic interfaces on remote partition.<br />
This structure contains additional field <code>m_port</code> which denotes number of the port.<br />
<br />
The file <code>transport.h</code> contains function <code>process_incomming_message</code> which is used by<br />
communication device driver to proceed incoming message.<br />
Also the device driver should use function <code>register_remote_transport_func</code><br />
which is used to pass the structure <code>Message</code> outside the partition.<br />
<br />
For the moment, only one device driver on the msp430 node is supported and only one device driver for MSP430 is created.<br />
<br />
In file <code>transport.c</code> the subroutines ''deliver_to_'' are defined.<br />
These functions are used to transport the <code>Request</code> to corresponding queue or to the device driver.<br />
<br />
The file generated for PolORB <code>deployment.h</code> is used to obtain a port number for remote port.<br />
<br />
Also the function <code>process_incoming_message</code> uses enum from <code>deployment.h</code> to decide which thread shoud be used<br />
to proceed <code>Message</code>.<br />
<br />
=== msp430_freertos_eusci_a_serial_minimal_header and msp430_freertos_eusci_a_serial_minimal_header ===<br />
<br />
These templates generates following files:<br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.c</code><br />
* <code>build/node/partition/drivers/msp430_eusci_a_serial_minimal/msp430_eusci_a_serial_minimal.h</code><br />
<br />
These files contains a source code of the communication driver<br />
Which uses MSP430 e_USCI_A to provide UART communication with other nodes.<br />
<br />
Following functions are defined: <br />
<syntaxhighlight lang="C"><br />
void msp430_eusci_a_serial_minimal_init(void);<br />
void msp430_eusci_a_serial_minimal_poller(void* param);<br />
void msp430_eusci_a_serial_minimal_sender(uint8_t* data, uint32_t length, uint32_t port);<br />
</syntaxhighlight><br />
<br />
More about device driver in the next chapter.<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The procedure of adding device drivers is descibed in article [[Writing driver for PolyORB-HI-C]].<br />
<br />
For MSP430FR5969 the communication with remote nodes was achived via UART.<br />
The UART driver for Linux was implemented as PolORB-HI-C driver: <code>linux_serial_minimal</code>.<br />
The UART driver for MSP430 was implemented without PolyORB: <code>msp430_eusci_a_serial_minimal</code>.<br />
<br />
=== ocarina_components.aadl ===<br />
The file ''ocarina_components.aadl'' is part of the [https://gitrepos.estec.esa.int/taste/taste-setup taste-setup] project.<br />
On the Taste VM the location of this file is ''/home/taste/tool-src/install/misc/aadl-library/ocarina_components.aadl''.<br />
<br />
For the MSP430 the new bus implementation ''serial.minimal'' was added.<br />
Together with this bus, two devices was added with ability to use this bus: <code>MSP430_serial</code> and <code>linux_serial</code>.</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=546Technical topic: TASTE on MSP430 with FreeRTOS2019-12-16T12:24:24Z<p>Kgrochowski: /* Mapping of TASTE structures */</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
'''TBC'''<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
'''TBC'''<br />
<br />
=== Mapping of TASTE structures ===<br />
The threads will be mapped to [https://www.freertos.org/implementing-a-FreeRTOS-task.html FreeRTOS Tasks].<br />
Task has own stack, priority and ''main'' function.<br />
<br />
The communication and synchronization between tasks will be realised using [https://www.freertos.org/Inter-Task-Communication.html queues and semaphores or mutexes].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software [https://www.freertos.org/RTOS-software-timer.html timers].<br />
<br />
'''TBC'''<br />
<br />
=== Gathering FreeRTOS source files ===<br />
The FreeRTOS source files must be present in the partition source directory before compilation.<br />
There are two possible solutions:<br />
* embed FreeRTOS source files in kazoo templates;<br />
* create template that generates shell script, which copies requires FreeRTOS files from known location.<br />
<br />
'''TBC'''<br />
<br />
=== main.c ===<br />
To generate this file, the new Concurrency View subdirectory should be created.<br />
This file is a entry point, the function ''main'' for partition on MSP430.<br />
This file should be responsible for intialization of FreeRTOS primitives like tasks and queues.<br />
The device drivers should be initialized here.<br />
The '''main.c''' should also contain all necessary functions and other structures, which are required by FreeRTOS.<br />
<br />
'''TBC'''<br />
<br />
=== Function wrappers ===<br />
The wrappers around provided interfaces of the functions will be generated in files '''build/<node name>/<partition name>/freertos_interface.{c,h}'''.<br />
The responsibilities of wrapper function is:<br />
* acquire lock on mutex before calling the function if provided interface is ''protected'' if necessary;<br />
* send [[#Requests]] to other partitions.<br />
<br />
As a base for templates following subdirectories will be used: ''pohic_wrappers_body'' and ''pohic_wrappers_header''.<br />
<br />
=== Requests ===<br />
This file will be contains structures responsible for communication between other partitions.<br />
As a prototype for this template, the files ''request.c'' and ''request.h'', currently generated by [[Ocarina]], will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Marshallers ===<br />
This file will be contain function responsible for decoding and encoding [[#Requests]].<br />
As a prototype for this template, the files ''marshallers.c'' and ''marshallers.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Subprograms ===<br />
This file will be contain functions corresponding to subprograms for [[#Device drivers]].<br />
As a prototype for this template, the files ''subprograms.c'' and ''subprograms.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Activity ===<br />
This file will be contain activities like, waiting for events or queues and calling functions responsible for realization of ''provided interfaces''. <br />
As a prototype for this template, the files ''activity.c'' and ''activity.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== FreeRTOSConfig.h ===<br />
To generate this file, the new concurrency_view subdirectory should be created.<br />
<br />
The file ''FreeRTOSConfig.h'' contains configuration for FreeRTOS.<br />
This file defines a set of macros.<br />
Example macros are presented in table below:<br />
{| class="wikitable"<br />
!Macro name<br />
!Description<br />
|-<br />
|<code>configTICK_RATE_HZ</code><br />
|Used to configure tick frequency for scheduler<br />
|-<br />
|<code>configMAX_PRIORITIES</code><br />
|Used to configure max priority of the task<br />
|-<br />
|<code>configGENERATE_RUN_TIME_STATS</code><br />
|Used to enable or disable run time statistics<br />
|-<br />
|<code>configTOTAL_HEAP_SIZE</code> <br />
|Used to configure total heap size<br />
|-<br />
|<code>configMINIMAL_STACK_SIZE</code><br />
|Uset to configure minimal stack size<br />
|}<br />
<br />
Some macros, like <code>configTICK_RATE_HZ</code>, will be generated based on kazoo template parameters.<br />
FreeRTOSConfig.h will be used for tailoring FreeRTOS for TASTE purposes. For an example to disable coroutines following line will be added:<br />
<syntaxhighlight lang="C"><br />
#define configUSE_CO_ROUTINES ( 0 )<br />
</syntaxhighlight><br />
Or to do not include FreeRTOS function to compilation to reduce memory usage:<br />
<syntaxhighlight lang="C"><br />
#define INCLUDE_vTaskDelete ( 1 )<br />
</syntaxhighlight><br />
<br />
'''TBC'''<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
The source code files generated by kazoo, should be compiled.<br />
For this purpose the kazoo template should be created based on existing template for other platform, e.g. <code>c_pohi_gpr</code>.<br />
$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r c_pohi_gpr freertos_msp430_gpr<br />
<br />
Within new subdirectory, the file ''partition.tmplt'' is the main file responsible for generation of ''.gpr'' file, but other files, like ''trigger.tmplt'', should be changed.<br />
The generated file is responsible for building partition. The main modification in ''partition.tmplt'' is exclusion of PolyORB files from compilation and inclusion of source files generated for FreeRTOS partition.<br />
This file should also include FreeRTOS source files and source code for device drivers.<br />
<br />
Another modification in this file is introduction of C compiler for MPS430 platform: <code>msp430-elf-gcc</code>.<br />
<br />
'''TBC'''<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The device drivers for MSP430 and FreeRTOS will be implemented independly using driver library for MSP430FR5969.<br />
<br />
'''TBC'''<br />
<br />
=== UART ===<br />
'''TBC'''</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=545Technical topic: TASTE on MSP430 with FreeRTOS2019-12-16T12:19:10Z<p>Kgrochowski: /* Hardware Description */</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using [http://www.ti.com/product/MSP430FR5969 MSP43FR5969] processor as example.<br />
The [http://www.ti.com/tool/MSP-EXP430FR5969 MSP430FR5969 LaunchPad Development Kit] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
'''TBC'''<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
'''TBC'''<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
FreeRTOS task is just a thread. It has own stack, priority and ''main'' function.<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
'''TBC'''<br />
<br />
=== Gathering FreeRTOS source files ===<br />
The FreeRTOS source files must be present in the partition source directory before compilation.<br />
There are two possible solutions:<br />
* embed FreeRTOS source files in kazoo templates;<br />
* create template that generates shell script, which copies requires FreeRTOS files from known location.<br />
<br />
'''TBC'''<br />
<br />
=== main.c ===<br />
To generate this file, the new Concurrency View subdirectory should be created.<br />
This file is a entry point, the function ''main'' for partition on MSP430.<br />
This file should be responsible for intialization of FreeRTOS primitives like tasks and queues.<br />
The device drivers should be initialized here.<br />
The '''main.c''' should also contain all necessary functions and other structures, which are required by FreeRTOS.<br />
<br />
'''TBC'''<br />
<br />
=== Function wrappers ===<br />
The wrappers around provided interfaces of the functions will be generated in files '''build/<node name>/<partition name>/freertos_interface.{c,h}'''.<br />
The responsibilities of wrapper function is:<br />
* acquire lock on mutex before calling the function if provided interface is ''protected'' if necessary;<br />
* send [[#Requests]] to other partitions.<br />
<br />
As a base for templates following subdirectories will be used: ''pohic_wrappers_body'' and ''pohic_wrappers_header''.<br />
<br />
=== Requests ===<br />
This file will be contains structures responsible for communication between other partitions.<br />
As a prototype for this template, the files ''request.c'' and ''request.h'', currently generated by [[Ocarina]], will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Marshallers ===<br />
This file will be contain function responsible for decoding and encoding [[#Requests]].<br />
As a prototype for this template, the files ''marshallers.c'' and ''marshallers.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Subprograms ===<br />
This file will be contain functions corresponding to subprograms for [[#Device drivers]].<br />
As a prototype for this template, the files ''subprograms.c'' and ''subprograms.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Activity ===<br />
This file will be contain activities like, waiting for events or queues and calling functions responsible for realization of ''provided interfaces''. <br />
As a prototype for this template, the files ''activity.c'' and ''activity.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== FreeRTOSConfig.h ===<br />
To generate this file, the new concurrency_view subdirectory should be created.<br />
<br />
The file ''FreeRTOSConfig.h'' contains configuration for FreeRTOS.<br />
This file defines a set of macros.<br />
Example macros are presented in table below:<br />
{| class="wikitable"<br />
!Macro name<br />
!Description<br />
|-<br />
|<code>configTICK_RATE_HZ</code><br />
|Used to configure tick frequency for scheduler<br />
|-<br />
|<code>configMAX_PRIORITIES</code><br />
|Used to configure max priority of the task<br />
|-<br />
|<code>configGENERATE_RUN_TIME_STATS</code><br />
|Used to enable or disable run time statistics<br />
|-<br />
|<code>configTOTAL_HEAP_SIZE</code> <br />
|Used to configure total heap size<br />
|-<br />
|<code>configMINIMAL_STACK_SIZE</code><br />
|Uset to configure minimal stack size<br />
|}<br />
<br />
Some macros, like <code>configTICK_RATE_HZ</code>, will be generated based on kazoo template parameters.<br />
FreeRTOSConfig.h will be used for tailoring FreeRTOS for TASTE purposes. For an example to disable coroutines following line will be added:<br />
<syntaxhighlight lang="C"><br />
#define configUSE_CO_ROUTINES ( 0 )<br />
</syntaxhighlight><br />
Or to do not include FreeRTOS function to compilation to reduce memory usage:<br />
<syntaxhighlight lang="C"><br />
#define INCLUDE_vTaskDelete ( 1 )<br />
</syntaxhighlight><br />
<br />
'''TBC'''<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
The source code files generated by kazoo, should be compiled.<br />
For this purpose the kazoo template should be created based on existing template for other platform, e.g. <code>c_pohi_gpr</code>.<br />
$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r c_pohi_gpr freertos_msp430_gpr<br />
<br />
Within new subdirectory, the file ''partition.tmplt'' is the main file responsible for generation of ''.gpr'' file, but other files, like ''trigger.tmplt'', should be changed.<br />
The generated file is responsible for building partition. The main modification in ''partition.tmplt'' is exclusion of PolyORB files from compilation and inclusion of source files generated for FreeRTOS partition.<br />
This file should also include FreeRTOS source files and source code for device drivers.<br />
<br />
Another modification in this file is introduction of C compiler for MPS430 platform: <code>msp430-elf-gcc</code>.<br />
<br />
'''TBC'''<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The device drivers for MSP430 and FreeRTOS will be implemented independly using driver library for MSP430FR5969.<br />
<br />
'''TBC'''<br />
<br />
=== UART ===<br />
'''TBC'''</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=544Technical topic: TASTE on MSP430 with FreeRTOS2019-12-16T12:17:20Z<p>Kgrochowski: /* Modification in Makefiles and GNAT Project Manager files */</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using MSP43FR5969 processor [http://www.ti.com/product/MSP430FR5969] as example.<br />
The MSP430FR5969 LaunchPad Development Kit [http://www.ti.com/tool/MSP-EXP430FR5969] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
'''TBC'''<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
'''TBC'''<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
FreeRTOS task is just a thread. It has own stack, priority and ''main'' function.<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
'''TBC'''<br />
<br />
=== Gathering FreeRTOS source files ===<br />
The FreeRTOS source files must be present in the partition source directory before compilation.<br />
There are two possible solutions:<br />
* embed FreeRTOS source files in kazoo templates;<br />
* create template that generates shell script, which copies requires FreeRTOS files from known location.<br />
<br />
'''TBC'''<br />
<br />
=== main.c ===<br />
To generate this file, the new Concurrency View subdirectory should be created.<br />
This file is a entry point, the function ''main'' for partition on MSP430.<br />
This file should be responsible for intialization of FreeRTOS primitives like tasks and queues.<br />
The device drivers should be initialized here.<br />
The '''main.c''' should also contain all necessary functions and other structures, which are required by FreeRTOS.<br />
<br />
'''TBC'''<br />
<br />
=== Function wrappers ===<br />
The wrappers around provided interfaces of the functions will be generated in files '''build/<node name>/<partition name>/freertos_interface.{c,h}'''.<br />
The responsibilities of wrapper function is:<br />
* acquire lock on mutex before calling the function if provided interface is ''protected'' if necessary;<br />
* send [[#Requests]] to other partitions.<br />
<br />
As a base for templates following subdirectories will be used: ''pohic_wrappers_body'' and ''pohic_wrappers_header''.<br />
<br />
=== Requests ===<br />
This file will be contains structures responsible for communication between other partitions.<br />
As a prototype for this template, the files ''request.c'' and ''request.h'', currently generated by [[Ocarina]], will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Marshallers ===<br />
This file will be contain function responsible for decoding and encoding [[#Requests]].<br />
As a prototype for this template, the files ''marshallers.c'' and ''marshallers.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Subprograms ===<br />
This file will be contain functions corresponding to subprograms for [[#Device drivers]].<br />
As a prototype for this template, the files ''subprograms.c'' and ''subprograms.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Activity ===<br />
This file will be contain activities like, waiting for events or queues and calling functions responsible for realization of ''provided interfaces''. <br />
As a prototype for this template, the files ''activity.c'' and ''activity.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== FreeRTOSConfig.h ===<br />
To generate this file, the new concurrency_view subdirectory should be created.<br />
<br />
The file ''FreeRTOSConfig.h'' contains configuration for FreeRTOS.<br />
This file defines a set of macros.<br />
Example macros are presented in table below:<br />
{| class="wikitable"<br />
!Macro name<br />
!Description<br />
|-<br />
|<code>configTICK_RATE_HZ</code><br />
|Used to configure tick frequency for scheduler<br />
|-<br />
|<code>configMAX_PRIORITIES</code><br />
|Used to configure max priority of the task<br />
|-<br />
|<code>configGENERATE_RUN_TIME_STATS</code><br />
|Used to enable or disable run time statistics<br />
|-<br />
|<code>configTOTAL_HEAP_SIZE</code> <br />
|Used to configure total heap size<br />
|-<br />
|<code>configMINIMAL_STACK_SIZE</code><br />
|Uset to configure minimal stack size<br />
|}<br />
<br />
Some macros, like <code>configTICK_RATE_HZ</code>, will be generated based on kazoo template parameters.<br />
FreeRTOSConfig.h will be used for tailoring FreeRTOS for TASTE purposes. For an example to disable coroutines following line will be added:<br />
<syntaxhighlight lang="C"><br />
#define configUSE_CO_ROUTINES ( 0 )<br />
</syntaxhighlight><br />
Or to do not include FreeRTOS function to compilation to reduce memory usage:<br />
<syntaxhighlight lang="C"><br />
#define INCLUDE_vTaskDelete ( 1 )<br />
</syntaxhighlight><br />
<br />
'''TBC'''<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
The source code files generated by kazoo, should be compiled.<br />
For this purpose the kazoo template should be created based on existing template for other platform, e.g. <code>c_pohi_gpr</code>.<br />
$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r c_pohi_gpr freertos_msp430_gpr<br />
<br />
Within new subdirectory, the file ''partition.tmplt'' is the main file responsible for generation of ''.gpr'' file, but other files, like ''trigger.tmplt'', should be changed.<br />
The generated file is responsible for building partition. The main modification in ''partition.tmplt'' is exclusion of PolyORB files from compilation and inclusion of source files generated for FreeRTOS partition.<br />
This file should also include FreeRTOS source files and source code for device drivers.<br />
<br />
Another modification in this file is introduction of C compiler for MPS430 platform: <code>msp430-elf-gcc</code>.<br />
<br />
'''TBC'''<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The device drivers for MSP430 and FreeRTOS will be implemented independly using driver library for MSP430FR5969.<br />
<br />
'''TBC'''<br />
<br />
=== UART ===<br />
'''TBC'''</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=543Technical topic: TASTE on MSP430 with FreeRTOS2019-12-16T12:16:45Z<p>Kgrochowski: /* FreeRTOSConfig.h */</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using MSP43FR5969 processor [http://www.ti.com/product/MSP430FR5969] as example.<br />
The MSP430FR5969 LaunchPad Development Kit [http://www.ti.com/tool/MSP-EXP430FR5969] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
'''TBC'''<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
'''TBC'''<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
FreeRTOS task is just a thread. It has own stack, priority and ''main'' function.<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
'''TBC'''<br />
<br />
=== Gathering FreeRTOS source files ===<br />
The FreeRTOS source files must be present in the partition source directory before compilation.<br />
There are two possible solutions:<br />
* embed FreeRTOS source files in kazoo templates;<br />
* create template that generates shell script, which copies requires FreeRTOS files from known location.<br />
<br />
'''TBC'''<br />
<br />
=== main.c ===<br />
To generate this file, the new Concurrency View subdirectory should be created.<br />
This file is a entry point, the function ''main'' for partition on MSP430.<br />
This file should be responsible for intialization of FreeRTOS primitives like tasks and queues.<br />
The device drivers should be initialized here.<br />
The '''main.c''' should also contain all necessary functions and other structures, which are required by FreeRTOS.<br />
<br />
'''TBC'''<br />
<br />
=== Function wrappers ===<br />
The wrappers around provided interfaces of the functions will be generated in files '''build/<node name>/<partition name>/freertos_interface.{c,h}'''.<br />
The responsibilities of wrapper function is:<br />
* acquire lock on mutex before calling the function if provided interface is ''protected'' if necessary;<br />
* send [[#Requests]] to other partitions.<br />
<br />
As a base for templates following subdirectories will be used: ''pohic_wrappers_body'' and ''pohic_wrappers_header''.<br />
<br />
=== Requests ===<br />
This file will be contains structures responsible for communication between other partitions.<br />
As a prototype for this template, the files ''request.c'' and ''request.h'', currently generated by [[Ocarina]], will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Marshallers ===<br />
This file will be contain function responsible for decoding and encoding [[#Requests]].<br />
As a prototype for this template, the files ''marshallers.c'' and ''marshallers.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Subprograms ===<br />
This file will be contain functions corresponding to subprograms for [[#Device drivers]].<br />
As a prototype for this template, the files ''subprograms.c'' and ''subprograms.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Activity ===<br />
This file will be contain activities like, waiting for events or queues and calling functions responsible for realization of ''provided interfaces''. <br />
As a prototype for this template, the files ''activity.c'' and ''activity.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== FreeRTOSConfig.h ===<br />
To generate this file, the new concurrency_view subdirectory should be created.<br />
<br />
The file ''FreeRTOSConfig.h'' contains configuration for FreeRTOS.<br />
This file defines a set of macros.<br />
Example macros are presented in table below:<br />
{| class="wikitable"<br />
!Macro name<br />
!Description<br />
|-<br />
|<code>configTICK_RATE_HZ</code><br />
|Used to configure tick frequency for scheduler<br />
|-<br />
|<code>configMAX_PRIORITIES</code><br />
|Used to configure max priority of the task<br />
|-<br />
|<code>configGENERATE_RUN_TIME_STATS</code><br />
|Used to enable or disable run time statistics<br />
|-<br />
|<code>configTOTAL_HEAP_SIZE</code> <br />
|Used to configure total heap size<br />
|-<br />
|<code>configMINIMAL_STACK_SIZE</code><br />
|Uset to configure minimal stack size<br />
|}<br />
<br />
Some macros, like <code>configTICK_RATE_HZ</code>, will be generated based on kazoo template parameters.<br />
FreeRTOSConfig.h will be used for tailoring FreeRTOS for TASTE purposes. For an example to disable coroutines following line will be added:<br />
<syntaxhighlight lang="C"><br />
#define configUSE_CO_ROUTINES ( 0 )<br />
</syntaxhighlight><br />
Or to do not include FreeRTOS function to compilation to reduce memory usage:<br />
<syntaxhighlight lang="C"><br />
#define INCLUDE_vTaskDelete ( 1 )<br />
</syntaxhighlight><br />
<br />
'''TBC'''<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
The source code files generated by kazoo, should be compiled.<br />
For this purpose the kazoo template should be created based on existing template for other platform, e.g. <code>c_pohi_gpr</code>.<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r c_pohi_gpr freertos_msp430_gpr</nowiki><br />
<br />
Within new subdirectory, the file ''partition.tmplt'' is the main file responsible for generation of ''.gpr'' file, but other files, like ''trigger.tmplt'', should be changed.<br />
The generated file is responsible for building partition. The main modification in ''partition.tmplt'' is exclusion of PolyORB files from compilation and inclusion of source files generated for FreeRTOS partition.<br />
This file should also include FreeRTOS source files and source code for device drivers.<br />
<br />
Another modification in this file is introduction of C compiler for MPS430 platform: <code>msp430-elf-gcc</code>.<br />
<br />
'''TBC'''<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The device drivers for MSP430 and FreeRTOS will be implemented independly using driver library for MSP430FR5969.<br />
<br />
'''TBC'''<br />
<br />
=== UART ===<br />
'''TBC'''</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=542Kazoo2019-12-16T12:12:52Z<p>Kgrochowski: /* Code generation */</p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
$ cd ~/tool-src/kazoo<br />
$ git checkout master<br />
$ git pull<br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build and install kazoo from sources so run the following commands in the terminal:<br />
$ cd ~/tool-src<br />
$ ./install/87_kazoo.sh<br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
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:<br />
<br />
$ taste<br />
<br />
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.<br />
<br />
<syntaxhighlight lang="Makefile"><br />
KAZOO?=kazoo<br />
<br />
all: c<br />
<br />
c: work/glue_built<br />
$(MAKE) -C work<br />
<br />
skeletons: InterfaceView.aadl DataView.aadl<br />
$(KAZOO) --gw -o work<br />
$(MAKE) -C work dataview<br />
<br />
work/glue_built: InterfaceView.aadl DeploymentView.aadl DataView.aadl<br />
$(KAZOO) -p --glue --gw -o work<br />
touch work/glue_built<br />
<br />
clean:<br />
$(MAKE) -C work clean<br />
<br />
.PHONY: clean skeletons c<br />
</syntaxhighlight><br />
<br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''work''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
$ make<br />
<br />
The output binary files will be located in the directory '''work/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make -j<br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Makefiles/Project Files/ - to build the system incrementally,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces, via a middleware and operating system,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons|code skeletons]] and [[#Glue code|glue code]] generation algorithms.<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View|Concurrency View processing]].<br />
<br />
=== Build script ===<br />
A build script named <code>build-script.sh</code> is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code><function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code><function name>/<language>/<function name>_mini_cv.aadl</code><br />
|-<br />
|system_config<br />
|<code><function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code><function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code><function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
=== Concurrency View ===<br />
For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code> (the actual Concurrency View)<br />
|Always (Used later by [[Ocarina]] to create middleware source code from the Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code> (AADL project entry point)<br />
|Always (Used later by [[Ocarina]] to process the Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code> (Cross-compiler configuration for the TSP/AIR hypervisor)<br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=538Technical topic: TASTE on MSP430 with FreeRTOS2019-12-16T11:04:21Z<p>Kgrochowski: </p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP-430 platform using MSP43FR5969 processor [http://www.ti.com/product/MSP430FR5969] as example.<br />
The MSP430FR5969 LaunchPad Development Kit [http://www.ti.com/tool/MSP-EXP430FR5969] was used for testing purposes.<br />
<br />
Microcontroller's parameters:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
On this very limited platform using [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] is impossible, due to memory requirements.<br />
In the next sections the different approach of code generation is described.<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
<br />
'''TBC'''<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
'''TBC'''<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
FreeRTOS task is just a thread. It has own stack, priority and ''main'' function.<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
'''TBC'''<br />
<br />
=== Gathering FreeRTOS source files ===<br />
The FreeRTOS source files must be present in the partition source directory before compilation.<br />
There are two possible solutions:<br />
* embed FreeRTOS source files in kazoo templates;<br />
* create template that generates shell script, which copies requires FreeRTOS files from known location.<br />
<br />
'''TBC'''<br />
<br />
=== main.c ===<br />
To generate this file, the new Concurrency View subdirectory should be created.<br />
This file is a entry point, the function ''main'' for partition on MSP430.<br />
This file should be responsible for intialization of FreeRTOS primitives like tasks and queues.<br />
The device drivers should be initialized here.<br />
The '''main.c''' should also contain all necessary functions and other structures, which are required by FreeRTOS.<br />
<br />
'''TBC'''<br />
<br />
=== Function wrappers ===<br />
The wrappers around provided interfaces of the functions will be generated in files '''build/<node name>/<partition name>/freertos_interface.{c,h}'''.<br />
The responsibilities of wrapper function is:<br />
* acquire lock on mutex before calling the function if provided interface is ''protected'' if necessary;<br />
* send [[#Requests]] to other partitions.<br />
<br />
As a base for templates following subdirectories will be used: ''pohic_wrappers_body'' and ''pohic_wrappers_header''.<br />
<br />
=== Requests ===<br />
This file will be contains structures responsible for communication between other partitions.<br />
As a prototype for this template, the files ''request.c'' and ''request.h'', currently generated by [[Ocarina]], will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Marshallers ===<br />
This file will be contain function responsible for decoding and encoding [[#Requests]].<br />
As a prototype for this template, the files ''marshallers.c'' and ''marshallers.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Subprograms ===<br />
This file will be contain functions corresponding to subprograms for [[#Device drivers]].<br />
As a prototype for this template, the files ''subprograms.c'' and ''subprograms.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== Activity ===<br />
This file will be contain activities like, waiting for events or queues and calling functions responsible for realization of ''provided interfaces''. <br />
As a prototype for this template, the files ''activity.c'' and ''activity.h'', currently generated by [[Ocarina]] will be used.<br />
<br />
''' TBC '''<br />
<br />
=== FreeRTOSConfig.h ===<br />
To generate this file, the new concurrency_view subdirectory should be created.<br />
<br />
The file ''FreeRTOSConfig.h'' contains configuration for FreeRTOS.<br />
This file defines a set of macros.<br />
Example macros are presented in table below:<br />
{| class="wikitable"<br />
!Macro name<br />
!Description<br />
|-<br />
|configTICK_RATE_HZ<br />
|Used to configure tick frequency for scheduler<br />
|-<br />
|configMAX_PRIORITIES<br />
|Used to configure max priority of the task<br />
|-<br />
|configGENERATE_RUN_TIME_STATS <br />
|Used to enable or disable run time statistics<br />
|-<br />
|configTOTAL_HEAP_SIZE <br />
|Used to configure total heap size<br />
|-<br />
|configMINIMAL_STACK_SIZE <br />
|Uset to configure minimal stack size<br />
|}<br />
<br />
Some macros, like configTICK_RATE_HZ, will be generated based on kazoo template parameters.<br />
FreeRTOSConfig.h will be used for tailoring FreeRTOS for TASTE purposes. For an example to disable coroutines following line will be added:<br />
<nowiki><br />
#define configUSE_CO_ROUTINES ( 0 )</nowiki><br />
Or to do not include FreeRTOS function to compilation to reduce memory usage:<br />
<nowiki><br />
#define INCLUDE_vTaskDelete ( 1 )</nowiki><br />
<br />
'''TBC'''<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
The source code files generated by kazoo, should be compiled.<br />
For this purpose the kazoo template should be created based on existing template for other platform, e.g. <code>c_pohi_gpr</code>.<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r c_pohi_gpr freertos_msp430_gpr</nowiki><br />
<br />
Within new subdirectory, the file ''partition.tmplt'' is the main file responsible for generation of ''.gpr'' file, but other files, like ''trigger.tmplt'', should be changed.<br />
The generated file is responsible for building partition. The main modification in ''partition.tmplt'' is exclusion of PolyORB files from compilation and inclusion of source files generated for FreeRTOS partition.<br />
This file should also include FreeRTOS source files and source code for device drivers.<br />
<br />
Another modification in this file is introduction of C compiler for MPS430 platform: <code>msp430-elf-gcc</code>.<br />
<br />
'''TBC'''<br />
<br />
== Device drivers ==<br />
The devices and their drivers are described in file ''ocarina_components.aadl''. This file describes subprograms required by device drivers.<br />
The device drivers for MSP430 and FreeRTOS will be implemented independly using driver library for MSP430FR5969.<br />
<br />
'''TBC'''</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=536Kazoo2019-12-16T09:49:10Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
$ cd ~/tool-src/kazoo<br />
$ git checkout master<br />
$ git pull<br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build and install kazoo from sources so run the following commands in the terminal:<br />
$ cd ~/tool-src<br />
$ ./install/87_kazoo.sh<br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
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:<br />
<br />
$ taste<br />
<br />
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.<br />
<br />
<syntaxhighlight lang="Makefile"><br />
KAZOO?=kazoo<br />
<br />
all: c<br />
<br />
c: work/glue_built<br />
$(MAKE) -C work<br />
<br />
skeletons: InterfaceView.aadl DataView.aadl<br />
$(KAZOO) --gw -o work<br />
$(MAKE) -C work dataview<br />
<br />
work/glue_built: InterfaceView.aadl DeploymentView.aadl DataView.aadl<br />
$(KAZOO) -p --glue --gw -o work<br />
touch work/glue_built<br />
<br />
clean:<br />
$(MAKE) -C work clean<br />
<br />
.PHONY: clean skeletons c<br />
</syntaxhighlight><br />
<br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''work''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
$ make<br />
<br />
The output binary files will be located in the directory '''work/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make -j<br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Makefiles/Project Files/ - to build the system incrementally,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces, via a middleware and operating system,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons|code skeletons]] and [[#Glue code|glue code]] generation algorithms.<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
A build script named <code>build-script.sh</code> is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code><function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code><function name>/<language>/<function name>_mini_cv.aadl</code><br />
|-<br />
|system_config<br />
|<code><function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code><function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code><function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
=== Concurrency View ===<br />
For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code> (the actual Concurrency View)<br />
|Always (Used later by [[Ocarina]] to create middleware source code from the Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code> (AADL project entry point)<br />
|Always (Used later by [[Ocarina]] to process the Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code> (Cross-compiler configuration for the TSP/AIR hypervisor)<br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_and_FreeRTOS&diff=521Kazoo and FreeRTOS2019-12-13T15:45:38Z<p>Kgrochowski: Redirected page to Technical topic: TASTE on MSP-430 with FreeRTOS</p>
<hr />
<div>#REDIRECT [[Technical topic: TASTE on MSP-430 with FreeRTOS]]</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=519Technical topic: TASTE on MSP430 with FreeRTOS2019-12-13T15:42:25Z<p>Kgrochowski: Kgrochowski moved page Technical topic: TASTE on MSP-430 to Technical topic: TASTE on MSP-430 with FreeRTOS</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP43FR5969 processor [http://www.ti.com/product/MSP430FR5969].<br />
The MSP430FR5969 LaunchPad Development Kit [http://www.ti.com/tool/MSP-EXP430FR5969] was used for testing purposes.<br />
<br />
Features of this microcontroller:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
TBC<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
TBC<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
TBC<br />
<br />
=== main.c ===<br />
TBD<br />
<br />
=== FreeRTOSConfig.h ===<br />
TBD<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
TBD<br />
<br />
== Adding device drivers ==<br />
The device drivers are described in file ''ocarina_components.aadl''.<br />
<br />
TBC</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP-430&diff=520Technical topic: TASTE on MSP-4302019-12-13T15:42:25Z<p>Kgrochowski: Kgrochowski moved page Technical topic: TASTE on MSP-430 to Technical topic: TASTE on MSP-430 with FreeRTOS</p>
<hr />
<div>#REDIRECT [[Technical topic: TASTE on MSP-430 with FreeRTOS]]</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_TASTE_on_MSP430_with_FreeRTOS&diff=517Technical topic: TASTE on MSP430 with FreeRTOS2019-12-13T15:39:58Z<p>Kgrochowski: Kgrochowski moved page Kazoo and FreeRTOS to Technical topic: TASTE on MSP-430</p>
<hr />
<div>This page describes how FreeRTOS support was added to TASTE.<br />
<br />
== Hardware Description ==<br />
This article describes steps of adding support for MSP43FR5969 processor [http://www.ti.com/product/MSP430FR5969].<br />
The MSP430FR5969 LaunchPad Development Kit [http://www.ti.com/tool/MSP-EXP430FR5969] was used for testing purposes.<br />
<br />
Features of this microcontroller:<br />
* 16-bit RISC architecture;<br />
* 16‑MHz Clock;<br />
* 64KB FRAM / 2KB SRAM.<br />
<br />
<br />
== New execution platform ==<br />
Add new platform '''Platform_MSP430_FreeRTOS''' to TASTE. Follow instructions from [[Technical topic: Add a new target platform to TASTE]].<br />
TBC<br />
<br />
== Source code generation for Concurrency View ==<br />
The ''Concurrency View'' code is responsible for initialization of devices, drivers, threads and other structures.<br />
The created structures are responsible for passing information between functions and thread synchronization.<br />
Generally this code is generated by [[Ocarina]]. The generated code uses [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]] as a middleware.<br />
<br />
Kazoo templates for ''Concurrency View'' has parameters, which describes threads, mutexes, functions, etc. and relations between them.<br />
These parameters may be used to generate code without [[PolyORB-HI-Ada]] or [[PolyORB-HI-C]].<br />
This section described this approach.<br />
<br />
TBC<br />
<br />
=== Mapping of TASTE structures===<br />
The threads will be mapped to FreeRTOS tasks [https://www.freertos.org/implementing-a-FreeRTOS-task.html].<br />
<br />
The communication and synchronization between tasks will be realised using queues and semaphores or mutexes [https://www.freertos.org/Inter-Task-Communication.html].<br />
<br />
Cyclic provided interfaces of functions will be implemented using software timers [https://www.freertos.org/RTOS-software-timer.html].<br />
<br />
TBC<br />
<br />
=== main.c ===<br />
TBD<br />
<br />
=== FreeRTOSConfig.h ===<br />
TBD<br />
<br />
== Modification in Makefiles and GNAT Project Manager files ==<br />
TBD<br />
<br />
== Adding device drivers ==<br />
The device drivers are described in file ''ocarina_components.aadl''.<br />
<br />
TBC</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_and_FreeRTOS&diff=518Kazoo and FreeRTOS2019-12-13T15:39:58Z<p>Kgrochowski: Kgrochowski moved page Kazoo and FreeRTOS to Technical topic: TASTE on MSP-430</p>
<hr />
<div>#REDIRECT [[Technical topic: TASTE on MSP-430]]</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=516Kazoo2019-12-13T15:38:13Z<p>Kgrochowski: /* Adding new platform to TASTE using Kazoo */</p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons|code skeletons]] and [[#Glue code|glue code]] generation algorithms.<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code><function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code><function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code><function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code><function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code><function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_skeletons_and_glue_templates&diff=515Kazoo skeletons and glue templates2019-12-13T15:31:55Z<p>Kgrochowski: </p>
<hr />
<div>This page lists all files present in each code skeleton and glue templates. For each file it's parameters are described. Templates are processed according to [[Kazoo#Code skeletons|code skeletons]] and [[Kazoo#Glue code|glue code]] generation algorithms.<br />
<br />
Skeleton code templates are stored in <code>templates/skeletons</code> kazoo subdirectory, glue code templates are stored in <code>templates/glue/language_wrappers</code> kazoo subdirectory.<br />
<br />
For glue code templates replace <code>templates/skeletons</code> with <code>templates/glue/language_wrappers</code> in list below.<br />
<br />
=== templates/skeletons/makefile.tmplt ===<br />
This template is present only in code skeleton templates directory.<br />
This template is evaluated only once per system. The output is saved to the Makefile within output directory. <br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Function_Names<br />
|Combined table: list of fuction names...<br />
|-<br />
|Language<br />
|... and corresponding implementation language<br />
|-<br />
|Is_Type<br />
|... and flag if it is a function type<br />
|-<br />
|Has_Context_Param<br />
|... and flag to indicate if function has context parameters<br />
|-<br />
|CP_Files<br />
|List of all context parameters ASN.1 files<br />
|-<br />
|Unique_Languages<br />
|List of all languages used in the system<br />
|-<br />
|ASN1_Files<br />
|List of all ASN.1 files<br />
|-<br />
|ACN_Files<br />
|List of all ACN files<br />
|-<br />
|ASN1_Modules<br />
|List of all ASN.1 modules<br />
|}<br />
<br />
=== templates/skeletons/context-parameters.tmplt ===<br />
This template is present only in code skeleton templates directory.<br />
This template is evaluated once for every function which has context parameters. The output is saved to the file Context-<function name>.asn<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Function name<br />
|-<br />
|Sort_Set<br />
|Set of types used for this Context Parameter file<br />
|-<br />
|Module_Set<br />
|... corresponding module (needed for ASN.1 "IMPORTS")<br />
|-<br />
|CP_Name<br />
|Table of context parameter names<br />
|-<br />
|CP_Sort<br />
|... corresponding ASN.1 type<br />
|-<br />
|CP_ASN1_Module<br />
|... in ASN.1 module<br />
|-<br />
|CP_Value<br />
|... with default value<br />
|}<br />
<br />
=== templates/skeletons/sub/makefile.tmplt ===<br />
This template is processed when Makefile file name returned by [[#templates/skeletons/sub/makefile-filename.tmplt|Makefile name template]] is not empty.<br />
The output of this template is saved using selected file name in directory <code><functionname>/<languagename></code><br />
<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Function_Names<br />
|Combined table: list of function names...<br />
|-<br />
|Language<br />
|... and corresponding implementation language<br />
|-<br />
|Is_Type<br />
|... and flag if it is a function type<br />
|-<br />
|Has_Context_Param<br />
|... and flag to indicate if function has context parameters<br />
|-<br />
|CP_Files<br />
|List of all context parameters ASN.1 files<br />
|-<br />
|Unique_Languages<br />
|List of all languages used in the system<br />
|-<br />
|ASN1_Files<br />
|List of all ASN.1 files<br />
|-<br />
|ACN_Files<br />
|List of all ACN files<br />
|-<br />
|ASN1_Modules<br />
|List of all ASN.1 modules<br />
|}<br />
<br />
=== templates/skeletons/sub/trigger.tmplt ===<br />
This template is evaluated to check if other files from given directory should be processed.<br />
If the result of evaluation is equal to "TRUE", then other files will be processed.<br />
This template is identical for Skeleton and Glue subfolders.<br />
<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|-<br />
|Is_Type<br />
|True if function type<br />
|-<br />
|Instance_Of<br />
|Name of instance or empty string<br />
|-<br />
|Language<br />
|Implementation language for the function<br />
|-<br />
|Filename_Is_Present<br />
|True if target function output already exists<br />
|-<br />
|Makefile_Is_Present<br />
|True if target build script already exists<br />
|-<br />
|Zip_File<br />
|Optional path to zip file<br />
|-<br />
|Use_POHIC<br />
|Command line configuration<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timers<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Async_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Sync_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Has_Context<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|PIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Filenames<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/skeletons/sub/makefile-filename.tmplt ===<br />
This file is optional, if it exists the result of processing is a file name for the output of [[#templates/skeletons/sub/makefile.tmplt|Makefile template]], otherwise file name will be empty.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|}<br />
<br />
=== templates/skeletons/sub/function-filename.tmplt ===<br />
This file is optional, if it exists the result of processing is a file name for the output of [[#templates/skeletons/sub/function.tmplt|function template]], otherwise file name will be empty.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|}<br />
<br />
=== templates/skeletons/sub/interface.tmplt ===<br />
This file is processed for each required and provided interfaces of the function. Results of processing are passed to [[#templates/skeletons/sub/function.tmplt|function template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Direction<br />
|"PI" or "RI"<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Language<br />
|The implementation language of the function<br />
|-<br />
|Property_Names<br />
|All AADL properties (names) associated to the function<br />
|-<br />
|Property_Values<br />
|... and corresponding values<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
| |_ Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
| |_ Corresponding direction<br />
|-<br />
|Param_Encodings<br />
| |_ Corresponding ASN.1 encoding<br />
|-<br />
|Is_Timer<br />
|Flag set to true if this is a timer interface<br />
|-<br />
|Period<br />
|Property of the interface<br />
|-<br />
|WCET<br />
|Property of the interface<br />
|-<br />
|Queue_Size<br />
|Property of the interface<br />
|-<br />
|IF_Property_Names<br />
| and Values User-defined properties (vector tag)<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/skeletons/sub/function.tmplt ===<br />
This template is processed when function-filename.tmplt exists.<br />
The output of this template is save to the file with name returned by processing function-filename.tmplt in directory [functionname]/[languagename]/src.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|-<br />
|Language<br />
|The implementation language<br />
|-<br />
|List_Of_PIs<br />
|List of all Provided Interfaces (just names)<br />
|-<br />
|List_Of_RIs<br />
|List of all Required Interfaces (just names)<br />
|-<br />
|List_Of_Sync_PIs<br />
|List of synchronous Provided Interfaces<br />
|-<br />
|List_Of_Sync_RIs<br />
|List of synchronous Required Interfaces<br />
|-<br />
|List_Of_ASync_PIs<br />
|List of asynchronous Provided Interfaces<br />
|-<br />
|List_Of_ASync_RIs<br />
|List of asynchronous Required Interfaces<br />
|-<br />
|ASN1_Modules<br />
|List of ASN.1 Modules names<br />
|-<br />
|ASN1_Files<br />
|List of ASN.1 Files with path<br />
|-<br />
|Timers<br />
|List of timers (just names)<br />
|-<br />
|Has_Context<br />
|Flag, True if there are context parameters<br />
|-<br />
|CP_Names<br />
|List of Context Parameter names<br />
|-<br />
|CP_Types<br />
|List of Context Parameter types<br />
|-<br />
|Provided_Interfaces<br />
|From template: Provided interfaces with params<br />
|-<br />
|Required_Interfaces<br />
|From template: Required interfaces with params<br />
|-<br />
|Property_Names<br />
|List of User-defined properties (names)<br />
|-<br />
|Property_Values<br />
|List of User-defined properties (values)<br />
|-<br />
|Is_Type Flag<br />
|True if function is a component type<br />
|-<br />
|Instance_Of<br />
|Optional name of component type<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_concurrency_view_templates&diff=514Kazoo concurrency view templates2019-12-13T15:28:38Z<p>Kgrochowski: </p>
<hr />
<div>This page lists all files present in each Concurrency View templates. For each file it's parameters are described. Templates are processed according to [[Kazoo#Concurrency View|Concurrency View template]] processing algorithm.<br />
<br />
Skeleton code templates are stored in <code>templates/concurrency_view</code> kazoo subdirectory.<br />
<br />
=== templates/concurrency_view/sub/trigger.tmplt ===<br />
This file is processed for every node. The result of this file indicates if the rest of files for given node will be processed.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Filename_Is_Present<br />
|true if file with name returned by filenode.tmplt exists<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/thread.tmplt ===<br />
This file is processed for every thread in every partition in every node.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Thread_Name<br />
|Thread name<br />
|-<br />
|Partition_Name<br />
|Partition containing this thread<br />
|-<br />
|Entry_Port_Name<br />
|Name of the PI<br />
|-<br />
|RCM<br />
|One of "CYCLIC_OPERATION", "SPORADIC_OPERATION"<br />
|-<br />
|Need_Mutex<br />
|True if the PI is shared with others in the protected block<br />
|-<br />
|Pro_Block_Name<br />
|Name of the protected function<br />
|-<br />
|Node_Name<br />
|Name of the deployment node<br />
|-<br />
|Remote_Threads<br />
|Vector tag: output remote thread list<br />
|-<br />
|Remote_PIs<br />
| |_ Associated PI Name<br />
|-<br />
|Remote_PI_Sorts<br />
| |_ Optional param type of the remote thread<br />
|-<br />
|Remote_PI_Modules<br />
| |_ Asn1 module of the optional param type<br />
|-<br />
|Name<br />
|<br />
|-<br />
|Kind<br />
|<br />
|-<br />
|Parent_Function<br />
|Tags related to the PI that is at the origin of the thread creation: shoud be useless here<br />
|-<br />
|Param_Names<br />
|<br />
|-<br />
|Period<br />
|<br />
|-<br />
|WCET<br />
|<br />
|-<br />
|Queue_Size<br />
|relevant here<br />
|-<br />
|IF_Property_Names<br />
|<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RI_Port_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Directions<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/pi.tmplt ===<br />
This file is evaluated for every protected and unprotected provided interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#templates/concurrency_view/sub/block.tmplt|block template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
| |_ Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
| |_ Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Protected_Block_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Caller_Is_Local<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/ri.tmplt ===<br />
This file is evaluated for every required interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#templates/concurrency_view/sub/block.tmplt|block template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
|Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
|Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/block.tmplt ===<br />
This file is evaluated for every block.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Protected block name<br />
|-<br />
|Language<br />
|Implementation language<br />
|-<br />
|Calling_Threads<br />
|List of calling threads<br />
|-<br />
|Protected_PIs<br />
|Protected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Unprotected_PIs<br />
|Unprotected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Required<br />
|Required interfaces (from ri.tmplt)<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Zip_File<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|PIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Async_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Sync_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Has_Context<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timers<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Filenames<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/partition.tmplt ===<br />
This file is evaluated for every partition.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Partition name (usually the name of the binary)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|Tag: list of thread names<br />
|-<br />
|Node_Name<br />
|Name of the node containing this partition<br />
|-<br />
|Blocks<br />
|Code generated for protected functions<br />
|-<br />
|Block_Names<br />
|Tag: list of block (user functions) names<br />
|-<br />
|Coverage<br />
|True if user requested code coverage enable<br />
|-<br />
|Package_Name<br />
|AADL Package name for the target (e.g. ocarina_porocessors_x86)<br />
|-<br />
|CPU_Name<br />
|CPU AADL Identifier (e.g. x86_inst)<br />
|-<br />
|CPU_Family<br />
|CPU Kind (e.g. leon3)<br />
|-<br />
|CPU_Instance<br />
|AADL component instance (e.g. rtems_posix)<br />
|-<br />
|CPU_Platform<br />
|AADL CPU_Platform (e.g. PLATFORM_NATIVE)<br />
|-<br />
|CPU_Classifier<br />
|AADL CPU Classifier (e.g. ocarina_processors_x86::x86.linux)<br />
|-<br />
|VP_Name<br />
|Virtual processor name on which the partition is bounded<br />
|-<br />
|VP_Platform<br />
|Virtual processor platform (e.g. PLATFORM_AIR)<br />
|-<br />
|VP_Classifier<br />
|Virtual processor classifier<br />
|-<br />
|Bound_Functions<br />
|List of user functions from Interface view<br />
|-<br />
|Thread_Src_Name<br />
|Vector tag : connection thread name (source)<br />
|-<br />
|Thread_Dst_Name<br />
|Vector tag : connection thread name (dest)<br />
|-<br />
|Thread_Src_Port<br />
|Vector tag : connection port name (source)<br />
|-<br />
|Thread_Dst_Port<br />
|Vector tag : connection port name (dest)<br />
|-<br />
|In_Port_Names<br />
|Vector tag: input ports of the partition<br />
|-<br />
|In_Port_Thread_Name<br />
| |_ corresponding thread inside the partition<br />
|-<br />
|In_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Out_Port_Names<br />
|Vector tag: output ports of the partition<br />
|-<br />
|Out_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Part_Out_Port_Name<br />
|Vector tag: output ports of the partition (can be several times the same)<br />
|-<br />
|Connected_Threads<br />
| |_ Corresponding thread connected to it<br />
|-<br />
|Block_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Duration<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Memory_Region<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Thread_Has_Param<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/node.tmplt ===<br />
This file is evaluated for every node. The result of this file is saved to the file with name returned by [[#templates/concurrency_view/sub/filenode.tmplt|filenode.tmplt]]. The result is also used as a parameter for [[#templates/concurrency_view/sub/system.tmplt|system.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Node_Name<br />
|Name of the node from deployment view<br />
|-<br />
|Partition_Names<br />
|Tag listing the partitions in this node<br />
|-<br />
|Has_Memory<br />
|Boolean flag indicating that a memory is defined for this node<br />
|-<br />
|Partitions<br />
|List of rendered code for partitions<br />
|-<br />
|VP_Names<br />
|Vector tag: list of virtual processors on this node<br />
|-<br />
|VP_Package_Names<br />
| |_ Corresponding package name<br />
|-<br />
|VP_Platforms<br />
| |_ Corresponding platform name<br />
|-<br />
|VP_Classifiers<br />
| |_ Corresponding aadl classifier<br />
|-<br />
|CPU_Platform<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Instance<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Classifier<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Family<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/system.tmplt ===<br />
This file is evaluated for every node. The result of the evaluation are stored to the file with name returned by <br />
[[#templates/concurrency_view/sub/filesys.tmplt|filesys.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Nodes<br />
|Code generated for the nodes<br />
|-<br />
|Node_Names<br />
|Vector Tag of node names<br />
|-<br />
|Node_CPU<br />
|Corresponding CPU name (eg x86_linux)<br />
|-<br />
|Node_CPU_Classifier<br />
|CPU Classifier (ocarina...::x86_linux)<br />
|-<br />
|Node_Major_Frame<br />
|Time in milliseconds allocated to the CPU (TSP only)<br />
|-<br />
|Partition_Names<br />
|Vector Tag of partition names<br />
|-<br />
|Partition_Node<br />
|Corresponding node name<br />
|-<br />
|Partition_CPU<br />
|Corresponding CPU name<br />
|-<br />
|Partition_Duration<br />
|Corresponding time allocation (TSP only)<br />
|-<br />
|Partition_VP<br />
|Virtual processor binding (TSP only)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|List of all threads in the complete system<br />
|-<br />
|Target_Packages<br />
|List of all target package names in the complete system<br />
|-<br />
|Part_Source_Name<br />
|Inter-partition connections : partition source name (vector tag)<br />
|-<br />
|Part_Source_Port<br />
| |_ Corresponding port name<br />
|-<br />
|Part_Dest_Name<br />
| |_ Corresponding name of the remote partition<br />
|-<br />
|Part_Dest_Port<br />
| |_ Corresponding name of the port on the remote partition<br />
|-<br />
|Bus_Names<br />
|Vector tag: busses present in the system<br />
|-<br />
|Bus_AADL_Package<br />
| |_ corresponding AADL Package<br />
|-<br />
|Bus_Classifier<br />
| |_ corresponding AADL classifier<br />
|-<br />
|Device_Node_Name<br />
|<br />
|-<br />
|Device_Partition<br />
|-<br />
|Device_AADL_Pkg<br />
|<br />
|-<br />
|Device_Classifier<br />
|<br />
|-<br />
|Device_CPU<br />
|<br />
|-<br />
|Device_Config<br />
|<br />
|-<br />
|Device_Bus_Name<br />
|<br />
|-<br />
|Device_Port_Name<br />
|<br />
|-<br />
|Device_ASN1_File<br />
|<br />
|-<br />
|Device_ASN1_Sort<br />
|<br />
|-<br />
|Device_ASN1_Module<br />
|Device drivers (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Files<br />
|List of ASN.1 files/module/type for device configuration with no duplicates (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Mod<br />
| |_ corresponding asn1 module<br />
|-<br />
|Unique_Dev_ASN1_Sorts<br />
| |_ type name<br />
|-<br />
|Connect_From_Part<br />
|Vector tag - bus connection: partition source<br />
|-<br />
|Connect_Via_Bus<br />
| |_ bus name<br />
|-<br />
|Connect_Port_Name<br />
| |_ port name<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Has_Memory<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Device_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== templates/concurrency_view/sub/fileblock.tmplt ===<br />
TODO<br />
<br />
=== templates/concurrency_view/sub/filenode.tmplt ===<br />
TODO<br />
<br />
=== templates/concurrency_view/sub/filepart.tmplt ===<br />
TODO<br />
<br />
=== templates/concurrency_view/sub/filesys.tmplt ===<br />
TODO<br />
<br />
=== templates/concurrency_view/sub/filethread.tmplt ===<br />
TODO</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_concurrency_view_templates&diff=512Kazoo concurrency view templates2019-12-13T14:57:41Z<p>Kgrochowski: </p>
<hr />
<div>This page lists all files present in each Concurrency View templates. For each file it's parameters are described. Templates are processed according to [[Kazoo#Concurrency View|Concurrency View template]] processing algorithm.<br />
<br />
Skeleton code templates are stored in <code>templates/concurrency_view</code> kazoo subdirectory.<br />
<br />
=== <tmeplate-subdir>/trigger.tmplt ===<br />
This file is processed for every node. The result of this file indicates if the rest of files for given node will be processed.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Filename_Is_Present<br />
|true if file with name returned by filenode.tmplt exists<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/thread.tmplt ===<br />
This file is processed for every thread in every partition in every node.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Thread_Name<br />
|Thread name<br />
|-<br />
|Partition_Name<br />
|Partition containing this thread<br />
|-<br />
|Entry_Port_Name<br />
|Name of the PI<br />
|-<br />
|RCM<br />
|One of "CYCLIC_OPERATION", "SPORADIC_OPERATION"<br />
|-<br />
|Need_Mutex<br />
|True if the PI is shared with others in the protected block<br />
|-<br />
|Pro_Block_Name<br />
|Name of the protected function<br />
|-<br />
|Node_Name<br />
|Name of the deployment node<br />
|-<br />
|Remote_Threads<br />
|Vector tag: output remote thread list<br />
|-<br />
|Remote_PIs<br />
| |_ Associated PI Name<br />
|-<br />
|Remote_PI_Sorts<br />
| |_ Optional param type of the remote thread<br />
|-<br />
|Remote_PI_Modules<br />
| |_ Asn1 module of the optional param type<br />
|-<br />
|Name<br />
|<br />
|-<br />
|Kind<br />
|<br />
|-<br />
|Parent_Function<br />
|Tags related to the PI that is at the origin of the thread creation: shoud be useless here<br />
|-<br />
|Param_Names<br />
|<br />
|-<br />
|Period<br />
|<br />
|-<br />
|WCET<br />
|<br />
|-<br />
|Queue_Size<br />
|relevant here<br />
|-<br />
|IF_Property_Names<br />
|<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RI_Port_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Directions<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/pi.tmplt ===<br />
This file is evaluated for every protected and unprotected provided interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#<template_subdir>/block.tmplt|block template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
| |_ Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
| |_ Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Protected_Block_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Caller_Is_Local<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/ri.tmplt ===<br />
This file is evaluated for every required interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#<template_subdir>/block.tmplt|block template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
|Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
|Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/block.tmplt ===<br />
This file is evaluated for every block.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Protected block name<br />
|-<br />
|Language<br />
|Implementation language<br />
|-<br />
|Calling_Threads<br />
|List of calling threads<br />
|-<br />
|Protected_PIs<br />
|Protected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Unprotected_PIs<br />
|Unprotected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Required<br />
|Required interfaces (from ri.tmplt)<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Zip_File<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|PIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Async_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Sync_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Has_Context<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timers<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Filenames<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/partition.tmplt ===<br />
This file is evaluated for every partition.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Partition name (usually the name of the binary)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|Tag: list of thread names<br />
|-<br />
|Node_Name<br />
|Name of the node containing this partition<br />
|-<br />
|Blocks<br />
|Code generated for protected functions<br />
|-<br />
|Block_Names<br />
|Tag: list of block (user functions) names<br />
|-<br />
|Coverage<br />
|True if user requested code coverage enable<br />
|-<br />
|Package_Name<br />
|AADL Package name for the target (e.g. ocarina_porocessors_x86)<br />
|-<br />
|CPU_Name<br />
|CPU AADL Identifier (e.g. x86_inst)<br />
|-<br />
|CPU_Family<br />
|CPU Kind (e.g. leon3)<br />
|-<br />
|CPU_Instance<br />
|AADL component instance (e.g. rtems_posix)<br />
|-<br />
|CPU_Platform<br />
|AADL CPU_Platform (e.g. PLATFORM_NATIVE)<br />
|-<br />
|CPU_Classifier<br />
|AADL CPU Classifier (e.g. ocarina_processors_x86::x86.linux)<br />
|-<br />
|VP_Name<br />
|Virtual processor name on which the partition is bounded<br />
|-<br />
|VP_Platform<br />
|Virtual processor platform (e.g. PLATFORM_AIR)<br />
|-<br />
|VP_Classifier<br />
|Virtual processor classifier<br />
|-<br />
|Bound_Functions<br />
|List of user functions from Interface view<br />
|-<br />
|Thread_Src_Name<br />
|Vector tag : connection thread name (source)<br />
|-<br />
|Thread_Dst_Name<br />
|Vector tag : connection thread name (dest)<br />
|-<br />
|Thread_Src_Port<br />
|Vector tag : connection port name (source)<br />
|-<br />
|Thread_Dst_Port<br />
|Vector tag : connection port name (dest)<br />
|-<br />
|In_Port_Names<br />
|Vector tag: input ports of the partition<br />
|-<br />
|In_Port_Thread_Name<br />
| |_ corresponding thread inside the partition<br />
|-<br />
|In_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Out_Port_Names<br />
|Vector tag: output ports of the partition<br />
|-<br />
|Out_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Part_Out_Port_Name<br />
|Vector tag: output ports of the partition (can be several times the same)<br />
|-<br />
|Connected_Threads<br />
| |_ Corresponding thread connected to it<br />
|-<br />
|Block_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Duration<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Memory_Region<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Thread_Has_Param<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/node.tmplt ===<br />
This file is evaluated for every node. The result of this file is saved to the file with name returned by [[#<template_subdir>/filenode.tmplt|filenode.tmplt]]. The result is also used as a parameter for [[#<template_subdir>/system.tmplt|system.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Node_Name<br />
|Name of the node from deployment view<br />
|-<br />
|Partition_Names<br />
|Tag listing the partitions in this node<br />
|-<br />
|Has_Memory<br />
|Boolean flag indicating that a memory is defined for this node<br />
|-<br />
|Partitions<br />
|List of rendered code for partitions<br />
|-<br />
|VP_Names<br />
|Vector tag: list of virtual processors on this node<br />
|-<br />
|VP_Package_Names<br />
| |_ Corresponding package name<br />
|-<br />
|VP_Platforms<br />
| |_ Corresponding platform name<br />
|-<br />
|VP_Classifiers<br />
| |_ Corresponding aadl classifier<br />
|-<br />
|CPU_Platform<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Instance<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Classifier<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Family<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/system.tmplt ===<br />
This file is evaluated for every node. The result of the evaluation are stored to the file with name returned by <br />
[[#<template_subdir>/filesys.tmplt|filesys.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Nodes<br />
|Code generated for the nodes<br />
|-<br />
|Node_Names<br />
|Vector Tag of node names<br />
|-<br />
|Node_CPU<br />
|Corresponding CPU name (eg x86_linux)<br />
|-<br />
|Node_CPU_Classifier<br />
|CPU Classifier (ocarina...::x86_linux)<br />
|-<br />
|Node_Major_Frame<br />
|Time in milliseconds allocated to the CPU (TSP only)<br />
|-<br />
|Partition_Names<br />
|Vector Tag of partition names<br />
|-<br />
|Partition_Node<br />
|Corresponding node name<br />
|-<br />
|Partition_CPU<br />
|Corresponding CPU name<br />
|-<br />
|Partition_Duration<br />
|Corresponding time allocation (TSP only)<br />
|-<br />
|Partition_VP<br />
|Virtual processor binding (TSP only)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|List of all threads in the complete system<br />
|-<br />
|Target_Packages<br />
|List of all target package names in the complete system<br />
|-<br />
|Part_Source_Name<br />
|Inter-partition connections : partition source name (vector tag)<br />
|-<br />
|Part_Source_Port<br />
| |_ Corresponding port name<br />
|-<br />
|Part_Dest_Name<br />
| |_ Corresponding name of the remote partition<br />
|-<br />
|Part_Dest_Port<br />
| |_ Corresponding name of the port on the remote partition<br />
|-<br />
|Bus_Names<br />
|Vector tag: busses present in the system<br />
|-<br />
|Bus_AADL_Package<br />
| |_ corresponding AADL Package<br />
|-<br />
|Bus_Classifier<br />
| |_ corresponding AADL classifier<br />
|-<br />
|Device_Node_Name<br />
|<br />
|-<br />
|Device_Partition<br />
|-<br />
|Device_AADL_Pkg<br />
|<br />
|-<br />
|Device_Classifier<br />
|<br />
|-<br />
|Device_CPU<br />
|<br />
|-<br />
|Device_Config<br />
|<br />
|-<br />
|Device_Bus_Name<br />
|<br />
|-<br />
|Device_Port_Name<br />
|<br />
|-<br />
|Device_ASN1_File<br />
|<br />
|-<br />
|Device_ASN1_Sort<br />
|<br />
|-<br />
|Device_ASN1_Module<br />
|Device drivers (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Files<br />
|List of ASN.1 files/module/type for device configuration with no duplicates (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Mod<br />
| |_ corresponding asn1 module<br />
|-<br />
|Unique_Dev_ASN1_Sorts<br />
| |_ type name<br />
|-<br />
|Connect_From_Part<br />
|Vector tag - bus connection: partition source<br />
|-<br />
|Connect_Via_Bus<br />
| |_ bus name<br />
|-<br />
|Connect_Port_Name<br />
| |_ port name<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Has_Memory<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Device_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/fileblock.tmplt ===<br />
TODO<br />
<br />
=== <template_subdir>/filenode.tmplt ===<br />
TODO<br />
<br />
=== <template_subdir>/filepart.tmplt ===<br />
TODO<br />
<br />
=== <template_subdir>/filesys.tmplt ===<br />
TODO<br />
<br />
=== <template_subdir>/filethread.tmplt ===<br />
TODO</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_concurrency_view_templates&diff=511Kazoo concurrency view templates2019-12-13T14:48:06Z<p>Kgrochowski: </p>
<hr />
<div>This page lists all files present in each Concurrency View templates. For each file it's parameters are described. Templates are processed according to [[Kazoo#Concurrency View|Concurrency View template]] processing algorithm.<br />
<br />
Skeleton code templates are stored in <code>templates/concurrency_view</code> kazoo subdirectory.<br />
<br />
=== <tmeplate-subdir>/trigger.tmplt ===<br />
This file is processed for every node. The result of this file indicates if the rest of files for given node will be processed.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Filename_Is_Present<br />
|true if file with name returned by filenode.tmplt exists<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/thread.tmplt ===<br />
This file is processed for every thread in every partition in every node.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Thread_Name<br />
|Thread name<br />
|-<br />
|Partition_Name<br />
|Partition containing this thread<br />
|-<br />
|Entry_Port_Name<br />
|Name of the PI<br />
|-<br />
|RCM<br />
|One of "CYCLIC_OPERATION", "SPORADIC_OPERATION"<br />
|-<br />
|Need_Mutex<br />
|True if the PI is shared with others in the protected block<br />
|-<br />
|Pro_Block_Name<br />
|Name of the protected function<br />
|-<br />
|Node_Name<br />
|Name of the deployment node<br />
|-<br />
|Remote_Threads<br />
|Vector tag: output remote thread list<br />
|-<br />
|Remote_PIs<br />
| |_ Associated PI Name<br />
|-<br />
|Remote_PI_Sorts<br />
| |_ Optional param type of the remote thread<br />
|-<br />
|Remote_PI_Modules<br />
| |_ Asn1 module of the optional param type<br />
|-<br />
|Name<br />
|<br />
|-<br />
|Kind<br />
|<br />
|-<br />
|Parent_Function<br />
|Tags related to the PI that is at the origin of the thread creation: shoud be useless here<br />
|-<br />
|Param_Names<br />
|<br />
|-<br />
|Period<br />
|<br />
|-<br />
|WCET<br />
|<br />
|-<br />
|Queue_Size<br />
|relevant here<br />
|-<br />
|IF_Property_Names<br />
|<br />
|-<br />
|Skeletons<br />
|from kazoo configuration<br />
|-<br />
|Glue<br />
|from kazoo configuration<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RI_Port_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Directions<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/pi.tmplt ===<br />
This file is evaluated for every protected and unprotected provided interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#<template_subdir>/block.tmplt|block template]]<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
| |_ Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
| |_ Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Protected_Block_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Caller_Is_Local<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/ri.tmplt ===<br />
This file is evaluated for every required interface.<br />
The result of every evaluation is joined to single string and passed as a parameter to [[#<template_subdir>/block.tmplt|block template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
|Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
|Corresponding direction<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Language<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_Encodings<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Period<br />
|DOCUMENTATION MISSING<br />
|-<br />
|WCET<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Queue_Size<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Timer<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Calling_Threads<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/block.tmplt ===<br />
This file is evaluated for every block.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Protected block name<br />
|-<br />
|Language<br />
|Implementation language<br />
|-<br />
|Calling_Threads<br />
|List of calling threads<br />
|-<br />
|Protected_PIs<br />
|Protected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Unprotected_PIs<br />
|Unprotected Provided interfaces (from pi.tmplt)<br />
|-<br />
|Required<br />
|Required interfaces (from ri.tmplt)<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Zip_File<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|PIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Is_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Partition_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Async_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Sync_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Has_Context<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timers<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Filenames<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/partition.tmplt ===<br />
This file is evaluated for every partition.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Partition name (usually the name of the binary)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|Tag: list of thread names<br />
|-<br />
|Node_Name<br />
|Name of the node containing this partition<br />
|-<br />
|Blocks<br />
|Code generated for protected functions<br />
|-<br />
|Block_Names<br />
|Tag: list of block (user functions) names<br />
|-<br />
|Coverage<br />
|True if user requested code coverage enable<br />
|-<br />
|Package_Name<br />
|AADL Package name for the target (e.g. ocarina_porocessors_x86)<br />
|-<br />
|CPU_Name<br />
|CPU AADL Identifier (e.g. x86_inst)<br />
|-<br />
|CPU_Family<br />
|CPU Kind (e.g. leon3)<br />
|-<br />
|CPU_Instance<br />
|AADL component instance (e.g. rtems_posix)<br />
|-<br />
|CPU_Platform<br />
|AADL CPU_Platform (e.g. PLATFORM_NATIVE)<br />
|-<br />
|CPU_Classifier<br />
|AADL CPU Classifier (e.g. ocarina_processors_x86::x86.linux)<br />
|-<br />
|VP_Name<br />
|Virtual processor name on which the partition is bounded<br />
|-<br />
|VP_Platform<br />
|Virtual processor platform (e.g. PLATFORM_AIR)<br />
|-<br />
|VP_Classifier<br />
|Virtual processor classifier<br />
|-<br />
|Bound_Functions<br />
|List of user functions from Interface view<br />
|-<br />
|Thread_Src_Name<br />
|Vector tag : connection thread name (source)<br />
|-<br />
|Thread_Dst_Name<br />
|Vector tag : connection thread name (dest)<br />
|-<br />
|Thread_Src_Port<br />
|Vector tag : connection port name (source)<br />
|-<br />
|Thread_Dst_Port<br />
|Vector tag : connection port name (dest)<br />
|-<br />
|In_Port_Names<br />
|Vector tag: input ports of the partition<br />
|-<br />
|In_Port_Thread_Name<br />
| |_ corresponding thread inside the partition<br />
|-<br />
|In_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Out_Port_Names<br />
|Vector tag: output ports of the partition<br />
|-<br />
|Out_Port_Type_Name<br />
| |_ corresponding parameter type name (optional)<br />
|-<br />
|Part_Out_Port_Name<br />
|Vector tag: output ports of the partition (can be several times the same)<br />
|-<br />
|Connected_Threads<br />
| |_ Corresponding thread connected to it<br />
|-<br />
|Block_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Duration<br />
|DOCUMENTATION MISSING<br />
|-<br />
|VP_Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Memory_Region<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Instance_Of<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Thread_Has_Param<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/node.tmplt ===<br />
This file is evaluated for every node. The result of this file is saved to the file with name returned by [[#<template_subdir>/filenode.tmplt|filenode.tmplt]]. The result is also used as a parameter for [[#<template_subdir>/system.tmplt|system.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Node_Name<br />
|Name of the node from deployment view<br />
|-<br />
|Partition_Names<br />
|Tag listing the partitions in this node<br />
|-<br />
|Has_Memory<br />
|Boolean flag indicating that a memory is defined for this node<br />
|-<br />
|Partitions<br />
|List of rendered code for partitions<br />
|-<br />
|VP_Names<br />
|Vector tag: list of virtual processors on this node<br />
|-<br />
|VP_Package_Names<br />
| |_ Corresponding package name<br />
|-<br />
|VP_Platforms<br />
| |_ Corresponding platform name<br />
|-<br />
|VP_Classifiers<br />
| |_ Corresponding aadl classifier<br />
|-<br />
|CPU_Platform<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Instance<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Ada_Runtime<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Classifier<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Package_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CPU_Family<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template_subdir>/system.tmplt ===<br />
This file is evaluated for every node. The result of the evaluation are stored to the file with name returned by <br />
[[#<template_subdir>/filesys.tmplt|filesys.tmplt]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Nodes<br />
|Code generated for the nodes<br />
|-<br />
|Node_Names<br />
|Vector Tag of node names<br />
|-<br />
|Node_CPU<br />
|Corresponding CPU name (eg x86_linux)<br />
|-<br />
|Node_CPU_Classifier<br />
|CPU Classifier (ocarina...::x86_linux)<br />
|-<br />
|Node_Major_Frame<br />
|Time in milliseconds allocated to the CPU (TSP only)<br />
|-<br />
|Partition_Names<br />
|Vector Tag of partition names<br />
|-<br />
|Partition_Node<br />
|Corresponding node name<br />
|-<br />
|Partition_CPU<br />
|Corresponding CPU name<br />
|-<br />
|Partition_Duration<br />
|Corresponding time allocation (TSP only)<br />
|-<br />
|Partition_VP<br />
|Virtual processor binding (TSP only)<br />
|-<br />
|Threads<br />
|Code generated for the threads<br />
|-<br />
|Thread_Names<br />
|List of all threads in the complete system<br />
|-<br />
|Target_Packages<br />
|List of all target package names in the complete system<br />
|-<br />
|Part_Source_Name<br />
|Inter-partition connections : partition source name (vector tag)<br />
|-<br />
|Part_Source_Port<br />
| |_ Corresponding port name<br />
|-<br />
|Part_Dest_Name<br />
| |_ Corresponding name of the remote partition<br />
|-<br />
|Part_Dest_Port<br />
| |_ Corresponding name of the port on the remote partition<br />
|-<br />
|Bus_Names<br />
|Vector tag: busses present in the system<br />
|-<br />
|Bus_AADL_Package<br />
| |_ corresponding AADL Package<br />
|-<br />
|Bus_Classifier<br />
| |_ corresponding AADL classifier<br />
|-<br />
|Device_Node_Name<br />
|<br />
|-<br />
|Device_Partition<br />
|-<br />
|Device_AADL_Pkg<br />
|<br />
|-<br />
|Device_Classifier<br />
|<br />
|-<br />
|Device_CPU<br />
|<br />
|-<br />
|Device_Config<br />
|<br />
|-<br />
|Device_Bus_Name<br />
|<br />
|-<br />
|Device_Port_Name<br />
|<br />
|-<br />
|Device_ASN1_File<br />
|<br />
|-<br />
|Device_ASN1_Sort<br />
|<br />
|-<br />
|Device_ASN1_Module<br />
|Device drivers (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Files<br />
|List of ASN.1 files/module/type for device configuration with no duplicates (vector tag)<br />
|-<br />
|Unique_Dev_ASN1_Mod<br />
| |_ corresponding asn1 module<br />
|-<br />
|Unique_Dev_ASN1_Sorts<br />
| |_ type name<br />
|-<br />
|Connect_From_Part<br />
|Vector tag - bus connection: partition source<br />
|-<br />
|Connect_Via_Bus<br />
| |_ bus name<br />
|-<br />
|Connect_Port_Name<br />
| |_ port name<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Node_Has_Memory<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Device_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Block_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Use_POHIC<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo_skeletons_and_glue_templates&diff=510Kazoo skeletons and glue templates2019-12-13T14:37:26Z<p>Kgrochowski: </p>
<hr />
<div>This page lists all files present in each code skeleton and glue templates. For each file it's parameters are described. Templates are processed according to [[Kazoo#Code skeletons|code skeletons]] and [[Kazoo#Glue code|glue code]] generation algorithms.<br />
<br />
Skeleton code templates are stored in <code>templates/skeletons</code> kazoo subdirectory, glue code templates are stored in <code>templates/glue/language_wrappers</code> kazoo subdirectory.<br />
<br />
=== makefile.tmplt ===<br />
This template is present only in code skeleton templates directory.<br />
This template is evaluated only once per system. The output is saved to the Makefile within output directory. <br />
<br />
=== context-parameters.tmplt ===<br />
This template is present only in code skeleton templates directory.<br />
This template is evaluated once for every function which has context parameters. The output is saved to the file Context-<function name>.asn<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|Function name<br />
|-<br />
|Sort_Set<br />
|Set of types used for this Context Parameter file<br />
|-<br />
|Module_Set<br />
|... corresponding module (needed for ASN.1 "IMPORTS")<br />
|-<br />
|CP_Name<br />
|Table of context parameter names<br />
|-<br />
|CP_Sort<br />
|... corresponding ASN.1 type<br />
|-<br />
|CP_ASN1_Module<br />
|... in ASN.1 module<br />
|-<br />
|CP_Value<br />
|... with default value<br />
|}<br />
<br />
=== <template-subdir>/makefile.tmplt ===<br />
This template is processed when Makefile file name returned by [[#<template-subdir>/makefile-filename.tmplt|Makefile name template]] is not empty.<br />
The output of this template is saved using selected file name in directory <code><functionname>/<languagename></code><br />
<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Function_Names<br />
|Combined table: list of function names...<br />
|-<br />
|Language<br />
|... and corresponding implementation language<br />
|-<br />
|Is_Type<br />
|... and flag if it is a function type<br />
|-<br />
|Has_Context_Param<br />
|... and flag to indicate if function has context parameters<br />
|-<br />
|CP_Files<br />
|List of all context parameters ASN.1 files<br />
|-<br />
|Unique_Languages<br />
|List of all languages used in the system<br />
|-<br />
|ASN1_Files<br />
|List of all ASN.1 files<br />
|-<br />
|ACN_Files<br />
|List of all ACN files<br />
|-<br />
|ASN1_Modules<br />
|List of all ASN.1 modules<br />
|}<br />
<br />
=== <template-subdir>/trigger.tmplt ===<br />
This template is evaluated to check if other files from given directory should be processed.<br />
If the result of evaluation is equal to "TRUE", then other files will be processed.<br />
This template is identical for Skeleton and Glue subfolders.<br />
<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|-<br />
|Is_Type<br />
|True if function type<br />
|-<br />
|Instance_Of<br />
|Name of instance or empty string<br />
|-<br />
|Language<br />
|Implementation language for the function<br />
|-<br />
|Filename_Is_Present<br />
|True if target function output already exists<br />
|-<br />
|Makefile_Is_Present<br />
|True if target build script already exists<br />
|-<br />
|Zip_File<br />
|Optional path to zip file<br />
|-<br />
|Use_POHIC<br />
|Command line configuration<br />
|-<br />
|Deployment_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Interface_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Binary_Path<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Output_Dir<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Skeletons<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timers<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_ASync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|RIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Types<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Async_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Sync_RIs_Parent<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Other_Files<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_RI_Param_Name<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Debug_Flag<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Timer_Resolution<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_RIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Glue<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Property_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|List_Of_Sync_PIs<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Has_Context<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Check_Data_View<br />
|DOCUMENTATION MISSING<br />
|-<br />
|PIs_Have_Params<br />
|DOCUMENTATION MISSING<br />
|-<br />
|CP_Asn1Filenames<br />
|DOCUMENTATION MISSING<br />
|-<br />
|ASync_PI_Param_Type<br />
|DOCUMENTATION MISSING<br />
|-<br />
|No_Stdlib_Flag<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template-subdir>/makefile-filename.tmplt ===<br />
This file is optional, if it exists the result of processing is a file name for the output of [[#makefile.tmplt|Makefile template]], otherwise file name will be empty.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|}<br />
<br />
=== <template-subdir>/function-filename.tmplt ===<br />
This file is optional, if it exists the result of processing is a file name for the output of [[#<template-subdir>/function.tmplt|function template]], otherwise file name will be empty.<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the function<br />
|}<br />
<br />
=== <template-subdir>/interface.tmplt ===<br />
This file is processed for each required and provided interfaces of the function. Results of processing are passed to [[#<template-subdir>/function.tmplt|function template]].<br />
{| class="wikitable"<br />
!Parameter name<br />
!Description<br />
|-<br />
|Name<br />
|The name of the interface<br />
|-<br />
|Direction<br />
|"PI" or "RI"<br />
|-<br />
|Kind<br />
|The RCM Kind<br />
|-<br />
|Parent_Function<br />
|The name of the function<br />
|-<br />
|Language<br />
|The implementation language of the function<br />
|-<br />
|Property_Names<br />
|All AADL properties (names) associated to the function<br />
|-<br />
|Property_Values<br />
|... and corresponding values<br />
|-<br />
|Param_Names<br />
|List of parameter names<br />
|-<br />
|Param_Types<br />
| |_ Corresponding parameter types<br />
|-<br />
|Param_Directions<br />
| |_ Corresponding direction<br />
|-<br />
|Param_Encodings<br />
| |_ Corresponding ASN.1 encoding<br />
|-<br />
|Is_Timer<br />
|Flag set to true if this is a timer interface<br />
|-<br />
|Period<br />
|Property of the interface<br />
|-<br />
|WCET<br />
|Property of the interface<br />
|-<br />
|Queue_Size<br />
|Property of the interface<br />
|-<br />
|IF_Property_Names<br />
| and Values User-defined properties (vector tag)<br />
|-<br />
|Remote_Languages<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Param_ASN1_Modules<br />
|DOCUMENTATION MISSING<br />
|-<br />
|IF_Property_Values<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Interface_Names<br />
|DOCUMENTATION MISSING<br />
|-<br />
|Remote_Function_Names<br />
|DOCUMENTATION MISSING<br />
|}<br />
<br />
=== <template-subdir>/function.tmplt ===<br />
<!-- TODO --></div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=508Kazoo2019-12-13T14:11:39Z<p>Kgrochowski: /* Code generation */</p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons|code skeletons]] and [[#Glue code|glue code]] generation algorithms.<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=507Kazoo2019-12-13T14:06:43Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons]] and [[#Glue code]].<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Kazoo concurrency view templates|Concurrency View template]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=506Kazoo2019-12-13T14:04:46Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons]] and [[#Glue code]].<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Concurrency View template|Kazoo concurrency view templates]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<syntaxhighlight lang="Python"><br />
for template_subdirectory in concurrency_view_directory:<br />
all_nodes = ""<br />
filesys = evaluate_template_file("filesys.tmplt")<br />
for node in ConcurrencyView:<br />
filenode = evaluate_optional_template_file("filenode.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for partition in node.partitions:<br />
filepart = evaluate_optional_template_file("filepart.tmplt")<br />
for thread in partition.threads:<br />
filethread = evaluate_optional_template_file("filethread.tmplt")<br />
evaluate_template_file("thread.tmplt") and (save as filethread if filethread is not empty)<br />
for block in partition.blocks:<br />
fileblock = evaluate_optional_template_file("fileblock.tmplt")<br />
for block.protected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.unprotected_interfaces:<br />
evaluate_template_file("pi.tmplt")<br />
for block.required_interfaces:<br />
evaluate_template_file("ri.tmplt")<br />
evaluate_template_file("block.tmplt") and (save as fileblock if fileblock is not empty)<br />
partition_content = evaluate_template_file("partition.tmplt")<br />
if filepart is not empty:<br />
save partition_content as filepart<br />
node_content = evaluate_template_file("node.tmplt")<br />
if filenode is not empty:<br />
save node_content as filenode<br />
all_nodes += node_content<br />
if filesys is not empty and all_nodes is not empty:<br />
evaluate_optional_template_file("system.tmplt") and save as filesys<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=505Kazoo2019-12-13T13:38:30Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided AADL models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
Code is generated using input AADL models, parsed by [[Ocarina]].<br />
<br />
The system representation consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView contains also connections between provided interfaces and required interfaces.<br />
The InterfaceView is used to create skeletons and glue code. See [[#Code skeletons]] and [[#Glue code]].<br />
<br />
The DeploymentView consists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of the rest of glue code and also middleware integration. See [[#Concurrency View]].<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Concurrency View template|Kazoo concurrency view templates]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=504Kazoo2019-12-13T13:32:58Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for glue_template_subdirectory in glue_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
=== Concurrency View ===<br />
For each [[Concurrency View template|Kazoo concurrency view templates]] kazoo processes each node of the view and creates set of files<br />
according to the presented algorithm in pseudocode:<br />
<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available Concurrency View templates ====<br />
<br />
Currently kazoo provides the Concurrency View templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/concurrency_view</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
!Processed<br />
|-<br />
|aadl_2_threads<br />
|<code>build/system.aadl<br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_3_main<br />
|<code>build/main.aadl</code><br />
|Always (Used later by [[Ocarina]] to create source code of Concurrency View)<br />
|-<br />
|aadl_4_makefile<br />
|<code>build/Makefile.taste</code><br />
|Always<br />
|-<br />
|ada_pohi_gpr<br />
|<br />
* for every node: <code>Makefike.<node name></code><br />
* for every partition: <code><partition name>.gpr</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_body<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.adb</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|ada_wrappers_source<br />
|for every partition: <code>build/<partition name>/<partition name>_taste_interface.ads</code><br />
|Only when [[PolyORB-HI-Ada]] middleware should be used (default)<br />
|-<br />
|air_cgpr<br />
|for every partition: <code>build/<node name>/air.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_gpr <br />
|for every partition: <code>build/<node name>/_air.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_makefile<br />
|<code>build/Makefile.air</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|air_port_polling<br />
|for every partition: <code>build/<node name>/<partition name>/air_polling.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_gpr<br />
|<br />
* for every node: <code>build/<node name>/Makefile.<node name></code><br />
* for every partition <code>build/<node name>/<partition name>.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_cgpr<br />
|for every partition: <code>build/<node name>/rtems_ada.cgpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|c_pohi_rtems_with_ada_gpr<br />
|for every partition: <code>build/<node name>/<partition name>_rtems_ada.gpr</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|drivers_config<br />
|<code>build/drivers_config.asn</code><br />
|Always<br />
|-<br />
|pohic_makefile_workaround<br />
|for every partition: <code>build/<node name>/gather_<partition name>_filelist.sh</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_body<br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.c</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|-<br />
|pohic_wrappers_header <br />
|for every partition: <code>build/<node name>/<partition name>_polyorb_interface.h</code><br />
|Only when [[PolyORB-HI-C]] middleware should be used (<code>--polyorb-hi-c</code> option).<br />
|}<br />
<br />
== Under the hood ==<br />
Kazoo uses Ocarina library to parse input AADL models.<br />
The internal representation of system consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=503Kazoo2019-12-13T12:56:28Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory.<br />
For example to create new Concurrency View template, execute the following commands:<br />
<nowiki>$ cd ~/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
Templates locations:<br />
* Code skeletons: <code>tool-src/kazoo/templates/skeletons</code><br />
* Glue code: <code>tool-src/kazoo/templates/glue/language_wrappers</code><br />
* Concurrency View: <code>tool-src/kazoo/templates/concurrency_view</code><br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
The skeletons templates are responsible for creating code skeletons,<br />
which are a placeholders for actual implementation of the functions, provided by the user.<br />
<br />
Kazoo uses code skeletons to generate files in folder created according to <code><function name>/<language>/<src>/</code> scheme.<br />
<br />
==== Available code skeletons templates ====<br />
<br />
Currently kazoo provides the following code skeletons templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/skeletons</code>):<br />
* ada-body<br />
* ada-source<br />
* blackbox-c-body<br />
* blackbox-c-header<br />
* c-body<br />
* c-header<br />
* cpp-body<br />
* cpp-body-instance<br />
* cpp-body-type<br />
* cpp-context<br />
* cpp-header<br />
* cpp-header-instance<br />
* cpp-header-type<br />
* gui-body<br />
* gui-enum-defs<br />
* gui-header<br />
* gui-runtime-body<br />
* gui-runtime-debug-body<br />
* gui-runtime-debug-header<br />
* gui-runtime-header<br />
* opengeode-process-body<br />
* opengeode-structure<br />
* pragmadev_process_rdd<br />
* pragmadev_process_rdp<br />
* pragmadev_scheduled<br />
* pragmadev_sys_process_rdd<br />
* simulink<br />
* timer-manager-body<br />
* timer-manager-header<br />
* vdm-body<br />
* vdm-header<br />
<br />
=== Glue code ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|glue template]] (each containing multiple template files).<br />
From each processing a one 'Makefile' and one 'implementation' file can be generated (both are optional outputs).<br />
This processing algorithm is presented in more detail in the pseudocode below:<br />
<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
</syntaxhighlight><br />
<br />
==== Available glue templates ====<br />
<br />
Currently kazoo provides the glue code templates (each stored in separate subdirectory of <code>tool-src/kazoo/templates/glue</code>) listed in table:<br />
<br />
{| class="wikitable"<br />
!Template name<br />
!Generates<br />
|-<br />
|invoke_ri-body<br />
|<code>build/<function name>/<language>/<function name>_invoke_ri.c</code><br />
|-<br />
|mini-cv<br />
|<code>build/<function name>/<language>/<function name>_mini_cv.c</code><br />
|-<br />
|system_config<br />
|<code>build/<function name>/<language>/<function name>_system_config.h</code><br />
|-<br />
|vm_if-body<br />
|<code>build/<function name>/<language>/<function name>_vm_if.c</code><br />
|-<br />
|vm_if-header<br />
|<code>build/<function name>/<language>/<function name>_vm_if.h</code><br />
|}<br />
<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== Under the hood ==<br />
Kazoo uses Ocarina library to parse input AADL models.<br />
The internal representation of system consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=502Kazoo2019-12-13T11:41:18Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd /home/taste/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl (+ .asn/.acn models)<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory:<br />
<nowiki>$ cd /home/taste/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
== Adding new platform to TASTE using Kazoo ==<br />
The steps required to add new platform to the TASTE was described in the article: [[Kazoo and FreeRTOS]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided models to generate four major parts of the final system implementation:<br />
* Build script - script responsible for final step of code generation and compilation,<br />
* Code skeletons - actual implementation of functions and their provided interfaces,<br />
* Glue code - the source code responsible for exchanging parameters and results between interfaces according to DataView.aadl,<br />
* Concurrency View - the system.aadl and main.aadl files, which will be later used by [[Ocarina]] to generate code during build script execution.<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
For each function defined in Interface View Kazoo will process each [[Kazoo skeletons and glue templates|skeleton template]] (each containing multiple template files).<br />
From each processing usually a single file will be generated. This processing algorithm is presented in more detail in the pseudocode below:<br />
<syntaxhighlight lang="Python"><br />
for function in InterfaceView:<br />
for skeleton_template_subdirectory in skeleton_directory:<br />
makefile_filename = evaluate_optional_template_file("makefile-filename.tmplt")<br />
function_filename = evaluate_optional_template_file("function-filename.tmplt")<br />
if evaluate_template_file("trigger.tmplt") is "TRUE":<br />
for interface in function.required_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
for interface in function.provided_interfaces:<br />
evaluate_template_file("interface.tmplt")<br />
if makefile_filename is not empty:<br />
evaluate_template_file("makefile.tmplt") and save as makefile_filename<br />
evaluate_template_file("function.tmplt") and (save as function_filename if function_filename is not empty)<br />
if context_parameters in function:<br />
evaluate_template_file("context_parameters.tmplt") and save as "<function name>/<implementation lang>/Context-<function name>.asn"<br />
</syntaxhighlight><br />
<br />
=== Glue code ===<br />
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the following algorithm presented in pseudocode:<br />
<nowiki>for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file</nowiki><br />
<br />
==== Existing Glue templates ====<br />
<br />
===== invoke_ri-body =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''<br />
<br />
===== mini-cv =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''<br />
<br />
===== system_config =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''<br />
<br />
===== vm_if-body =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''<br />
<br />
===== vm_if-header =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== Under the hood ==<br />
Kazoo uses Ocarina library to parse input AADL models.<br />
The internal representation of system consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=493Kazoo2019-12-12T13:58:07Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
== Overview ==<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
== Installation and updating ==<br />
<br />
=== Updating sources ===<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
=== Rebuilding from source ===<br />
<br />
To build kazoo from sources so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
== Using kazoo ==<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
=== Basic usage ===<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
=== Kazoo example ===<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd /home/taste/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
=== Kazoo help ===<br />
To obtain complete list of kazoo parameters and options type <code>kazoo --help</code>.<br />
<br />
=== Input files ===<br />
Kazoo used default TASTE AADL models as input:<br />
<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl<br/>Derived files:<br />
** DataView.asn<br />
** DataView.acn<br />
<br />
== New templates for kazoo ==<br />
To create new set of templates to be used by kazoo copy existing template subdirectory:<br />
<nowiki>$ cd /home/taste/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory></nowiki><br />
<br />
Edit newly created templates and [[#Rebuilding from source|rebuild]] kazoo.<br />
For more details see [[Technical_topic:_Add_a_new_target_platform_to_TASTE|note about adding new target to TASTE]].<br />
<br />
== Code generation ==<br />
<br />
Kazoo uses provided models to generate three major parts of the final system implementation:<br />
* Code skeletons <!-- TODO: Some notes describing each of the parts? --><br />
* Glue code <!-- TODO --><br />
* Build script - script responsible for final step of code generation and compilation.<br />
<br />
=== Build script ===<br />
Build script is a single file named <code>build-script.sh</code> which is generated from <code>build-script.tmplt</code> template file.<br />
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.<br />
<br />
=== Code skeletons ===<br />
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the following algorithm presented in pseudocode:<br />
<nowiki>for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
if function has context parameters then<br />
evaluate template context_parameters.tmplt and save the output to file</nowiki><br />
<br />
=== Glue code ===<br />
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the following algorithm presented in pseudocode:<br />
<nowiki>for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file</nowiki><br />
<br />
==== Existing Glue templates ====<br />
<br />
===== invoke_ri-body =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''<br />
<br />
===== mini-cv =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''<br />
<br />
===== system_config =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''<br />
<br />
===== vm_if-body =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''<br />
<br />
===== vm_if-header =====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== Under the hood ==<br />
Kazoo uses Ocarina library to parse input AADL models.<br />
The internal representation of system consists of three major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=491Kazoo2019-12-12T11:49:33Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
= Overview =<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
= Installation and updating =<br />
<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
To do so run the following commands in the terminal:<br />
<nowiki>$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
= Using kazoo =<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
== Basic usage ==<br />
<br />
Run the following commands in the terminal.<br />
<nowiki>$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files for kazoo|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki>$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
== Kazoo example ==<br />
Kazoo comes with a lot of helpful examples.The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simplifies the process of the build.<br />
For an example, to build project ''Demo_C'' run following commands in the terminal:<br />
<nowiki>$ cd /home/taste/tool-src/kazoo/test/Demo_C<br />
$ make</nowiki><br />
<br />
== Input files for kazoo ==<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl<br />
* DataView.asn<br />
* DataView.acn<br />
<br />
== Internal representation of system within kazoo ==<br />
Taste uses Ocarina library to parse input aadl files.<br />
The internal representation of system consists of thre major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided interfaces and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].<br />
<br />
== build-script.sh generation ==<br />
The file build-script.sh is generated from build-script.tmplt.<br />
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.<br />
<br />
== Code skeletons generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
if function has context parameters then<br />
evaluate template context_parameters.tmplt and save the output to file<br />
</nowiki><br />
<br />
== Glue code generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the presented algorithm in pseudocode:<br />
Algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Glue templates ===<br />
<br />
==== invoke_ri-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''<br />
<br />
==== mini-cv ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''<br />
<br />
==== system_config ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''<br />
<br />
==== vm_if-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''<br />
<br />
==== vm_if-header ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== How to create new template for kazoo ==<br />
Copy existing template subdirectory:<br />
<nowiki><br />
$ cd /home/taste/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory><br />
</nowiki><br />
After editing new templates kazoo needs to be [[#How to build kazoo|rebuild]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=490Kazoo2019-12-12T11:44:16Z<p>Kgrochowski: </p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
= Overview =<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
= Installation and updating =<br />
<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki><br />
$ cd ~/tool-src/kazoo<br />
$ git checkout master</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
To do so run the following commands in the terminal:<br />
<nowiki><br />
$ cd ~/tool-src/kazoo<br />
$ make install</nowiki><br />
<br />
= Using kazoo =<br />
<br />
Kazoo is a command line tool, executed from terminal and configured by a list o parameters.<br />
<br />
== Basic usage ==<br />
<br />
Run the following commands in the terminal.<br />
<nowiki><br />
$ kazoo --output=out --gw --glue --polyorb-hi-c</nowiki><br />
Kazoo will read the default [[#Input files for kazoo|input AADL models]] and generate code to the selected output directory.<br />
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.<br />
<br />
In the result directory '''out''' will be created and filled with generated models and source files.<br />
<br />
To build the generated system run following commands in the terminal:<br />
<nowiki><br />
$ cd out<br />
$ make</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
== How to use kazoo examples ==<br />
Kazoo comes with a lot of examples, which are wery helpful. The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simpifies the process of build.<br />
For an example, to build project Demo_C run following commands int the terminal:<br />
<nowiki><br />
$ cd /home/taste/tool-src/kazoo/test/Demo_C<br />
$ make<br />
</nowiki><br />
<br />
== Input files for kazoo ==<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl<br />
* DataView.asn<br />
* DataView.acn<br />
<br />
== Internal representation of system within kazoo ==<br />
Taste uses Ocarina library to parse input aadl files.<br />
The internal representation of system consists of thre major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided interfaces and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].<br />
<br />
== build-script.sh generation ==<br />
The file build-script.sh is generated from build-script.tmplt.<br />
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.<br />
<br />
== Code skeletons generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
if function has context parameters then<br />
evaluate template context_parameters.tmplt and save the output to file<br />
</nowiki><br />
<br />
== Glue code generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the presented algorithm in pseudocode:<br />
Algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Glue templates ===<br />
<br />
==== invoke_ri-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''<br />
<br />
==== mini-cv ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''<br />
<br />
==== system_config ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''<br />
<br />
==== vm_if-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''<br />
<br />
==== vm_if-header ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== How to create new template for kazoo ==<br />
Copy existing template subdirectory:<br />
<nowiki><br />
$ cd /home/taste/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory><br />
</nowiki><br />
After editing new templates kazoo needs to be [[#How to build kazoo|rebuild]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Kazoo&diff=489Kazoo2019-12-12T11:18:13Z<p>Kgrochowski: Refactoring of introduction and installation</p>
<hr />
<div>Kazoo is a part of the TASTE toolchain responsible for generating code and build scripts from AADL models.<br />
<br />
= Overview =<br />
<br />
Kazoo is a a command line tool which processes input AADL models and produces derived models, code and scripts used to build complete system.<br />
It facilitates [[Ocarina]] for AADL parsing and [https://github.com/AdaCore/templates-parser templates-parser] for templates processing and files generation.<br />
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.<br />
Generated build scripts apart from calling code compilers also run other tools like '''ocarina''' and '''aadl2glueC''' to create rest of the source code.<br />
<br />
= Installation and updating =<br />
<br />
To update kazoo run the following commands in the terminal:<br />
<nowiki><br />
$ cd ~/tool-src/kazoo<br />
$ git checkout master<br />
</nowiki><br />
When command succeeds, kazoo needs to be rebuild to complete installation.<br />
<br />
To do so run the following commands in the terminal:<br />
<nowiki><br />
$ cd ~/tool-src/kazoo<br />
$ make install<br />
</nowiki><br />
<br />
= Using kazoo =<br />
<br />
== How to use kazoo ==<br />
Kazoo is a command line tool.<br />
Run following commands in the terminal. Kazoo reads [[#Input files for kazoo|input aadl files]] and usi<br />
Example of kazoo usage:<br />
<nowiki><br />
$ kazoo --output=out --gw --glue --polyorb-hi-c<br />
</nowiki><br />
After this, directory '''out''' will be created. To build the system run following commands in the terminal:<br />
<nowiki><br />
$ cd out<br />
$ make<br />
</nowiki><br />
The output binary files will be located in the directory '''out/binaries'''.<br />
<br />
== How to use kazoo examples ==<br />
Kazoo comes with a lot of examples, which are wery helpful. The examples are located in the directory '''/home/taste/tool-src/kazoo/test/'''.<br />
Every example project contains Makefile, which simpifies the process of build.<br />
For an example, to build project Demo_C run following commands int the terminal:<br />
<nowiki><br />
$ cd /home/taste/tool-src/kazoo/test/Demo_C<br />
$ make<br />
</nowiki><br />
<br />
== Input files for kazoo ==<br />
* InterfaceView.aadl<br />
* DeploymentView.aadl<br />
* DataView.aadl<br />
* DataView.asn<br />
* DataView.acn<br />
<br />
== Internal representation of system within kazoo ==<br />
Taste uses Ocarina library to parse input aadl files.<br />
The internal representation of system consists of thre major structures:<br />
* InterfaceView<br />
* DeploymentView<br />
* ConcurrencyView<br />
<br />
The InterfaceView representation contains of list of functions. Every function contains provided interfaces and required interfaces. Optionally a function may contain context parameters.<br />
The InterfaceView representation contains also connections between provided interfaces and required interfaces.<br />
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]].<br />
<br />
The DeploymentView constists of Nodes, Buses and connections between them.<br />
The Node contains Partitions, Processors and Drivers.<br />
The Partition contains a list of bounded functions.<br />
The DeploymentView is not directly used for code generation.<br />
<br />
The ConcurrencyView is generated from DeploymentView.<br />
The ConcurrencyView consists of list of Nodes.<br />
Every Node consists of list of Partitions and list of Drivers.<br />
Every Partition consists of list of Threads.<br />
Every Thread has a list of assigned functions from InterfaceView.<br />
<br />
The ConcurrencyView is used for generation of rest of glue code and also middleware integration. See [[Kazoo#Concurrency View generation|Concurrency View generation]].<br />
<br />
== build-script.sh generation ==<br />
The file build-script.sh is generated from build-script.tmplt.<br />
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.<br />
<br />
== Code skeletons generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo skeletons templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
if function has context parameters then<br />
evaluate template context_parameters.tmplt and save the output to file<br />
</nowiki><br />
<br />
== Glue code generation ==<br />
[[Kazoo skeletons and glue templates|Kazoo glue templates]] are processed according to the presented algorithm in pseudocode:<br />
Algorithm in pseudocode:<br />
<nowiki><br />
for every function from InterfaceView:<br />
for every subdirectory<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
evaluate template function-filename.tmplt if exists<br />
evaluate template makefile-filename.tmplt if exists<br />
evaluate template interface.tmplt for required interfaces of function<br />
evaluate template interface.tmplt for provided interfaces of function<br />
evaluate template makefile.tmplt and optionally save output to file<br />
evaluate template function.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Glue templates ===<br />
<br />
==== invoke_ri-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_invoke_ri.c'''<br />
<br />
==== mini-cv ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_mini_cv.c'''<br />
<br />
==== system_config ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_system_config.h'''<br />
<br />
==== vm_if-body ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.c'''<br />
<br />
==== vm_if-header ====<br />
This subdirectory creates files with name '''build/<function name>/<language>/<function name>_vm_if.h'''<br />
<br />
== Concurrency View generation ==<br />
[[Kazoo concurrency view templates]] are processed according to the presented algorithm in pseudocode:<br />
<nowiki><br />
for every subdirectory<br />
for every node from ConcurrencyView<br />
evaluate template filesys.tmplt<br />
evaluate template filenode.tmplt<br />
evaluate template trigger.tmplt<br />
if result is equal to “TRUE” then<br />
for every partition from node:<br />
evaluate template filepart.tmplt<br />
evaluate template thread.tmplt and optionally save output to the file<br />
evaluate template filethread.tmplt<br />
evaluate template fileblock.tmplt<br />
evaluate template pi.tmplt<br />
evaluate template pi.tmplt (with other parameters)<br />
evaluate template ri.tmplt<br />
evaluate template block.tmplt and optionally save output to file<br />
evaluate template partition.tmplt and optionally save output to file<br />
evaluate template node.tmplt and optionally save output to file<br />
evaluate template system.tmplt and optionally save output to file<br />
</nowiki><br />
<br />
=== Existing Concurrency View subdirectories ===<br />
<br />
==== aadl_2_threads ====<br />
This subdirectory creates file '''build/system.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_3_main ====<br />
This subdirectory creates file '''build/main.aadl''', which is used by ocarina to create source code of Concurrency View.<br />
This subdirectory is processed always.<br />
<br />
==== aadl_4_makefile ====<br />
This subdirectory creates file '''build/Makefile.taste'''.<br />
This subdirectory is processed always.<br />
<br />
==== ada_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* for every node file with name '''Makefike.<node name>'''<br />
* for every partition file with name '''<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_body ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.adb''' for every partition<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== ada_wrappers_source ====<br />
This subdirectory creates files with name '''build/<partition name>/<partition name>_taste_interface.ads''' For every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was not used.<br />
<br />
==== air_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/air.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<parition name>_air.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_makefile ====<br />
This subdirectory creates file '''build/Makefile.air'''.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== air_port_polling ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/air_polling.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_gpr ====<br />
This subdirectory creates following files:<br />
* For every node '''build/<node name>/Makefile.<node name>'''<br />
* For every partition '''build/<node name>/<partition name>.gpr'''<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_cgpr ====<br />
This subdirectory creates files with name '''build/<node name>/rtems_ada.cgpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== c_pohi_rtems_with_ada_gpr ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>_rtems_ada.gpr''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== drivers_config ====<br />
This subdirectory creates file '''build/drivers_config.asn'''.<br />
This subdirectory is processed always.<br />
<br />
==== pohic_makefile_workaround ====<br />
This subdirectory creates files with name '''build/<node name>/gather_<partition name>_filelist.sh''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_body ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.c''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
==== pohic_wrappers_header ====<br />
This subdirectory creates files with name '''build/<node name>/<partition name>/<partition name>_polyorb_interface.h''' for every partition.<br />
This subdirectory is processed when option ''-p'' or ''--polyorb-hi-c'' was used.<br />
<br />
<br />
== How to create new template for kazoo ==<br />
Copy existing template subdirectory:<br />
<nowiki><br />
$ cd /home/taste/tool-src/kazoo/templates/concurrency_view<br />
$ cp -r aadl_2_threads <new subdirectory><br />
</nowiki><br />
After editing new templates kazoo needs to be [[#How to build kazoo|rebuild]].</div>Kgrochowskihttps://taste.tuxfamily.org/wiki/index.php?title=Main_Page&diff=488Main Page2019-12-12T09:21:05Z<p>Kgrochowski: link to Kazoo pages added to Technical topics</p>
<hr />
<div>= TASTE =<br />
Welcome to the [http://taste.tuxfamily.org/ TASTE] wiki! Please edit the wiki at your convenience.<br />
<br />
== TASTE Ecosystem, Overview and Screenshots ==<br />
* [[Latest news]]<br />
* [[Overview]]<br />
* [[TASTE consortium]]<br />
<br />
== Tool availability ==<br />
<br />
* [[Virtual Machine]]<br />
* [[Manual installation on a native platform]]<br />
<br />
== Documentation and presentations ==<br />
* [[Architecture Overview]]<br />
* [[Case studies]]<br />
* [[Media]] and [[Publications related to TASTE]]<br />
* [[Tools documentation]]<br />
* [[Technical topic: Advanced testing with MSC and Python scripts]]<br />
* [[Technical topic: OpenGEODE, an SDL editor for TASTE]]<br />
* [[Technical topic: OpenGEODE - Design pattern: How to emulate the SAVE symbol]]<br />
* [[Technical topic: OpenGEODE - SDL Operators: How to work with data]]<br />
* [[Technical topic: ASN1SCC - ESA's ASN.1 Compiler for safety-critical embedded platforms]]<br />
* [[Technical topic: ASN.1 - An introduction to ACN]]<br />
* [[Technical topic: Hints to model complex packet encodings with ASN.1 and ACN]]<br />
* [[Technical topic: ASN.1 and ACN - How to add a CRC value to an encoded packet]]<br />
* [[Technical topic: ASN.1 and SQL mapping]]<br />
* [[Technical topic: Using SQL Databases in TASTE]]<br />
* [[Technical topic: Customizing the ASN.1 compiler (ASN1SCC) with your own templates]]<br />
* [[Technical topic: Use of timers in user code with TASTE]]<br />
* [[Technical topic: Extend your models with your own property sets to hook your own tools]]<br />
* [[Technical topic: Test your Leon2/Leon3 applications with QEMU]]<br />
* [[Technical topic: Manage interface priorities]]<br />
* [[Technical topic: Work with sockets]]<br />
* [[Technical topic: FPGAs in TASTE]]<br />
* [[Technical topic: Code Coverage]]<br />
* [[Technical topic: Add a new target platform to TASTE]]<br />
* Technical topic: [[Kazoo]] templating engine<br />
* Technical topic: use the new qualifiable [[QGen]] code generator for Simulink with TASTE<br />
* [[Work in progress: Integrating SDL and VDM]]<br />
<br />
== Management and release process ==<br />
* [[Obtain the code and stay in sync]]<br />
* [[The TASTE VM update mechanism in detail]]<br />
* [[Regression checking suites]]<br />
* [[Repackaging of the VM]]<br />
* [[Merging into stable]]<br />
* [[Building a TASTE-y RTEMS]]<br />
* [[Taming the stack usage of embedded applications]]<br />
<br />
== Support ==<br />
* [[Contribute to the wiki]]<br />
* [[Submit a bug]]<br />
* [[Technical FAQ]]<br />
* [[taste-users]] mailing-list<br />
* [[taste-dev]] mailing-list<br />
* [https://www.openhub.net/p/taste-esa Source code metrics] on [https://www.openhub.net OpenHub]<br />
* [[Troubleshooting Device Driver issues on the Gaisler Boards]]<br />
<br />
== Other information ==<br />
<br />
* [[ASN.1 generators|ASN.1 Compiler and ASN.1 glue generators]]<br />
* [[Ocarina]]<br />
* [[Orchestrator]]<br />
* [[PolyORB-HI-Ada]]<br />
* [[PolyORB-HI-C]]<br />
* [[tasted]] (TASTE daemon - deprecated)<br />
* [[Cross-development toolchains]]<br />
* [[TASTE GUI for Windows]] (experimental)<br />
* [[Software requirements for TASTE GUI for Windows]] (experimental)<br />
* [[Using TASTE GUI for Windows]] (experimental)<br />
* [[Build TASTE on QEMU 1.0 for Windows platforms]] (experimental)<br />
* [[Software requirements for MSC Editor]]<br />
* [[Create an .exe file from the TASTE GUI for Windows sources]] (experimental)<br />
* [[Create an installer for TASTE GUI for Windows]] (experimental)<br />
* [[Create a binary file from the TASTE GUI for Windows sources for Linux]] (experimental)<br />
<br />
* [[ESA Summer of Code in Space - Project ideas]]</div>Kgrochowski