POLIS hands-on laboratory session

 

The self-guided lab session will teach you how to specify, simulate and synthesize in the POLIS co-design environment. At this point we assume that, after today’s lecture or reading the User’s Manual and/or the POLIS book, you are familiar with the Polis design flow, the ESTEREL Programming Language and the CFSM model of computation.

 

The Lab is divided into three different parts:

 

    1. Playing with Pre-designed Dashboard Controller
    2. Esterel Introductory Tutorial
    3. Specification and Simulation of Seat Belt Alarm Controller

 

In case of troubles, either ask the instructor or look at the last section.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1 Playing with the Pre-designed Dashboard Controller

 

In this part of the tutorial you will

 

  1. Simulate the controller to visualize behavior (virtual prototype)
  2. Simulate the controller to verify performance
  3. Compile the controller into hardware and software
  4. Look at the synthesized software and RTOS
  5. Modify the micro-controller choice (architecture)

 

1.1 Simulate behavior

 

First, starting from your home directory:

 

cd dac_demo

 

have a look at the Esterel source file for the seat belt controller:

 

vi belt.strl

 

(any other text editor that is available on your platform can be used, of course).

After the copyright notice and comments (identified by the % character) illustrating input and output signals, you have the list of inputs (keyword input), outputs (keyword output) and constant parameters (keyword constant). Parameters can be changed at simulation time to evaluate the effect of, in this case, different timeouts.

This controller implements the five second timeouts by using a micro-controller peripheral, and then scaling it in software. The weak abort statement is used to exit the loop when a sufficient number (specified by the CONST_PRE_SCAL_5 and CONST_PRE_SCAL_10 parameters) of OC_END input events have been received from the micro-controller timing unit.

 

Now compile the Esterel source files into annotated C models:

 

make ptl

 

and examine the output of the compilation of the seat belt controller:

 

vi ptolemy/z_BELT_0.c

 

after a prologue with several macros and include files, there is a function called _cpu_z_BELT_0 that, given a processor name, returns its index in the list of processors used to characterize the execution times of this CFSM in software. Then there is a function used to re-initialize the simulation, and we can find the transition function of the CFSM, implemented by _t_z_BELT_0.

Local variables are required to take the atomic input snapshot, are are copied from the global value buffers at the beginning. Then macro startup(proc); also copies the event presence flags.

The behavior is implemented as an s-graph, annotated with delays with the macro DELAY (one clock cycle annotation for each CPU mentioned in _cpu_z_BELT_0).

 

Now you can go to the simulation directory:

 

cd ptolemy

 

and compile the simulation models:

 

make all

 

Start the Ptolemy simulation interface:

 

pigi test_dac_demo

 

and wait for the picture of the astronomer to pop up. Iconify it.

Now you can look at architectural parameters, by typing the

 

e

 

command in the window showing the top-level netlist (the testbench), with the cursor away from any component instance (to show the global parameters instead of the component-specific ones). The parameters describe

 

Now you can run the behavioral simulation by setting the default implementation to HW (change the parameter and hit apply) and typing

 

R

 

A form with the simulation controls appears. Hit GO and play with the controls (you may need to move the window up from its default position):

As you move things around, dials should move and displays should change values.

 

1.2 Simulate performance

 

After the simulation ends (or you kill it with the ABORT button), you can change the default implementation back to SW. The new simulation should have exactly the same behavior as before. Also, you can check by looking at the missed deadline log file that there are no problems (except, perhaps, on the system testbench components):

 

cat ~/over.txt

Now you can try to reduce the speed of the processor, say to 1 MHz, and run the simulation again. The behavior still looks reasonable (in order to notice anything you should go at 0.01 MHz), but now over.txt logs a lot of missed deadlines.

You can also examine the hierarchy, by going over the system CFSM netlist (the large galaxy in the center) with the cursor and typing

 

i

 

Then you can look at the top right galaxy, the seat belt controller, in the same way, and examine all the stars (CFSMs) inside.

 

If you look inside the BELT star, you should see the Esterel source. If you type , (a comma) over it you should get some information about its cost and the meaning of its parameters. The parameter list can be obtained by typing e with the cursor over it.

 

The oc_prog_rel star is an example of a micro-controller peripheral (a programmable re-startable timer). The N parameter tells RTOS generation to implement it by using the second (out of five) timer channels on the 68HC11 micro-controller.

 

