From 4c47da1dd8c8cfc2727b4d04196e0ac567a8fd25 Mon Sep 17 00:00:00 2001
From: Marten Lohstroh <marten@berkeley.edu>
Date: Mon, 11 Mar 2024 16:21:26 -0700
Subject: [PATCH] Outdated Patmos docs that need to be updated to reflect
 reactor-c/pull/383

---
 docs/embedded/patmos.mdx | 107 +++++++++++++++++++++++++++++++++++++++
 docs/sidebars.ts         |   6 ++-
 2 files changed, 112 insertions(+), 1 deletion(-)
 create mode 100644 docs/embedded/patmos.mdx

diff --git a/docs/embedded/patmos.mdx b/docs/embedded/patmos.mdx
new file mode 100644
index 000000000..0b2d56e99
--- /dev/null
+++ b/docs/embedded/patmos.mdx
@@ -0,0 +1,107 @@
+---
+title: Patmos
+description: Developing LF Programs for Patmos.
+---
+# Overview
+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.
+
+### 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
+
+The reactor can be executed on the SW simulator with:
+
+    pasim Minimal.elf
+
+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:
+
+```
+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
+```
+
+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);
+    =}
+}
+```
+
+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:
+
+```
+...
+[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
+...
+```
+
+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
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index f13025991..310541eed 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -182,11 +182,15 @@ const sidebars: SidebarsConfig = {
         },
         {
           "type": "doc",
-          "id": "embedded/zephyr"
+          "id": "embedded/patmos"
         },
         {
           "type": "doc",
           "id": "embedded/rp2040"
+        },
+        {
+            "type": "doc",
+            "id": "embedded/zephyr"
         }
       ]
     },