diff --git a/docs/embedded/patmos.mdx b/docs/embedded/patmos.mdx index 0b2d56e99..b421eec38 100644 --- a/docs/embedded/patmos.mdx +++ b/docs/embedded/patmos.mdx @@ -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. \ No newline at end of file