From 6824bc0de23130a0900a71371d7887c287d545a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Tue, 23 Apr 2024 00:44:58 +0200 Subject: [PATCH 1/9] Add preliminary docs structure for FlexPRET support --- docs/embedded/flexpret.md | 97 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/embedded/flexpret.md diff --git a/docs/embedded/flexpret.md b/docs/embedded/flexpret.md new file mode 100644 index 000000000..6e6ffa215 --- /dev/null +++ b/docs/embedded/flexpret.md @@ -0,0 +1,97 @@ +--- +title: FlexPRET +description: Developing LF Programs for FlexPRET. +--- +# Overview + +FlexPRET is a precision-timed (PRET) machine designed for mixed-criticality +systems. As of 2024, PRET machines are an open field of research. Refer to its +[github page](https://github.com/pretis/flexpret) for more in-depth information. +FlexPRET either needs to be emulated or run on a Field-Programmable Gate Array +(FPGA). In this guide we will show you how to pair FlexPRET with Lingua Franca, +leaving you with precise software execution. + +As a developer, you should be aware of a significant difference between FlexPRET's +notion of threads versus other platforms. FlexPRET uses fined-grained *hardware* +threads, as opposed to the usual (software) threads. This means that if multiple +threads are running, they can swap every clock cycle. In addition, hardware +threads are designed to be isolated, meaning the execution time of one thread +will not affect the execution time of another, as opposed to concurrent software +threads. Since the threads are implemented in hardware, FlexPRET can only have +a maximum of eight. + +# Prerequisites + +- cmake +- sbt to build FlexPRET + +# Getting started + +## Development environment setup + +1. We start out by setting up a development environment. Clone the +`lf-flexpret-template` from Github: +``` +TODO: Github link with --recurse-submodules +``` +2. Source the `env.bash` or `env.fish` to set up necessary environment variables. You will need to do this every time, so it could be a good idea to add this to your `~/.bashrc`. +``` +source env.bash +``` +``` +source env.fish +``` + +## FlexPRET build + +3. Now we will build the FlexPRET emulator. Step into the FlexPRET directory and build the default configuration with `cmake`. +``` +cd flexpret +cmake -B build && cd build && make +``` + +4. You should now install the FlexPRET build to the FlexPRET software development kit (SDK). This provides the SDK with the necessary knowledge of FlexPRET's hardware configuration, such as the amount of data memory available. +``` +make install +``` + +5. Next, step into the SDK and compile it. This step is strictly speaking not necessary, but it is good to know the system works as expected. +``` +cd ../sdk +cmake -B build && cd build && make && ctest +``` + +## Lingua Franca on FlexPRET + +6. Step back to the top-level directory and compile a sample LF application. +``` +lfc src/Test.lf +``` + +7. Run the compiled program on the FlexPRET emulator. +``` +fp-emu +ispm=src-gen/Test/build/Test.mem +``` + +8. Verify that you see the expected output +``` +TODO: Add expected output +``` + +## Building FlexPRET with another configuration + +TODO: URL +Refer to the [FlexPRET docs](./flexpret/README.md#Configuration) for more information on how to run a non-default and custom FlexPRET configuration. + +# FlexPRET on FPGA + +TODO: Write + +# FlexPRET specific features + + +TODO: Describe and create example program +1. fp_int_on_expire() +2. interrupt temporal isolation + + From e1c0f89252b00148e08e94aa678e73740fc3001f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Tue, 23 Apr 2024 00:45:35 +0200 Subject: [PATCH 2/9] Rename *.md -> *.mdx --- docs/embedded/{flexpret.md => flexpret.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/embedded/{flexpret.md => flexpret.mdx} (100%) diff --git a/docs/embedded/flexpret.md b/docs/embedded/flexpret.mdx similarity index 100% rename from docs/embedded/flexpret.md rename to docs/embedded/flexpret.mdx From 37bccf2a133c9a2426b36186f795cd7ce2aeccfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Tue, 23 Apr 2024 12:25:36 +0200 Subject: [PATCH 3/9] Add troubleshooting section --- docs/embedded/flexpret.mdx | 70 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index 6e6ffa215..f7899c270 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -95,3 +95,73 @@ TODO: Describe and create example program 2. interrupt temporal isolation + +# Troubleshooting + +## Environment not set up + +``` +lfc: warning: No FP_PATH environment variable found +lfc: warning: No FP_SDK_PATH environment variable found +``` + +You probably forgot to `source env.bash` or `source env.fish`. + +## FlexPRET not installed to SDK + +This message means that the SDK did not find a FlexPRET installation. + +``` +Could not find + /lf-flexpret-workspace/flexpret/sdk/flexpret/fp-emu. + Please build FlexPRET and install it here with `cmake --install` to + continue. +``` + +In this case, you need to step into the FlexPRET directory, build FlexPRET (if +not built already) and install it to the SDK. + +``` +cd $FP_PATH +cmake -B build && cd build && make all install +``` + +## Instruction memory full + +An error that looks like this means your program (i.e., your instructions) are +too large to fit inside the instruction memory. + +``` +/opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: HelloWorld.riscv section `.text' will not fit in region `ROM' +/opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: region `ROM' overflowed by 70664 bytes +``` + +There are two possible solutions to this issue: +1. Reduce the size of your program. `printf` is notorious for taking up a lot of +space, so consider replacing it with a lower footprint version. Tip: To inspect +what takes up space in your final executible, use `nm`, like so: +`nm HelloWorld.riscv --size-sort`. +2. Increase the size of the instruction memory. This is done in FlexPRET's +configs (see TODO: LINK: ./flexpret/README.md#Configuration). This is easily +done when emulating FlexPRET, but might not be so simple on an FPGA. + +## Bootloader not found + +This error should only occur if you have specified `fpga` in the board target +property. It means that you do not have a bootloader installed to the FlexPRET +SDK. + +``` +Could not find + /home/magnus/ntnu/mttk/var2024/master/lf-flexpret/flexpret/sdk/flexpret/bootloader.cmake, + which is required to build software for FlexPRET on FPGA using the + bootloader. +``` + +The solution is to build the SDK; it will build the bootloder and automatically +install it. + +``` +cd $FP_SDK_PATH +cmake -B build && cd build && make +``` From b5f23b8b173acd1fbe04c9b00c6bf5ba8dbf4951 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Sun, 19 May 2024 11:28:22 +0200 Subject: [PATCH 4/9] Fix most TODOs --- docs/embedded/flexpret.mdx | 114 ++++++++++++++++++++----------------- 1 file changed, 63 insertions(+), 51 deletions(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index f7899c270..f2295153f 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -4,26 +4,9 @@ description: Developing LF Programs for FlexPRET. --- # Overview -FlexPRET is a precision-timed (PRET) machine designed for mixed-criticality -systems. As of 2024, PRET machines are an open field of research. Refer to its -[github page](https://github.com/pretis/flexpret) for more in-depth information. -FlexPRET either needs to be emulated or run on a Field-Programmable Gate Array -(FPGA). In this guide we will show you how to pair FlexPRET with Lingua Franca, -leaving you with precise software execution. - -As a developer, you should be aware of a significant difference between FlexPRET's -notion of threads versus other platforms. FlexPRET uses fined-grained *hardware* -threads, as opposed to the usual (software) threads. This means that if multiple -threads are running, they can swap every clock cycle. In addition, hardware -threads are designed to be isolated, meaning the execution time of one thread -will not affect the execution time of another, as opposed to concurrent software -threads. Since the threads are implemented in hardware, FlexPRET can only have -a maximum of eight. - -# Prerequisites - -- cmake -- sbt to build FlexPRET +FlexPRET is a precision-timed (PRET) machine designed for mixed-criticality systems. As of 2024, PRET machines are an open field of research. Refer to its [github page](https://github.com/pretis/flexpret) for more in-depth information. FlexPRET either needs to be emulated or run on a Field-Programmable Gate Array (FPGA). In this guide we will show you how to pair FlexPRET with Lingua Franca, leaving you with precise software execution. + +As a developer, you should be aware of a significant difference between FlexPRET's notion of threads versus other platforms. FlexPRET uses fined-grained *hardware* threads, as opposed to the usual (software) threads. This means that if multiple threads are running, they can swap every clock cycle. In addition, hardware threads are designed to be isolated, meaning the execution time of one thread will not affect the execution time of another, as opposed to concurrent software threads. Since the threads are implemented in hardware, FlexPRET can only have a maximum of eight. # Getting started @@ -32,7 +15,7 @@ a maximum of eight. 1. We start out by setting up a development environment. Clone the `lf-flexpret-template` from Github: ``` -TODO: Github link with --recurse-submodules +TODO: Github link with --recurse-submodules && cd lf-flexpret-workspace ``` 2. Source the `env.bash` or `env.fish` to set up necessary environment variables. You will need to do this every time, so it could be a good idea to add this to your `~/.bashrc`. ``` @@ -46,10 +29,12 @@ source env.fish 3. Now we will build the FlexPRET emulator. Step into the FlexPRET directory and build the default configuration with `cmake`. ``` -cd flexpret +cd $FP_PATH cmake -B build && cd build && make ``` +(It is possible to name the build folder something other than `build`, but `bin` is reserved.) + 4. You should now install the FlexPRET build to the FlexPRET software development kit (SDK). This provides the SDK with the necessary knowledge of FlexPRET's hardware configuration, such as the amount of data memory available. ``` make install @@ -57,7 +42,7 @@ make install 5. Next, step into the SDK and compile it. This step is strictly speaking not necessary, but it is good to know the system works as expected. ``` -cd ../sdk +cd $FP_SDK_PATH cmake -B build && cd build && make && ctest ``` @@ -65,36 +50,60 @@ cmake -B build && cd build && make && ctest 6. Step back to the top-level directory and compile a sample LF application. ``` -lfc src/Test.lf +lfc src/HelloWorld.lf ``` 7. Run the compiled program on the FlexPRET emulator. ``` -fp-emu +ispm=src-gen/Test/build/Test.mem +./bin/HelloWorld ``` +(This is just a `bash` script that runs the emulator and passes the correct program binary file to it underneath the hood.) + 8. Verify that you see the expected output ``` -TODO: Add expected output +[0]: ---- Start execution ---- +[0]: Environment 0: ---- Intializing start tag +[0]: Environment 0: ---- Spawning 1 workers. +[1]: Hello world from FlexPRET +[1]: Goodbye ``` -## Building FlexPRET with another configuration +(The `[]` means hardware thread `n` is printing.) -TODO: URL -Refer to the [FlexPRET docs](./flexpret/README.md#Configuration) for more information on how to run a non-default and custom FlexPRET configuration. +# FlexPRET specific features -# FlexPRET on FPGA +Some of FlexPRET's specific features are highlighted in the sample programs. These include `interrupt on expire`, which triggers an interrupt at some scheduled point in time and temporal isolation of hardware threads (i.e., isolated in timing). -TODO: Write +## Interrupt on expire -# FlexPRET specific features +The sample code is available in `src/InterruptExpire.lf`. + +Run the application like so: + +``` +lfc src/InterruptExpire.lf && ./bin/InterruptExpire +``` + +## Temporal isolation + +See `src/multi-threaded/Isolation.lf` for the sample application. The application runs a hardware thread in the background of an LF reactor that triggers every 50 milliseconds. The interrupt handler runs a long `for` loop. On other platforms, the interrupt handler would distrup the timing of the LF reaction. But due to temporal isolation, the LF reaction's timing is unaffected by the interrupts. +Run the application like so: -TODO: Describe and create example program -1. fp_int_on_expire() -2. interrupt temporal isolation +``` +lfc src/multi-threaded/Isolation.lf && ./bin/Isolation +``` + +## Building FlexPRET with another configuration +Refer to the [FlexPRET docs](https://github.com/pretis/flexpret?tab=readme-ov-file#configuration) for more information on how to run a non-default and custom FlexPRET configuration. +# FlexPRET on FPGA + +It is possible to realize FlexPRET on a Field-Programmable Gate Array (FPGA). Refer to [the docs](https://github.com/pretis/flexpret?tab=readme-ov-file#running-on-fpga). + +Please note that for FPGA, only hardware thread 0 is connected to a UART peripheral, meaning only hardware thread 0 can print using that. # Troubleshooting @@ -132,36 +141,39 @@ An error that looks like this means your program (i.e., your instructions) are too large to fit inside the instruction memory. ``` -/opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: HelloWorld.riscv section `.text' will not fit in region `ROM' +/opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: HelloWorld section `.text' will not fit in region `ROM' /opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: region `ROM' overflowed by 70664 bytes ``` There are two possible solutions to this issue: 1. Reduce the size of your program. `printf` is notorious for taking up a lot of -space, so consider replacing it with a lower footprint version. Tip: To inspect +space, so consider replacing it with a lower footprint version (or nothing at all). Tip: To inspect what takes up space in your final executible, use `nm`, like so: -`nm HelloWorld.riscv --size-sort`. -2. Increase the size of the instruction memory. This is done in FlexPRET's -configs (see TODO: LINK: ./flexpret/README.md#Configuration). This is easily -done when emulating FlexPRET, but might not be so simple on an FPGA. +`nm HelloWorld --size-sort`. +1. Increase the size of the instruction memory. This is done in FlexPRET's +configs (see [FlexPRET's README](https://github.com/pretis/flexpret?tab=readme-ov-file#configuration)). This is easily +done when emulating FlexPRET, but might not be so simple when realizing the design on an FPGA. ## Bootloader not found -This error should only occur if you have specified `fpga` in the board target -property. It means that you do not have a bootloader installed to the FlexPRET -SDK. - +This error should only occur if you have specified `fpga` in the board target property. It means that you do not have not built the bootloader in the FlexPRET SDK. ``` -Could not find - /home/magnus/ntnu/mttk/var2024/master/lf-flexpret/flexpret/sdk/flexpret/bootloader.cmake, - which is required to build software for FlexPRET on FPGA using the - bootloader. +/opt/riscv/lib/gcc/riscv32-unknown-elf/11.1.0/../../../../riscv32-unknown-elf/bin/ld: cannot open linker script file bootloader.ld: No such file or directory ``` -The solution is to build the SDK; it will build the bootloder and automatically -install it. +The solution is to build the SDK; it will build the bootloder and generate a `bootloader.ld`. ``` cd $FP_SDK_PATH cmake -B build && cd build && make ``` + +## Hardware vs. software configuration mismatch + +This error occurs if the configuration used to build FlexPRET does not match the hardware configuration installed to FlexPRET's SDK. + +``` +Reset_Handler: 165: Abort:[0]: Hardware and software configuration mismatch (0xef49961d vs. 0x79d84635) +``` + +The solution is to rebuild FlexPRET and install its hardware configuration to the SDK with `make install`. From 4cfdd00aa3cf2d260444c9f97ae77cbbe9d2995a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Wed, 22 May 2024 20:11:59 +0200 Subject: [PATCH 5/9] Finish TODO --- docs/embedded/flexpret.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index f2295153f..ea1eef709 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -15,7 +15,7 @@ As a developer, you should be aware of a significant difference between FlexPRET 1. We start out by setting up a development environment. Clone the `lf-flexpret-template` from Github: ``` -TODO: Github link with --recurse-submodules && cd lf-flexpret-workspace +git clone --recurse-submodules https://github.com/lf-lang/lf-flexpret-template lf-flexpret-workspace && cd lf-flexpret-workspace ``` 2. Source the `env.bash` or `env.fish` to set up necessary environment variables. You will need to do this every time, so it could be a good idea to add this to your `~/.bashrc`. ``` From b5c4fbe009624f8f715cc54eb9845a9ee9012650 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Thu, 23 May 2024 11:56:50 +0200 Subject: [PATCH 6/9] Update docs/embedded/flexpret.mdx Co-authored-by: erling --- docs/embedded/flexpret.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index ea1eef709..13edde09d 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -17,13 +17,7 @@ As a developer, you should be aware of a significant difference between FlexPRET ``` git clone --recurse-submodules https://github.com/lf-lang/lf-flexpret-template lf-flexpret-workspace && cd lf-flexpret-workspace ``` -2. Source the `env.bash` or `env.fish` to set up necessary environment variables. You will need to do this every time, so it could be a good idea to add this to your `~/.bashrc`. -``` -source env.bash -``` -``` -source env.fish -``` +2. Source the `env.bash` to set up necessary environment variables. You will need to do this every time, so it could be a good idea to add this to your `~/.bashrc`. ## FlexPRET build From 7fa4b2fde9c5599e222f5fcaaf69528995303832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Thu, 23 May 2024 11:56:57 +0200 Subject: [PATCH 7/9] Update docs/embedded/flexpret.mdx Co-authored-by: erling --- docs/embedded/flexpret.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index 13edde09d..8abd9e557 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -27,7 +27,6 @@ cd $FP_PATH cmake -B build && cd build && make ``` -(It is possible to name the build folder something other than `build`, but `bin` is reserved.) 4. You should now install the FlexPRET build to the FlexPRET software development kit (SDK). This provides the SDK with the necessary knowledge of FlexPRET's hardware configuration, such as the amount of data memory available. ``` From 60379a372630950b56a2f99eda0d3a2d71d8b7f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Thu, 23 May 2024 11:59:52 +0200 Subject: [PATCH 8/9] Rephrase weird sentence --- docs/embedded/flexpret.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index 8abd9e557..0287b12ee 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -27,8 +27,7 @@ cd $FP_PATH cmake -B build && cd build && make ``` - -4. You should now install the FlexPRET build to the FlexPRET software development kit (SDK). This provides the SDK with the necessary knowledge of FlexPRET's hardware configuration, such as the amount of data memory available. +4. You should now install FlexPRET's hardware configuration to the software development kit (SDK). This provides the SDK necessary information such as the amount of data memory available. ``` make install ``` From 8fe4654d269669e0f31f74afcf17825e01c65cde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20M=C3=A6hlum?= Date: Thu, 23 May 2024 12:01:00 +0200 Subject: [PATCH 9/9] Fix bug in sentence --- docs/embedded/flexpret.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/flexpret.mdx b/docs/embedded/flexpret.mdx index 0287b12ee..0d9504b04 100644 --- a/docs/embedded/flexpret.mdx +++ b/docs/embedded/flexpret.mdx @@ -27,7 +27,7 @@ cd $FP_PATH cmake -B build && cd build && make ``` -4. You should now install FlexPRET's hardware configuration to the software development kit (SDK). This provides the SDK necessary information such as the amount of data memory available. +4. You should now install FlexPRET's hardware configuration to the software development kit (SDK). This provides the SDK with necessary information such as the amount of data memory available. ``` make install ```