Difference between pages "Technical topic: OpenGEODE - SDL Operators: How to work with data" and "TASTE Step by step tutorial"

From TASTE
(Difference between pages)
Jump to: navigation, search
(INTEGER types)
 
(Hello World)
 
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
The SDL language primarily targets the description of a system's behaviour. It is however also possible to manipulate data using a collection of built-in operators. This can be convenient to avoid depending on external, manually-written code to process the parameters of messages during the execution of a state machine transition.
+
This tutorial explains how to quickly build a system using [https://taste.tools/ TASTE].
  
Variables are defined in the ASN.1 language and can express simple types (boolean, numbers and enumerated values) as well as complex data structures (records, arrays, and choices). Each type comes with some dedicated operators which are described in this page.
+
Make sure you have either installed the TASTE Virtual machine : https://download.tuxfamily.org/taste/TASTE-VM-10-64bit.ova
  
 +
...or that you made a manual installation following the instructions here: [[Manual installation on a native platform]]
  
= INTEGER types =
+
If you use the VM, note that the username and password to login are taste / tastevm
  
  MyInt ::= INTEGER (-10 .. 255)
+
= Important =
  
  dcl foo MyInt := 42;
+
Always make sure you are using the latest version of the TASTE tools.
 +
From within the TASTE Virtual machine or your native installation, open a terminal and run the following commands:
  
 +
  $ cd tool-src
 +
  $ ./Update-TASTE.sh
  
The following can be done (in addition to the +, -, / and * operators):
+
When it is done, close the current window and open a new terminal.
  
  foo := -5              -- assign a value
+
= Hello World =
  foo := abs (foo)        -- return 5
 
  foo := fix (5.7)        -- convert float to integer
 
  foo := power (10, 2)    -- 100
 
  foo := (foo + 1) mod 10 -- modulo
 
  write (foo)
 
  writeln (foo)          -- display the value (procedure call)
 
  
Moreover, integer can be assigned with a value expressed with an base 16 and base 2 representation, using the ASN.1 value notation:
+
This tutorial explains how to create a basic system to get familiar with the tool.
  
  foo := '00FF'H;
+
== Create a new project ==
  bar := '01100011'B;
 
  
If the range of the integer is positive (unsigned integer) then it is also possible to apply bitwise operators to it.
+
Run the following command:
  
= REAL types =
+
  $ taste
  
  MyReal ::= REAL (0.0 .. 10.0)
+
You will be prompted for a project name and a new folder with this name will be created. Always use the '''taste''' command to re-open an existing project.
   
 
  dcl foo MyReal := 42.0;
 
  dcl bar MyInt  := 5;
 
  
The following can be done:
+
The Space Creator editor will show up:
  
  foo := 0.0            -- assign a value
+
:[[File:ClipCapIt-221116-133346.PNG|1000px]]
  foo := ceil (1.618)    -- ceiling
 
  foo := floor (1.618)  -- ceiling
 
  foo := float (bar)    -- convert integer to real
 
  foo := round (3.14159) -- round
 
  foo := sin (3.14)
 
  foo := cos (3.14)
 
  foo := sqrt (2)
 
  foo := trunc (7.77)    -- truncation
 
  write (foo)
 
  writeln (foo)
 
  
 +
== Build the system logical architecture ==
  
= ENUMERATED types =
+
In the main window, draw a rectangle while pressing the mouse '''right button'''. When you release the mouse button, a contextual menu offers to create a function or a function type:
  
  MyEnum ::= ENUMERATED { foo, bar }
+
:[[File:ClipCapIt-221116-133603.PNG]]
  
  dcl var MyEnum := foo;
+
Choose "Function", and rename the box:
  dcl pos INTEGER (0..1);
 
  
Keep in mind that an enumerated is a '''state''' and not a number.  
+
:[[File:ClipCapIt-221116-133927.PNG]]
You can get the ''value'' (as a number) of an enumerant like this:
 
  
  pos := num (var);
+
Create a second function next to it.
  
If the ENUMERATED type contains explicit values:
+
Then keep the Ctrl key and the left mouse button clicked to draw a line between the two functions:
  
  MyOtherEnum ::= ENUMERATED {fourty (40), two (2)}
+
:[[File:ClipCapIt-221116-134009.PNG]]
  dcl baz MyOtherEnum := fourty;
 
  
then applying the ''num'' operator will return either 40 or 2.
+
When you release the mouse button, a connection will appear and a dialog will let you name this connection:
  
Additionally you can set the value of an enumerated from a position (or from the number set in the ENUMERATED type):
 
  
  var := val (1, MyEnum)      -- sets to bar
+
:[[File:ClipCapIt-221116-134200.PNG]]
  baz := val (40, MyOtherEnum) -- sets to fourty
 
  
You can also print the enumerant name on the screen with the write or writeln operators.
+
You can select the "kind" of connection this is. It can be an asynchronous message ('''sporadic''') or a simple, immediate function call (e.g. '''unprotected''').
  
= CHOICE types =
+
Add a connection in the other direction by using Ctrl+Left Click from the function on the right and releasing the keys when hovering on the left function. If you name it "Hi", it will look like this:
  
  MyChoice ::= CHOICE {
+
:[[File:ClipCapIt-221116-134541.PNG]]
      foo BOOLEAN,
 
      bar INTEGER (0 .. 255)
 
  }
 
 
  dcl a MyChoice := foo : FALSE;  -- ASN.1 Value Notation to set the value
 
  
You can evaluate the current choice using the '''present''' operator in a decision:
+
Last, we will add a cyclic interface to the "caller" function. To do this, right click on the Caller function and choose the "Provided Interface" option from the menu entry:
  
    DECISION present (a)  -- test against foo and bar
+
:[[File:ClipCapIt-221116-134816.PNG]]
  
    writeln (if present (a) = foo then a.foo else a.bar fi)
+
In the dialog, name it ("trigger", choose "Periodic" for the kind attribute, and leave the period to 1000 ms:
  
You can also use an implicit type to store the choice determinant:
+
:[[File:ClipCapIt-221116-134925.PNG]]
  
    dcl current_choice MyChoice_selection := present (a);
+
== Create data types ==
  
And if you happen to have an ENUMERATED type with the extact same enumerants as the CHOICE options, you can convert from an to:
+
TASTE software works with data, and relies on well defined data structures. They are captured with the ASN.1 language.
  
      MyDeterminants ::= ENUMERATED { foo, bar }
+
On the Workspace area of the editor you will see a file with the ".asn" extension. The file name itself is the name of your project. Double click on this file to open the editor. The default file contains a lot of built-in documentation to help you with the syntax of the language.
      dcl det MyDeterminants := to_enum (a, MyDeterminants);
 
      current_choice := to_selector (det, MyChoice);
 
  
Last, there is an internal operator named '''choice_to_int''' that can be used if the CHOICE options are (mostly) numerical. It allows to return the value correponding to the current choice item without specifying the field name. You must provide a default value that will be returned in case the current choice's type is not numerical:
+
For this example we will create a type to store a simple counter with a range of values from 0 to 3:
  
   
+
:[[File:ClipCapIt-221116-135538.PNG]]
    dcl someInt MyInt;
 
    dcl someChoice MyChoice := { bar : 42 }
 
    (...)
 
    someInt := choice_to_int (someChoice, 10)    -- will return 42
 
    someChoice := { foo : false }
 
    someInt := choice_to_int (someChoice, 10)    -- will return 10, the default value since the current choice is not "bar"
 
  
When combined with other operators, this can be used to make checks on the value of the choice without having to check manually all possible values.
+
After this is done, go back to the main diagram by selecting the file named "interfaceview.xml". Note that you may also split the window in the IDE to view both files at the same time.
  
For example you may want to write a generic function that can check a value against a threshold. The value itself could be in a CHOICE:
+
== Select the implementation language of each function ==
  
  ValueToMonitor ::= CHOICE {
+
To create an implementation of the system, we have to select a language for each function (caller and callee). We will use C for the callee and SDL for the caller.
      current Amp,
+
To do this, double click on each function, and select the tab named "Implementations". Change the language accordingly (the default being SDL, there is no need to touch the caller function):
      voltage INTEGER (0..230)
 
      -- and a hundred more
 
  }
 
  Parameters ::= ENUMERATED { current, voltage, ..... }
 
  
but you don't want to write a function that does something like:
+
:[[File:ClipCapIt-221116-135952.PNG]]
  
    if present (val) = current then
 
      if val.current < currentThreshold then
 
        return true
 
      end if
 
    else if present (val) = voltage then
 
      if val.voltage < voltageThreshold then
 
        return true
 
      end if
 
    else .....
 
  
Instead you can do in a single line:
+
== Implement the functions ==
  
    if choice_to_int(val, 0) < thresholds(num(to_enum(val), Parameters)) then
+
We start with the "callee" function. Right click on the function and select "Edit Implementation" from the contextual menu.
        return true
+
After being prompted to save the model (do it), wait a few seconds to enter the C editor in the IDE:
    end if
 
  
assuming that threshold is a table indexed in the order of the determinants.
+
:[[File:ClipCapIt-221116-140250.PNG]]
  
= SEQUENCE OF types (arrays) =
+
Edit the code at will. The IDE provides auto-completion and on-the-fly syntax and semantic checks:
  
  MySeqOf ::= SEQUENCE (SIZE (0..10)) OF BOOLEAN
+
:[[File:ClipCapIt-221116-140500.PNG]]
  dcl foo MySeqOf := { true, false, false };  -- ASN.1 Value Notation
 
  dcl bar MyInt;
 
  
  bar := fix (length (foo)) -- 3
+
When you are done, go back to the main diagram editor (double click on "interfaceview.xml" in the workspace on the left).
  
  for each in foo:
+
Right-click on Caller and choose "Edit Implementation". This will open the SDL editor (OpenGEODE).
      call writeln (each);
 
  endfor
 
  
 +
:[[File:ClipCapIt-221116-140708.PNG]]
  
= SEQUENCE types (records) =
+
If you are not familiar with SDL, a complete documentation is built-in the tool (on the right).
 +
Double click on the Caller block to enter the state machine editor.
  
  MySeq ::= SEQUENCE {
+
You can create the state machine using the set of symbols on the left of the editor. In this example, when the periodic trigger is received, the "Hello" message will be sent (to the callee function), and then the "Hi" message will be expected in return. After a few cycles, we enter a state named "Enough" and stop repeating this polite exchange.
      a BOOLEAN OPTIONAL,
 
      b INTEGER (0 .. 255)
 
  }
 
  
  dcl seq MySeq := { a FALSE, b 10 };  -- ASN.1 Value Notation
+
:[[File:ClipCapIt-221116-142433.PNG]]
  
  DECISION exist (seq.a)  -- test presence of optional field
+
You may want to visualize this simple state machine with a "statechart" representation. Click on the corresponding tab on top of the editor:
  
= STRING types =
+
:[[File:ClipCapIt-221116-141927.PNG]]
  
== IA5String ==
+
You may now save the model and quit OpenGEODE, to get back to the main interface view.
  
This type is an ASCII string
+
== Quick build and run ==
  
  SomeString ::= IA5String (1..255)
+
At this stage you can already build the system. Click on the "Play" button on the bottom left corner of the tool:
  
It can be assigned a value:
+
:[[File:ClipCapIt-221116-142131.PNG]]
  
  dcl myStr SomeString := 'hello';    -- at declaration
 
  TASK myStr := 'world';              -- or in a task
 
  
It can be used in '''write'''/'''writeln''' calls.
+
After a few seconds of build, you will see the system run in a console:
  
== OCTET STRING ==
+
:[[File:ClipCapIt-221116-142547.PNG]]
  
  OctStr ::= OCTET STRING (SIZE (0.255))
+
When you do Ctrl-C to stop the application you can visualize a log of the execution in a file that was generated and that appeared in the workspace:
  
Octet strings can be assigned a text string, a hex string, or a bit string:
+
:[[File:ClipCapIt-221116-142758.PNG]]
  
  dcl myStr1 OctStr := '68656c6c6f'H;
+
== Create a deployment to run on target ==
  dcl myStr2 OctStr := '01010110'B;
 
  dcl myStr3 OctStr := 'hello world';
 
  
It is '''not''' possible to iterate (with a '''for loop''') on OCTET STRINGs. Only '''SEQUENCE OF''' types are iterable.
+
This quick build produced a Linux binary. But you may want to build on a different platform, for example a Leon processor with the RTEMS6 Qualified RTOS.
If you need to iterate on a sequence of octets, you can therefore define an custom octet string like this:
 
  
  Octet ::= OCTET STRING (SIZE (1))
+
To do this you need to model the deployment of your system. On the workspace, right-click on "Other files" and choose "Add new"
  OctetString ::= SEQUENCE (SIZE (0..255)) OF Octet
 
  
  dcl helloStr OctetString := {'h', 'e', 'l', 'l', 'o'};
+
:[[File:ClipCapIt-221116-143200.PNG]]
  ...
 
  for chr in helloStr:
 
    call write(chr);
 
  endfor
 
 
 
= TIMER types =
 
  
  timer mytimer;
+
In the dialog select "Deployment View file":
  
The '''SET''' and '''RESET''' operators from '''SDL''' are indirectly supported via procedure calls:
+
:[[File:ClipCapIt-221116-143234.PNG]]
  
  set_timer (1000, mytimer);
+
 
  reset_timer (mytimer);
+
Then on the next screen you may rename it, but keep the ".dv.xml" file extension:
 +
 
 +
:[[File:ClipCapIt-221116-143320.PNG]]
 +
 
 +
This will open a new editor, from which you can drag and drop deployment boards. Select for example this one:
 +
 
 +
:[[File:ClipCapIt-221116-143650.PNG]]
 +
 
 +
When you right click on the board, you can bind the functions (caller and callee) to it.
 +
 
 +
Save the project, and click again on the "Run" button. This time the binary will be created using the RTEMS Cross compiler for the GR740 board that you selected, and it will execute using a SPARC/Leon built-in emulator. The output should be the same as before:
 +
 
 +
:[[File:ClipCapIt-221116-143903.PNG]]
 +
 
 +
 
 +
... except for the timings, as the Leon emulator does not reproduce the waiting periods correctly (the 1 second beween each trigger isn't right). If you download this binary on a real board however it should work as expected.

Revision as of 13:40, 16 November 2022

Introduction

This tutorial explains how to quickly build a system using TASTE.

Make sure you have either installed the TASTE Virtual machine : https://download.tuxfamily.org/taste/TASTE-VM-10-64bit.ova

...or that you made a manual installation following the instructions here: Manual installation on a native platform

If you use the VM, note that the username and password to login are taste / tastevm

Important

Always make sure you are using the latest version of the TASTE tools. From within the TASTE Virtual machine or your native installation, open a terminal and run the following commands:

  $ cd tool-src
  $ ./Update-TASTE.sh

When it is done, close the current window and open a new terminal.

Hello World

This tutorial explains how to create a basic system to get familiar with the tool.

Create a new project

Run the following command:

  $ taste

You will be prompted for a project name and a new folder with this name will be created. Always use the taste command to re-open an existing project.

The Space Creator editor will show up:

ClipCapIt-221116-133346.PNG

Build the system logical architecture

In the main window, draw a rectangle while pressing the mouse right button. When you release the mouse button, a contextual menu offers to create a function or a function type:

ClipCapIt-221116-133603.PNG

Choose "Function", and rename the box:

ClipCapIt-221116-133927.PNG

Create a second function next to it.

Then keep the Ctrl key and the left mouse button clicked to draw a line between the two functions:

ClipCapIt-221116-134009.PNG

When you release the mouse button, a connection will appear and a dialog will let you name this connection:


ClipCapIt-221116-134200.PNG

You can select the "kind" of connection this is. It can be an asynchronous message (sporadic) or a simple, immediate function call (e.g. unprotected).

Add a connection in the other direction by using Ctrl+Left Click from the function on the right and releasing the keys when hovering on the left function. If you name it "Hi", it will look like this:

ClipCapIt-221116-134541.PNG

Last, we will add a cyclic interface to the "caller" function. To do this, right click on the Caller function and choose the "Provided Interface" option from the menu entry:

ClipCapIt-221116-134816.PNG

In the dialog, name it ("trigger", choose "Periodic" for the kind attribute, and leave the period to 1000 ms:

ClipCapIt-221116-134925.PNG

Create data types

TASTE software works with data, and relies on well defined data structures. They are captured with the ASN.1 language.

On the Workspace area of the editor you will see a file with the ".asn" extension. The file name itself is the name of your project. Double click on this file to open the editor. The default file contains a lot of built-in documentation to help you with the syntax of the language.

For this example we will create a type to store a simple counter with a range of values from 0 to 3:

ClipCapIt-221116-135538.PNG

After this is done, go back to the main diagram by selecting the file named "interfaceview.xml". Note that you may also split the window in the IDE to view both files at the same time.

Select the implementation language of each function

To create an implementation of the system, we have to select a language for each function (caller and callee). We will use C for the callee and SDL for the caller. To do this, double click on each function, and select the tab named "Implementations". Change the language accordingly (the default being SDL, there is no need to touch the caller function):

ClipCapIt-221116-135952.PNG


Implement the functions

We start with the "callee" function. Right click on the function and select "Edit Implementation" from the contextual menu. After being prompted to save the model (do it), wait a few seconds to enter the C editor in the IDE:

ClipCapIt-221116-140250.PNG

Edit the code at will. The IDE provides auto-completion and on-the-fly syntax and semantic checks:

ClipCapIt-221116-140500.PNG

When you are done, go back to the main diagram editor (double click on "interfaceview.xml" in the workspace on the left).

Right-click on Caller and choose "Edit Implementation". This will open the SDL editor (OpenGEODE).

ClipCapIt-221116-140708.PNG

If you are not familiar with SDL, a complete documentation is built-in the tool (on the right). Double click on the Caller block to enter the state machine editor.

You can create the state machine using the set of symbols on the left of the editor. In this example, when the periodic trigger is received, the "Hello" message will be sent (to the callee function), and then the "Hi" message will be expected in return. After a few cycles, we enter a state named "Enough" and stop repeating this polite exchange.

ClipCapIt-221116-142433.PNG

You may want to visualize this simple state machine with a "statechart" representation. Click on the corresponding tab on top of the editor:

ClipCapIt-221116-141927.PNG

You may now save the model and quit OpenGEODE, to get back to the main interface view.

Quick build and run

At this stage you can already build the system. Click on the "Play" button on the bottom left corner of the tool:

ClipCapIt-221116-142131.PNG


After a few seconds of build, you will see the system run in a console:

ClipCapIt-221116-142547.PNG

When you do Ctrl-C to stop the application you can visualize a log of the execution in a file that was generated and that appeared in the workspace:

ClipCapIt-221116-142758.PNG

Create a deployment to run on target

This quick build produced a Linux binary. But you may want to build on a different platform, for example a Leon processor with the RTEMS6 Qualified RTOS.

To do this you need to model the deployment of your system. On the workspace, right-click on "Other files" and choose "Add new"

ClipCapIt-221116-143200.PNG

In the dialog select "Deployment View file":

ClipCapIt-221116-143234.PNG


Then on the next screen you may rename it, but keep the ".dv.xml" file extension:

ClipCapIt-221116-143320.PNG

This will open a new editor, from which you can drag and drop deployment boards. Select for example this one:

ClipCapIt-221116-143650.PNG

When you right click on the board, you can bind the functions (caller and callee) to it.

Save the project, and click again on the "Run" button. This time the binary will be created using the RTEMS Cross compiler for the GR740 board that you selected, and it will execute using a SPARC/Leon built-in emulator. The output should be the same as before:

ClipCapIt-221116-143903.PNG


... except for the timings, as the Leon emulator does not reproduce the waiting periods correctly (the 1 second beween each trigger isn't right). If you download this binary on a real board however it should work as expected.