Skip to content

Commit 30adc83

Browse files
EhsanKhodadadEhsanKhodadad
committed
Patmos docs updated to reflect pull 383
1 parent 4c47da1 commit 30adc83

File tree

1 file changed

+88
-78
lines changed

1 file changed

+88
-78
lines changed

‎docs/embedded/patmos.mdx

+88-78
Original file line numberDiff line numberDiff line change
@@ -7,101 +7,111 @@ Lingua Franca's C-runtime supports [Patmos](https://github.com/t-crest/patmos),
77
a bare-metal execution platform that is optimized for time-predictable execution.
88
The time-predictability aspect of Patmos makes it easier to obtain a worst-case
99
execution time (WCET) for reactions.
10-
10+
## Prerequisites
11+
- Linux or macOS development system. (use WSL on Windows)
12+
- DE2-115 Development Kit, which is equipped with Altera Cyclone IV FPGA (optional)
13+
### Getting Started
14+
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)
1115
### Compiling and Running Reactors
12-
Patmos can run in an FPGA, but there are also two
13-
simulators available:
14-
15-
1. `pasim` a software ISA simulator that is written in C++.
16-
2. `patemu` a cycle-accurate hardware emulator generated from the hardware description.
17-
18-
To execute reactions on Patmos, the [Patmos toolchain](https://github.com/t-crest/patmos) needs
19-
to be installed. The web page contains a quick start, detailed information including how to
20-
perform WCET analysis is available in the
21-
[Patmos Reference Handbook](http://patmos.compute.dtu.dk/patmos_handbook.pdf).
22-
23-
To execute the "hello world" reactor on Patmos use the LF compiler to generate the C code.
24-
Compile the reactor with the Patmos compiler (in `src-gen`):
25-
26-
patmos-clang Minimal.c -o Minimal.elf
27-
28-
The reactor can be executed on the SW simulator with:
16+
Patmos can run in an FPGA, but there are also two simulators available:
2917

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

32-
As Patmos is a bare metal runtime that has no notion of calendar time, its start time
33-
is considered the epoch and the following output will be observed:
21+
Consider the following simple LF program inside the HelloWorld.lf file:
22+
```lf-c
23+
target C {
24+
single-threaded: true
25+
}
26+
main reactor {
27+
reaction(startup) {=
28+
lf_print("Hello World!");
29+
=}
30+
}
3431
3532
```
36-
Start execution at time Thu Jan 1 00:00:00 1970
37-
plus 640000 nanoseconds.
38-
Hello World.
39-
Elapsed logical time (in nsec): 0
40-
Elapsed physical time (in nsec): 3970000
33+
After generating C code using `lfc HelloWorld.lf` command, add a Makefile file to compile LF-generated code inside `src-gen/HelloWorld` folder. In this Makefile mention the name of all generated c files, and the pathes of all header files. Here is a sample of such a Makefile file:
34+
```Makefile
35+
LF_PROJECT_ROOT ?= $(CURDIR)/../..
36+
LF_MAIN_TARGET ?= HelloWorld
37+
LF_MAIN_TARGET_LC := $(shell echo $(LF_MAIN_TARGET) | tr '[:upper:]' '[:lower:]')
38+
LIB_PATH := ~/t-crest/local/patmos-unknown-unknown-elf/lib
39+
SERIAL?=/dev/ttyUSB0
40+
41+
INCS := -I"$(LF_PROJECT_ROOT)/include" \
42+
-I"$(LF_PROJECT_ROOT)/include/api" \
43+
-I"$(LF_PROJECT_ROOT)/include/core" \
44+
-I"$(LF_PROJECT_ROOT)/include/core/platform" \
45+
-I"$(LF_PROJECT_ROOT)/include/core/modal_models" \
46+
-I"$(LF_PROJECT_ROOT)/include/core/utils" \
47+
48+
CC := patmos-clang
49+
CFLAGS := -O2 $(INCS) -DINITIAL_EVENT_QUEUE_SIZE=10 -DINITIAL_REACT_QUEUE_SIZE=10 -DLF_SINGLE_THREADED=0 -DLF_REACTION_GRAPH_BREADTH=1
50+
SRC_FILES := _$(LF_MAIN_TARGET_LC)_main.c $(LF_MAIN_TARGET).c lib/schedule.c
51+
SRC_FILES += core/reactor_common.c core/lf_token.c core/reactor.c core/tag.c core/environment.c
52+
SRC_FILES += core/utils/util.c core/utils/vector.c
53+
SRC_FILES += core/utils/pqueue.c core/utils/pqueue_tag.c core/utils/pqueue_base.c
54+
SRC_FILES += core/utils/hashset/hashset_itr.c core/utils/hashset/hashset.c
55+
SRC_FILES += core/clock.c core/platform/lf_atomic_patmos.c core/platform/lf_atomic_irq.c
56+
SRC_FILES += core/platform/lf_patmos_support.c
57+
58+
OBJ_FILES := $(patsubst %.c,%.o,$(SRC_FILES))
59+
EXE_NAME := $(LF_MAIN_TARGET).elf
60+
61+
.PHONY: all clean wcet
62+
63+
all: $(EXE_NAME)
64+
65+
# Target for the executable
66+
$(EXE_NAME): $(OBJ_FILES)
67+
$(CC) $(CFLAGS) -o $@ $^
68+
# Rule to compile C files into object files
69+
$(OBJ_FILES): %.o: %.c
70+
$(CC) $(CFLAGS) -c -o $@ $<
71+
72+
clean:
73+
rm -f $(OBJ_FILES) $(EXE_NAME)
74+
4175
```
4276

43-
The reactor can also be executed on the hardware emulator of Patmos:
77+
Then move this Makefile inside the `src-gen/HelloWorld` folder and run the following make command:
4478

45-
patemu Minimal.elf
79+
make -C src-gen/HelloWorld
4680

47-
This execution is considerably slower than the SW simulator, as the concrete hardware
48-
of Patmos is simulated cycle-accurate.
81+
If you are using an older version of LF that doesn't support Patmos, you need to copy `lf_patmos_support` c and h files in the related folders before executing make command whether manually or by executing the following bash file that automates the copying process (considering those files are located in a folder called `files`)
4982

50-
### Worst-Case Execution Time Analysis
83+
```bash
84+
PROJECT_ROOT="$PWD"
85+
PROJECT_NAME="HelloWorld"
5186

52-
Following example is a code fragment from
53-
[Wcet.lf](https://github.com/lf-lang/lingua-franca/blob/master/xtext/org.icyphy.linguafranca/src/test/C/src/Wcet.lf).
54-
55-
```lf-c
56-
reactor Work {
57-
input in1: int;
58-
input in2: int;
59-
output out:int;
60-
reaction(in1, in2) -> out {=
61-
int ret;
62-
if (in1 > 10) {
63-
ret = in2 * in1;
64-
} else {
65-
ret = in2 + in1;
66-
}
67-
lf_set(out, ret);
68-
=}
69-
}
87+
cp "$PROJECT_ROOT/files/lf_patmos_support.h" "$PROJECT_ROOT/src-gen/$PROJECT_NAME/include/core/platform/"
88+
cp "$PROJECT_ROOT/files/platform.h" "$PROJECT_ROOT/src-gen/$PROJECT_NAME/include/core/"
89+
cp "$PROJECT_ROOT/files/lf_patmos_support.c" "$PROJECT_ROOT/src-gen/$PROJECT_NAME/core/platform/"
90+
cp "$PROJECT_ROOT/files/lf_atomic_patmos.c" "$PROJECT_ROOT/src-gen/$PROJECT_NAME/core/platform/"
91+
cp "$PROJECT_ROOT/files/lf_patmos_support.h" "$PROJECT_ROOT/include/core/platform/"
92+
cp "$PROJECT_ROOT/files/platform.h" "$PROJECT_ROOT/include/core"
7093
```
7194

72-
We want to perform WCET analysis of the single reaction of the Work reactor.
73-
This reaction, depending on the input data, will either perform a multiplication,
74-
which is more expensive in Patmos, or an addition. The WCET analysis shall consider
75-
the multiplication path as the worst-case path. To generate the information for
76-
WCET analysis by the compiler we have to compile the application as follows:
95+
If there is no error after making, an HelloWorld.elf file must be generator inside `src-gen\HelloWorld` folder. Then, the reactor can be executed on the SW simulator with the following command:
7796

78-
patmos-clang -O2 -mserialize=wcet.pml Wcet.c
97+
pasim src-gen\HelloWorld\HelloWorld.elf
7998

80-
We investigate the C source code `Wcet.c` and find that the reaction we
81-
are interested is named `reaction_function1`. Therefore, we invoke WCET analysis
82-
as follows:
99+
After executing the above command, the following lines must be printed.
100+
```
101+
Hello World!
102+
---- Elapsed logical time (in nsec): 0
103+
---- Elapsed physical time (in nsec): 770,000
104+
```
83105

84-
platin wcet -i wcet.pml -b a.out -e reaction_function1 --report
106+
The reactor can also be executed on the hardware emulator of Patmos:
85107

86-
This results in following report:
108+
patemu src-gen\helloworld\HelloWorld.elf
109+
110+
This execution is considerably slower than the SW simulator, as the concrete hardware
111+
of Patmos is simulated cycle-accurate. Here is a sample of its output:
87112

88113
```
89-
...
90-
[platin] INFO: Finished run WCET analysis (platin) in 62 ms
91-
[platin] INFO: best WCET bound: 242 cycles
92-
---
93-
- analysis-entry: reaction_function1
94-
source: platin
95-
cycles: 242
96-
...
114+
Hello World!
115+
---- Elapsed logical time (in nsec): 0
116+
---- Elapsed physical time (in nsec): 3,459,000
97117
```
98-
99-
The analysis gives the WCET of 242 clock cycles for the reaction,
100-
which includes clock cycles for data cache misses.
101-
Further details on the WCET analysis
102-
tool `platin` and e.g., how to annotate loop bounds can be found in the
103-
[Patmos Reference Handbook](http://patmos.compute.dtu.dk/patmos_handbook.pdf).
104-
105-
Note, that the WCET analysis of a reaction does only include the code of the
106-
reaction function, not the cache miss cost of calling the function from
107-
the scheduler or the cache miss cost when returning to the scheduler.

0 commit comments

Comments
 (0)