Merge branch 'main' into blog-package

vinzbarbuto · web-flow · commit 13cba1263773 · 2024-12-11T19:52:59.000+01:00
diff --git a/docs/embedded/patmos.mdx b/docs/embedded/patmos.mdx
@@ -0,0 +1,70 @@
+---
+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.
+## 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, 
+}
+
+main reactor {
+	reaction(startup) {=
+		printf("Hello World!\n");
+	=}
+}
+  
+
+```
+You can generate C code using `lfc HelloPatmos.lf` command in the above folder:
+
+```
+cd test/C/src/patmos/
+lfc HelloPatmos.lf
+```
+
+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:
+
+```
+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 HelloPatmos
+```
+
+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:
+
+```
+Hello World!
+---- Elapsed logical time (in nsec): 0
+---- Elapsed physical time (in nsec): 3,459,000
+```
diff --git a/docs/reference/target-declaration.mdx b/docs/reference/target-declaration.mdx
@@ -42,7 +42,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**single-threaded**](#single-threaded): Specify to not use multithreading.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
@@ -104,7 +104,6 @@ rs={
     build-type: <Debug, Release, RelWithDebInfo, or MinSizeRel>,
     cargo-features: <array of strings>,
     cargo-dependencies: <list of key-value pairs>,
-    export-dependency-graph: <true or false>,
     rust-include: <array of strings>,
     single-file-project: <true or false>,
     single-threaded: <true or false>,
@@ -380,10 +379,10 @@ This option takes a path as string argument to a folder containing an alternativ
 <ShowIf c py ts>
 This target does not support the `export-dependency-graph` target option.
 </ShowIf>
-<ShowIf cpp rs>
+<ShowIf cpp>
 This parameter takes arguments `true` or `false` to specify whether the compiled binary will export its internal dependency graph as a dot graph when executed. This is a debugging utility.
 <ShowOnly rs>
-If a [CLI](#command-line-arguments) is generated, the target property is ignored, and the user should instead use the `--export-graph` flag of the generated program.
+This feature works when a [CLI](#command-line-arguments) option is enabled and the user use the `--export-graph` flag of the generated program.
 </ShowOnly>
 </ShowIf>
 </ShowIfs>
@@ -477,10 +476,10 @@ The `logging` option is one of `ERROR`, `WARN`, `INFO`, `LOG` or `DEBUG`. It spe
 ## no-compile
 
 <ShowIfs>
-<ShowIf ts rs >
+<ShowIf ts>
 This target does not support the `no-compile` target option.
 </ShowIf>
-<ShowIf c cpp py>
+<ShowIf c cpp py rs>
 If true, then do not invoke a target language compiler nor cmake. Just generate code.
 </ShowIf>
 </ShowIfs>
@@ -534,19 +533,16 @@ This argument takes a string (with quotation marks) containing any tag, branch n
 This target does not support the `rust-include` target option.
 </ShowIf>
 <ShowIf rs>
-This specifies a set of Rust modules in the generated project. See [Linking support files](#linking-support-files).
+This specifies a set of Rust modules in the generated project.
 </ShowIf>
 </ShowIfs>
 
 ## scheduler
 
 <ShowIfs>
-<ShowIf c cpp py ts >
+<ShowIf c cpp py rs ts >
 This target does not support the `scheduler` target option.
 </ShowIf>
-<ShowIf rs>
-This specifies the scheduler to use. See[Target Language Details](<../reference/target-language-details.mdx#scheduler-target-property>).
-</ShowIf>
 </ShowIfs>
 
 ## single-file-project
@@ -556,7 +552,7 @@ This specifies the scheduler to use. See[Target Language Details](<../reference/
 This target does not support the `single-file-project` target option.
 </ShowIf>
 <ShowIf rs>
-If true, enables [single-file project layout](#single-file-layout).
+If true, only main.rs is generated instead of multiple rust source files.
 </ShowIf>
 </ShowIfs>
 
@@ -732,7 +728,6 @@ The generated executable may feature a command-line interface (CLI), if it uses
   - `--timeout <time value>`: override the default timeout mentioned as a target property. The syntax for times is just like the LF one (e.g. `1msec`, `"2 seconds"`).
   - `--workers <number>`: override the default worker count mentioned as a target property. This option is **ignored** unless the runtime crate has been built with the feature `parallel-runtime`.
   - `--export-graph`: export the dependency graph (corresponds to `export-dependency-graph` target property). This is a flag, i.e., absent means false, present means true. This means the value of the target property is ignored and not used as default.
-  - `--log-level`: corresponds to the `logging` target property, but note that the levels have different meanings, and the target property is ignored. See [Logging levels](#logging-levels).
 - parameters of the main reactor are translated to CLI parameters.
   - Each LF parameter named `param` corresponds to a CLI parameter named `--main-param`. Underscores in the LF parameter name are replaced by hyphens.
   - The type of each parameters must implement the trait [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html).
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
@@ -176,6 +176,10 @@ const sidebars: SidebarsConfig = {
           "type": "doc",
           "id": "embedded/arduino"
         },
+        {
+          "type": "doc",
+          "id": "embedded/patmos"
+        },
         {
           "type": "doc",
           "id": "embedded/zephyr"
diff --git a/versioned_docs/version-0.5.0/reference/target-declaration.mdx b/versioned_docs/version-0.5.0/reference/target-declaration.mdx
@@ -43,7 +43,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**threading**](#threading): Whether to use multiple threads.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
diff --git a/versioned_docs/version-0.6.0/reference/target-declaration.mdx b/versioned_docs/version-0.6.0/reference/target-declaration.mdx
@@ -42,7 +42,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**single-threaded**](#single-threaded): Specify to not use multithreading.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
diff --git a/versioned_docs/version-0.7.0/reference/target-declaration.mdx b/versioned_docs/version-0.7.0/reference/target-declaration.mdx
@@ -42,7 +42,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**single-threaded**](#single-threaded): Specify to not use multithreading.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
diff --git a/versioned_docs/version-0.8.0/reference/target-declaration.mdx b/versioned_docs/version-0.8.0/reference/target-declaration.mdx
@@ -42,7 +42,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**single-threaded**](#single-threaded): Specify to not use multithreading.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
diff --git a/versioned_docs/version-0.9.0/embedded/patmos.mdx b/versioned_docs/version-0.9.0/embedded/patmos.mdx
@@ -0,0 +1,70 @@
+---
+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.
+## 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, 
+}
+
+main reactor {
+	reaction(startup) {=
+		printf("Hello World!\n");
+	=}
+}
+  
+
+```
+You can generate C code using `lfc HelloPatmos.lf` command in the above folder:
+
+```
+cd test/C/src/patmos/
+lfc HelloPatmos.lf
+```
+
+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:
+
+```
+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 HelloPatmos
+```
+
+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:
+
+```
+Hello World!
+---- Elapsed logical time (in nsec): 0
+---- Elapsed physical time (in nsec): 3,459,000
+```
diff --git a/versioned_docs/version-0.9.0/reference/target-declaration.mdx b/versioned_docs/version-0.9.0/reference/target-declaration.mdx
@@ -42,7 +42,7 @@ A target specification may have optional parameters, the names and values of whi
 - [**protobufs**](#protobufs): An array of .proto files that are to be compiled and included in the generated code.
 - [**runtime-version**](#runtime-version): Specify which version of the runtime system to use.
 - [**rust-include**](#rust-include): (Rust only) A set of Rust modules in the generated project.
-- [**scheduler**](#scheduler): (C only) Specification of the scheduler to us.
+- [**scheduler**](#scheduler): (C only) Specification of the scheduler to use.
 - [**single-file-project**](#single-file-project): (Rust only) If true, enables [single-file project layout](#single-file-layout).
 - [**single-threaded**](#single-threaded): Specify to not use multithreading.
 - [**timeout**](#timeout): A time value (with units) specifying the logical stop time of execution. See [Termination](../writing-reactors/termination.mdx).
@@ -104,7 +104,6 @@ rs={
     build-type: <Debug, Release, RelWithDebInfo, or MinSizeRel>,
     cargo-features: <array of strings>,
     cargo-dependencies: <list of key-value pairs>,
-    export-dependency-graph: <true or false>,
     rust-include: <array of strings>,
     single-file-project: <true or false>,
     single-threaded: <true or false>,
@@ -380,10 +379,10 @@ This option takes a path as string argument to a folder containing an alternativ
 <ShowIf c py ts>
 This target does not support the `export-dependency-graph` target option.
 </ShowIf>
-<ShowIf cpp rs>
+<ShowIf cpp>
 This parameter takes arguments `true` or `false` to specify whether the compiled binary will export its internal dependency graph as a dot graph when executed. This is a debugging utility.
 <ShowOnly rs>
-If a [CLI](#command-line-arguments) is generated, the target property is ignored, and the user should instead use the `--export-graph` flag of the generated program.
+This feature works when a [CLI](#command-line-arguments) option is enabled and the user use the `--export-graph` flag of the generated program.
 </ShowOnly>
 </ShowIf>
 </ShowIfs>
@@ -477,10 +476,10 @@ The `logging` option is one of `ERROR`, `WARN`, `INFO`, `LOG` or `DEBUG`. It spe
 ## no-compile
 
 <ShowIfs>
-<ShowIf ts rs >
+<ShowIf ts>
 This target does not support the `no-compile` target option.
 </ShowIf>
-<ShowIf c cpp py>
+<ShowIf c cpp py rs>
 If true, then do not invoke a target language compiler nor cmake. Just generate code.
 </ShowIf>
 </ShowIfs>
@@ -534,19 +533,16 @@ This argument takes a string (with quotation marks) containing any tag, branch n
 This target does not support the `rust-include` target option.
 </ShowIf>
 <ShowIf rs>
-This specifies a set of Rust modules in the generated project. See [Linking support files](#linking-support-files).
+This specifies a set of Rust modules in the generated project.
 </ShowIf>
 </ShowIfs>
 
 ## scheduler
 
 <ShowIfs>
-<ShowIf c cpp py ts >
+<ShowIf c cpp py rs ts >
 This target does not support the `scheduler` target option.
 </ShowIf>
-<ShowIf rs>
-This specifies the scheduler to use. See[Target Language Details](<../reference/target-language-details.mdx#scheduler-target-property>).
-</ShowIf>
 </ShowIfs>
 
 ## single-file-project
@@ -556,7 +552,7 @@ This specifies the scheduler to use. See[Target Language Details](<../reference/
 This target does not support the `single-file-project` target option.
 </ShowIf>
 <ShowIf rs>
-If true, enables [single-file project layout](#single-file-layout).
+If true, only main.rs is generated instead of multiple rust source files.
 </ShowIf>
 </ShowIfs>
 
@@ -732,7 +728,6 @@ The generated executable may feature a command-line interface (CLI), if it uses
   - `--timeout <time value>`: override the default timeout mentioned as a target property. The syntax for times is just like the LF one (e.g. `1msec`, `"2 seconds"`).
   - `--workers <number>`: override the default worker count mentioned as a target property. This option is **ignored** unless the runtime crate has been built with the feature `parallel-runtime`.
   - `--export-graph`: export the dependency graph (corresponds to `export-dependency-graph` target property). This is a flag, i.e., absent means false, present means true. This means the value of the target property is ignored and not used as default.
-  - `--log-level`: corresponds to the `logging` target property, but note that the levels have different meanings, and the target property is ignored. See [Logging levels](#logging-levels).
 - parameters of the main reactor are translated to CLI parameters.
   - Each LF parameter named `param` corresponds to a CLI parameter named `--main-param`. Underscores in the LF parameter name are replaced by hyphens.
   - The type of each parameters must implement the trait [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html).
diff --git a/versioned_docs/version-0.9.0/sidebars.ts b/versioned_docs/version-0.9.0/sidebars.ts
@@ -176,6 +176,10 @@ const sidebars: SidebarsConfig = {
           "type": "doc",
           "id": "embedded/arduino"
         },
+        {
+          "type": "doc",
+          "id": "embedded/patmos"
+        },
         {
           "type": "doc",
           "id": "embedded/zephyr"
diff --git a/versioned_sidebars/version-0.9.0-sidebars.json b/versioned_sidebars/version-0.9.0-sidebars.json
@@ -162,6 +162,10 @@
           "type": "doc",
           "id": "embedded/arduino"
         },
+        {
+          "type": "doc",
+          "id": "embedded/patmos"
+        },
         {
           "type": "doc",
           "id": "embedded/zephyr"
