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 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

Development environment setup

1. We start out by setting up a development environment. Clone the lf-flexpret-template from Github:

git clone --recurse-submodules https://github.com/lf-lang/lf-flexpret-template lf-flexpret-workspace && cd lf-flexpret-workspace

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

3. Now we will build the FlexPRET emulator. Step into the FlexPRET directory and build the default configuration with cmake.

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 with necessary information 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 $FP_SDK_PATH
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/HelloWorld.lf

7. Run the compiled program on the FlexPRET emulator.

./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

[0]: ---- Start execution ----
[0]: Environment 0: ---- Intializing start tag
[0]: Environment 0: ---- Spawning 1 workers.
[1]: Hello world from FlexPRET
[1]: Goodbye

(The [<n>] means hardware thread n is printing.)

FlexPRET specific features

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).

Interrupt on expire

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:

lfc src/multi-threaded/Isolation.lf && ./bin/Isolation

Building FlexPRET with another configuration

Refer to the FlexPRET docs 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.

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

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
  <path to workspace>/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 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 (or nothing at all). Tip: To inspect what takes up space in your final executible, use nm, like so: nm HelloWorld --size-sort.
2. Increase the size of the instruction memory. This is done in FlexPRET's configs (see FlexPRET's README). 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 not built the bootloader in the FlexPRET SDK.

/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 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.