1.3 Synthesize hardware and software

 

Now you can close the simulator (type control-D in the simulator console, at the top left) and

 

cd ..

make 68hc11e9

 

The Makefile first of all recompiles all Esterel files into a single SHIFT file (instead of one file per CFSM, as was done before for co-simulation), and then performs

 

Finally, the Makefile pulls the peripheral programming files out of the POLIS library and makes a local copy. In this first synthesis run, the micro-controller (a Motorola 68hc11e9) does not include an on-board PWM generator. That peripheral is not pulled out of the library, but is synthesized from its CFSM specification.

 

1.4 Look at synthesized software

 

cd dac_demo_part_sg

vi z_BELT_0.c

 

As you can see, the synthesized software is the same as in the Ptolemy simulation, but without the delay characterization.

Inputs are read by the detect_<event_name>_to_<CFSM_name> macros, that are defined by the RTOS (file os.c).

Outputs are mitted by the emit_<CFSM_name>_<event_name> functions, that are also defined by the RTOS.

Arithmetic operations use macro names that are also defined in C by os.c.

 

Curious people can also have a look at the generated RTOS, in file os.c, and examine the definition of the emission/detection macros and functions, of the various tables that customize the RTOS, of the scheduler, and so on.

 

The peripheral driver routines of the oc_prog_rel timer service that we considered earlier can be found by executing:

 

vi $POLIS/polis_lib/sw/peripherals/68hc11/timer/oc_prog_rel.c

 

You can see (after the initial blank lines) how the driver routines implement event emission and detection primitives. Communication with the timer unit peripheral is performed exactly like with any other CFSM. For example, deliver_e_OC_START_to_oc_prog_rel uses the value of event OC_START, contained in variable v_OC_START, to tell the timer unit when the end-of-count output should be generated, relative to the current value of the free-running counter _r_hc11tcnt. The end-of-count event can be delivered either by polling or by interrupt, depending on the designer’s choice (using a set_sw_attr command to override the default polling implementation).

 

The synthesized hardware is, unfortunately, unreadable, because the current release of POLIS produces only BLIF and XNF (gate-level) outputs. The next version will produce synthesizable (and simulatable) VHDL as well.

 

1.5 Change architecture

 

You can now try to generate hardware and software for a different micro-controller (with a PWM generator on board, instead of a syntehsized one), by executing:

 

make clean

make 68hc11gauss

 

You will notice that this time hardware synthesis is much faster, because only a small amount of glue logic (debouncers for the external inputs) needs to be synthesized.

 

 

 

 

2 Esterel: An Introductory Tutorial

 

This tutorial provides a quick introduction to the basic constructs of Esterel. For a complete description of the language, we recommend to read "The Esterel v5 Language Primer" by G. Berry. In this Section we first present a small example that shows how to run Esterel simulations, then we introduce the constructs that will be used use in the rest of the lab.

 

2.1 A small example (from "The Esterel Primer").

 

Specification:

"Emit output O as soon as input I has occurred n times.

Reset this behavior each time the input R occurs".

 

The Esterel file, to be created in esterel_ex/ex1.strl, is:

 

module Example:

constant n: integer;

input I, R;

output O;

loop

await n I;

emit O;

each R;

end module

 

To run the Esterel simulation, apply the following steps:

