Skip to content

Commit

Permalink
Merge pull request #255 from EhsanKhodadad/patmos
Browse files Browse the repository at this point in the history 
Patmos docs updated to reflect lf-lang/lingua-franca#2383
  • Loading branch information
@lhstrh
lhstrh authored Oct 28, 2024
2 parents 4c47da1 + 7c39f5f commit 413c7f2
Showing 1 changed file with 46 additions and 83 deletions.
129 changes: 46 additions & 83 deletions docs/embedded/patmos.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,101 +7,64 @@ Lingua Franca's C-runtime supports [Patmos](https://github.com/t-crest/patmos),
a bare-metal execution platform that is optimized for time-predictable execution.
The time-predictability aspect of Patmos makes it easier to obtain a worst-case
execution time (WCET) for reactions.
## Prerequisites
- Linux or macOS development system. (use WSL on Windows)
- DE2-115 Development Kit, which is equipped with Altera Cyclone IV FPGA (optional)
### Getting Started
To know how to install the toolchain for building Patmos, read the Patmos project's readme at https://github.com/t-crest/patmos or study the sixth chapter of its handbook available here: [Patmos Reference Handbook](http://patmos.compute.dtu.dk/patmos_handbook.pdf)
### Compiling and Running Lingua Franca codes
Patmos can run in an FPGA, but there are also two simulators available:

1. `pasim`: a software ISA simulator that is written in C++.
2. `patemu`: a cycle-accurate hardware emulator generated from the hardware description.

Consider the following simple LF program inside the HelloPatmos.lf file located in `test/C/src/patmos/HelloPatmos.lf`:
```lf-c
target C {
platform: "Patmos",
single-threaded: true,
build-type: Debug,
}
### Compiling and Running Reactors
Patmos can run in an FPGA, but there are also two
simulators available:

1. `pasim` a software ISA simulator that is written in C++.
2. `patemu` a cycle-accurate hardware emulator generated from the hardware description.

To execute reactions on Patmos, the [Patmos toolchain](https://github.com/t-crest/patmos) needs
to be installed. The web page contains a quick start, detailed information including how to
perform WCET analysis is available in the
[Patmos Reference Handbook](http://patmos.compute.dtu.dk/patmos_handbook.pdf).

To execute the "hello world" reactor on Patmos use the LF compiler to generate the C code.
Compile the reactor with the Patmos compiler (in `src-gen`):

patmos-clang Minimal.c -o Minimal.elf
main reactor {
reaction(startup) {=
printf("Hello World!\n");
=}
}
The reactor can be executed on the SW simulator with:
```
You can generate C code using `lfc HelloPatmos.lf` command in the above folder:

pasim Minimal.elf
```
cd test/C/src/patmos/
lfc HelloPatmos.lf
```

As Patmos is a bare metal runtime that has no notion of calendar time, its start time
is considered the epoch and the following output will be observed:
If there is no error after making, an executable file must be generator inside `src-gen/patmos/HelloPatmos` folder. Then, the reactor can be executed on the SW simulator with the following command:

```
Start execution at time Thu Jan 1 00:00:00 1970
plus 640000 nanoseconds.
Hello World.
Elapsed logical time (in nsec): 0
Elapsed physical time (in nsec): 3970000
cd ../../src-gen/patmos/HelloPatmos/build
pasim HelloPatmos
```
After executing the above command, the following lines must be printed.
```
Hello World!
---- Elapsed logical time (in nsec): 0
---- Elapsed physical time (in nsec): 770,000
```

The reactor can also be executed on the hardware emulator of Patmos:

patemu Minimal.elf

This execution is considerably slower than the SW simulator, as the concrete hardware
of Patmos is simulated cycle-accurate.

### Worst-Case Execution Time Analysis

Following example is a code fragment from
[Wcet.lf](https://github.com/lf-lang/lingua-franca/blob/master/xtext/org.icyphy.linguafranca/src/test/C/src/Wcet.lf).

```lf-c
reactor Work {
input in1: int;
input in2: int;
output out:int;
reaction(in1, in2) -> out {=
int ret;
if (in1 > 10) {
ret = in2 * in1;
} else {
ret = in2 + in1;
}
lf_set(out, ret);
=}
}
```
patemu HelloPatmos
```

We want to perform WCET analysis of the single reaction of the Work reactor.
This reaction, depending on the input data, will either perform a multiplication,
which is more expensive in Patmos, or an addition. The WCET analysis shall consider
the multiplication path as the worst-case path. To generate the information for
WCET analysis by the compiler we have to compile the application as follows:

patmos-clang -O2 -mserialize=wcet.pml Wcet.c

We investigate the C source code `Wcet.c` and find that the reaction we
are interested is named `reaction_function1`. Therefore, we invoke WCET analysis
as follows:

platin wcet -i wcet.pml -b a.out -e reaction_function1 --report

This results in following report:
This execution is considerably slower than the SW simulator, as the concrete hardware
of Patmos is simulated cycle-accurate. Here is a sample of its output:

```
...
[platin] INFO: Finished run WCET analysis (platin) in 62 ms
[platin] INFO: best WCET bound: 242 cycles
---
- analysis-entry: reaction_function1
source: platin
cycles: 242
...
Hello World!
---- Elapsed logical time (in nsec): 0
---- Elapsed physical time (in nsec): 3,459,000
```

The analysis gives the WCET of 242 clock cycles for the reaction,
which includes clock cycles for data cache misses.
Further details on the WCET analysis
tool `platin` and e.g., how to annotate loop bounds can be found in the
[Patmos Reference Handbook](http://patmos.compute.dtu.dk/patmos_handbook.pdf).

Note, that the WCET analysis of a reaction does only include the code of the
reaction function, not the cache miss cost of calling the function from
the scheduler or the cache miss cost when returning to the scheduler.

0 comments on commit 413c7f2

Please sign in to comment.