0. cd esterel_ex

  1. esterel –simul ex1.strl
  2. vi ex1.h (with a single statement, #define n 10)
  3. cc –c ex1.c
  4. cc –o ex1 ex1.o -L$ESTERELHOME/lib –lxes
  5. Run the executable ex1
  6. Click on tick in the simulation main panel. In the panel displaying the esterel code await assumes color red and each is underlined. This mean they are being executed right now.
  7. Click on I, tick in the simulation main panel. Repeat this action three times. Output O becomes red.
  8. Click on R and tick.
  9. Repeat point 6. and 7.

 

Note that the value of the constant n is defined in the file ex1.h In this case, we have defined it to be three.

 

 

 

Review of useful Esterel constructs

 

  1. Loop.
  2.  

    loop

    ...

    end

     

    The loop statement loops forever.

     

  3. Await.
  4.  

    await I

     

    Delay statement that terminates when I occurs.

     

    await n I

     

    It counts n occurrences of the event I and only then yields control to the next statement.

     

  5. Emit.
  6.  

    emit O

     

    Emission of a signal O is an instantaneous statement.

     

  7. Abort.
  8.  

    abort

    p

    when S

     

    The abort .... when statement executes p until the signal S is detected and then is instantaneously killed. Using the weak abort ... when statement the body p is executed a last time at abortion time.

     

    Example:

     

    abort

    loop

    emit A;

    await B;

    emit C;

    await D;

    end;

    when [ R1 or R2] ;

     

    The internal loop is aborted as soon as any of the input signals R1 or R2 occurs.

     

  9. Loop ... each

 

Temporal loop: loop + strong abortion statement.

loop

p

each d

 

is equivalent to:

loop

abort

p; halt

when d

end

 

6. Every do

 

Temporal loop:

 

every d do

p

end

 

is equivalent to:

 

await d

loop

p

each d

 

3 Specification and Simulation of Seat Belt Alarm Controller

 

In this part of the tutorial you will

 

  1. Write an Esterel file for the controller.
  2. Simulate controller with Esterel simulator for correctness.
  3. Write an Esterel file for the timer.
  4. Simulate timer with Esterel simulator for correctness.
  5. Compile Esterel description into Ptolemy stars and create testbed for simulation in Ptolemy.
  6. Do functional Simulation using Ptolemy Co-simulation framework
  7. Do performance simulation using Ptolemy Co-simulation framework.

 

Suppose that we want to specify a simple safety function of

Automobile: a seat belt alarm. A typical specification given to a designer would be:

 

"Five seconds after the key is turned on, if the belt has not been fastened, an alarm will beep for ten seconds or until the key is turned off."

 

We will use two interacting modules to realize this specification: a controller, and a timer. The specification of the controller can be represented in a reactive finite state form as follows:

 

3.1 Create Esterel file for controller

 

First, starting from your home directory:

 

mkdir ~/belt

cd ~/belt

 

Create a file with the name belt_control.strl that has the following characteristic:

 

  1. name of module is: belt_control
  2. inputs are all pure events: reset, key_on, key_off, belt_on, end_5, and end_10.
  3. outputs are: start_timer (a pure event), and alarm (an event with data part typed Boolean).
  4. has the behavior specified above.

You may use some or all of the following construct in the body of the module

 

loop Statement end

abort Statement when DelayExpression

emit SignalIdentifier ( Expression)

;

every DelayExpression do Statement end

or

emit SignalIdentifier

await DelayExpression

 

Recall that in Esterel, DelayExpression can be defined by the occurrence of some signal. Also be careful about () and []. () is used to denote data while [] is used to group statements.

 

Convince yourself that this Esterel file indeed has the same functionality as the FSM above.

 

3.2 Esterel simulation of the controller

 

 

Compile the Esterel file for simulation with the following two commands:

 

esterel –simul belt_control.strl

cc –o belt_control belt_control.c -L$ESTERELHOME/lib -lxes

 

and simulate it:

 

belt_control

 

At this point, you should get the x-window simulation interface of Esterel. you should

 

  1. click on tick to output any initial events.
  2. click on key_on, then tick, and see that start_timer is emitted
  3. click on end_5, then tick, and see alarm output alarm(true)
  4. click on belt_on, then tick, and see alarm output alarm(false)

 

Note the color change on and around the keyword and statement of the esterel code as it is being executed.

 

 

 

3.3 Create Esterel file for timer

 

 

Create the file timer.strl that corresponds to the functionality of timer. The timer should have the following characteristics:

 

  1. module name: timer
  2. constant declaration for count_5 and count_10, both integers.
  3. input pure events: msec, start_timer
  4. output pure events: end_5, end_10
  5. The functionality of the timer is: Every time a start_timer occurs, wait for count_5 msec and output end_5, wait for another count_10 msec and output end_10. If these operation is not completed when the new start_timer comes in, start over and discard the current computation.

 

Some of the statements you may want to use are:

 

every DelayExpression do Statement end

await Constant SignalIdentifier

emit SignalIdentifier

 

Convince yourself that the Esterel file you wrote does satisfy the requirements.

 

3.4 Esterel Simulation of timer

 

Create the file timer.h containing the following two lines:

 

#define count_5 5

#define count_10 10

 

This will serve as constant definition for Esterel simulation. To be correct, it should be 5000 and 10000 respectively, but for the purpose of Esterel simulation, we will scale it down to 5 and 10 for now.

 

Compile the Esterel file for simulation with the following two command:

 

esterel –simul timer.strl

cc –o timer timer.c –L$ESTERELHOME/lib –lxes

 

and then to start the simulation:

 

timer

 

At this point, you should get the x-window simulation interface of Esterel. you should

a. in main panel, select command-keep inputs

  1. click on: tick, start_timer, tick,start_timer msec,tick,tick,tick,tick
  1. now you should see end_5 event gets emitted
  2. do "tick" 10 more times, and see end_10 gets emitted
  3. you may want to throw in a start_timer before the counting is complete and see the count get restarted.

 

3.5 Convert Esterel description into Ptolemy stars and create simulation testbed

 

We will first need to convert the esterel file to a form that is simulatable in Ptolemy with Polis semantics. Create a file Makefile.src containing the following:

 

TOP = belt

STRL = belt_control.strl timer.strl

PTLUC = -a 68hc11 –a 68332

 

belt will be the top level design name, and STRL define the esterel files involved, while PTLUC define the processor that is being considered. They will come into play when one performs co-simulation in the next section.

 

Generate a Makefile from this source by executing

 

makemakefile

 

We should now compile esterel into delay augmented C-file for simulation and also generate all necessary wrapper for ptolemy simulation. This can be done as follows:

 

mkdir ptolemy

make ptl

 

Look at the screen printouts to see what is actually done for you by the Makefile. We are now ready to start building up simulation block in Ptolemy. Go to the ptolemy directory and start the Ptolemy simulator:

 

cd ptolemy

pigi belt

 

You should wait for the picture of Ptolemy, then click OK.

 

A summary of useful Ptolemy commands is shown below. You can access most of these command also by menu, The Schematic menu (generic netlist commands) is activated by the CTL-middle mouse button and the pigiRPC menu (simulation-specific commands) is activated by the SHIFT-middle mouse button.

 

Create Star *

Open palette O

Create/Copy c

Full Screen f

Pan p

Zoom-in z

Zoom-out Z

Close-window CTL-D

Select s

Unselect u

Undo U

Move m

Delete D

Create-icon @

Open-facet F

Look-inside i

Edit Parameter e

Run R

Get info ,

Save window S

 

The delete key can be used to erase a point, box or line segment if it has been incorrectly entered, while CTL-U erases the complete list of points, boxes and lines.

Saving netlists (galaxies) periodically, by typing

 

S

 

on top of their window is generally a good idea.

 

If you are short of time, you can avoid some graphical editing by copying all (or some) pre-designed stars and netlists to your current directory (belt/ptolemy):

 

cp –r $POLIS/examples/lab/belt/{belt_control,timer,belt,test_belt} .

 

If you copy only the netlists make sure that you used the exact names of inputs and outputs in the Esterel modules.

 

To create a Ptolemy star from an Esterel file, type

 

*

 

in the belt window.

The name of the star is belt_control, Domain is DE for discrete event. Star src directory will be the directory where the ptolemy wrapper is created, in this case, it should be ~/belt/ptolemy. The pathname of the Palette should remain ./user.pal That is where you can find the star you just created.

 

Do the same thing for timer

 

After we have created the computation nodes, we will create a design that contains these two interacting CFSMs. Open the user.pal palette to access the stars that we just created:

 

O

 

Scroll down with middle mouse button to get to ./user.pal and select it, then click OK Go back to the belt window, and make a point by clicking the left mouse button. In user.pal window, put the cursor on top of controller, type:

 

c

 

This should create a copy of the belt_control.

In order to get the full screen view, type:

 

f

 

If you need to pan around the screen, the center of the screen will move to the cursor point if you type:

 

p

 

Pan until the belt_control icon is at the top center edge of the screen. Create a point well below it by clicking the left mouse button, and copy timer over from the user.pal

 

If you ever need to zoom in at an area, drag it a box around it with the left mouse button, then type:

 

z

 

You can now close user.pal by typing

 

CTL-D

 

on top of the window.

 

Never close any window with methods provided by the window manager, since this will terminate the Ptolemy application. Always use CTL-D, Cancel, Close, OK supplied by Ptolemy.

 

You may want to move the icons around. To do so, first you need to select the icon by typing:

 

s

 

on top of the icon. Alternative, you can first drag out an area for selection with the left mouse button. Unselect is done by

 

u

 

while general undo is done by

 

U

 

After an object is selected, you can move its outline by means of the right mouse button, and then type:

 

m

 

Remember to unselect with u an object after you have moved it.

To delete an object, select it first, and type

 

D

 

Now we need to create output and input ports. Open the palette called system and copy over the input and output icon. You will need 5 input icon and 1 output icon.

 

Space the icons so that you will be able to create the following screen:

 

To create a connection between the port and e_reset signal pin, put the cursor at the edge of the port, and make a point with left mouse button, click on that point again and drag with left mouse button till destination point, let go, and type:

 

c

 

Never use boxes to create connections. If they appear because of incorrect clicking, remove them with delete.

To create jags in the line, let go the left mouse button before dragging it in a different direction. Complete all the connection according to the figure.

 

To name the port, put the cursor on top of the top most input port, and type:

 

"reset"c

 

You can see what you typed in the Ptolemy command window. Continue till all ports are named. Edit the target of the galaxy by typing:

 

T

 

and choose <parents>, choose OK

 

Put the cursor on top of timer and edit its parameter by typing:

 

e

 

enter 5000 for both end_5 and end_10. Click OK. If the simulation is too fast, just increase those values and run it again.

 

The ptolemy galaxy that represents the seat belt alarm controller is now complete. Create an icon in user.pal by typing:

 

@

 

click on OK to put the galaxy in the user.pal

 

Next, we will build the testbed for the simulation. Open it by typing:

 

 

F

 

Choose the test_belt galaxy, then click OK

 

You will need to create the following schematic for testbed:

 

 

 

 

belt is found in your user.pal. In order to find Absclock put the cursor on top of Polis in user.pal and type:

i

 

to look inside. Likewise, look inside Utility, look inside Sources, and copy over Absclock.

 

TK Button and TK Show Values are in the palette called de.pal (accessed via O). Look inside Signal Sources and Signal Sinks respectively.

 

Position Cursor on an empty portion of the design and type:

 

e

 

to get the parameter list. Fill in

(both file names are relative to your home directory).

Add a new parameter with name Clock_freq, type INT and value 1.

Add another new parameter with name implem, type STRING and value HW.

 

Edit the parameter of the input sources and output sink to give them a meaningful name. Modify the identifiers of TkButtons to reset, key_on, key_off, belt_on, and the label of TKShowValue to alarm

 

 

3.6 Simulation of seat belt alarm controller

 

 

We are finally ready to run the simulation. Go to the test_belt window and type:

 

R

 

and enter 1000000000 for the time stamp to stop. Click on key_on and watch the alarm go briefly on then off again. Feel free to look inside any star, galaxy or universe (i) and change any parameters (e), For information on any star, galaxy or university, type

 

,

 

on top of the object. Note that the Absclock star acts as a real time clock and always emits a token every x msec, where x is defined by the Interval parameter. Clock_freq denotes the hardware and software clock frequency in MHz. If you click on the debug flag in the run control window, the number that you see has a period of (interval*Clock_freq) msec. In this case with both interval and Clock_freq set to 1, the period is 1 msec.

 

Change the implementation of timer to HW and that of belt_control to SW, with the e command over their icons in the belt galaxy. Save the belt and test_belt galaxies by typing

 

S

 

when the cursor is in their windows.

Now exit Ptolemy by typing CTL-D on all the windows, observe the over.txt file in your directory. There are no overflows even for 68hc11 at 1Mhz, so over.txt should be empty.

 

Now you can generate a mixed hardware/software implementation, as specified in Ptolemy, by typing:

 

make hwsw

 

The hardware partition (timer, interfaces and address decoders) is contained in the file belt.blif.

The software partition (belt_control and the OS) is in belt_part_sg. Analyze both of them to understand how the interfacing works.

 

4 System-dependent notes

 

On some software platforms, you will need to add –lsocket at the end of the Esterel-generated software compilation, just after –lxes, in case you get unresolved symbols.

 

On some software platforms, the ~username notation is not supported. In that case, you should execute

 

masters belt

 

in the belt/ptolemy directory, and replace the pathname (including the initial tilde "~") up to the current directory with the relative pathname "." (a dot).

 

Sometimes a Makefile will produce an error message that can be safely ignored (and usually will tell you so in the next few lines of output).