{"id":13648863,"url":"https://github.com/pretis/flexpret","last_synced_at":"2025-04-22T11:33:27.606Z","repository":{"id":15993141,"uuid":"18736338","full_name":"pretis/flexpret","owner":"pretis","description":"A time-predictable processor for mixed-criticality systems","archived":false,"fork":false,"pushed_at":"2024-11-07T23:41:39.000Z","size":8012,"stargazers_count":58,"open_issues_count":15,"forks_count":29,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-19T03:13:24.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pretis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-04-13T18:24:07.000Z","updated_at":"2025-03-12T05:21:47.000Z","dependencies_parsed_at":"2023-10-27T19:30:10.932Z","dependency_job_id":"da74deab-b36e-467b-8373-8f1d3710212a","html_url":"https://github.com/pretis/flexpret","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretis%2Fflexpret","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretis%2Fflexpret/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretis%2Fflexpret/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pretis%2Fflexpret/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pretis","download_url":"https://codeload.github.com/pretis/flexpret/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250232583,"owners_count":21396665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:04:36.784Z","updated_at":"2025-04-22T11:33:24.968Z","avatar_url":"https://github.com/pretis.png","language":"Scala","funding_links":[],"categories":["Scala","Open Source Implementations"],"sub_categories":["Cores"],"readme":"FlexPRET\n================================================================================\n__FlexPRET__ is a 5-stage, fine-grained multithreaded [RISC-V](http://riscv.org) processor designed specifically for _mixed-criticality (real-time embedded) systems_ and written in [Chisel](http://www.chisel-lang.org). A hardware thread scheduler decides which hardware thread to start executing each cycle, regulated by configuration and status registers. Each hardware thread is either classified as a _hard real-time thread (HRTT)_ or _soft real-time thread (SRTT)_: HRTTs are only scheduled at a constant rate for _hardware-based isolation and predictability_ (enabling independent formal verification), and SRTTs share remaining cycles (including when a HRTT doesn't need prescribed cycles) for _efficient processor utilization_. For comparison purposes, both single-threaded and round-robin multithreaded 5-stage RISC-V processors can also be generated. FlexPRET was developed at UC Berkeley as part of the [PRET](http://chess.eecs.berkeley.edu/pret/) project.\n\nNote: the porting is not complete for the privileged RISC-V 2.0 ISA, so some tests are disabled.\n\nFor more information on the processor architecture:  \n* Michael Zimmer, \"[Predictable Processors for Mixed-Criticality Systems and Precision-Timed I/O](http://www2.eecs.berkeley.edu/Pubs/TechRpts/2015/EECS-2015-181.pdf),\" Ph.D. Dissertation, EECS Department, University of California, Berkeley, UCB/EECS-2015-181, 2015.\n* Michael Zimmer, David Broman, Chris Shaver, Edward A. Lee. \"[FlexPRET: A Processor Platform for Mixed-Criticality Systems](http://chess.eecs.berkeley.edu/pubs/1048.html). Proceedings of the 20th IEEE Real-Time and Embedded Technology and Application Symposium (RTAS), April, 2014.\n\n# Tools and installation\n\n## RISC-V Compiler\nWe use the `riscv-none-elf-gcc` compiler provided by xPack project. To install this toolchain to `/opt/xpack-riscv-none-elf-gcc-14.2.0-2` perform the following steps.\n\n```\n  wget -q --show-progress https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v14.2.0-2/xpack-riscv-none-elf-gcc-14.2.0-2-linux-x64.tar.gz -O gcc.tar.gz\n  tar xvf gcc.tar.gz --directory=/opt\n```\n\nThen add `export RISCV_TOOL_PATH_PREFIX=/opt/xpack-riscv-none-elf-gcc-14.2.0-2` to your `~/.bashrc`\n\nThere are also versions for macOS and Windows. Refer to the [documentation](https://xpack-dev-tools.github.io/riscv-none-elf-gcc-xpack/) for more information.\n\n## Verilator\nWe use the `verilator` toolchain for running emulations of the core. Install it and check that the version is greater than 4.038.\n\n```\nsudo apt install verilator\nverilator --version\n```\n\n## Vivado\n\nIf you intend to run FlexPRET on a Xilinx FPGA, you will need to install Vivado. Refer to Xilinx installation guides.\n\n# Quickstart\n\nAfter cloning the repository, update submodules with:\n\n```\ngit submodule update --init --recursive\n```\n\n## FlexPRET unit tests\nTo run all unit tests for FlexPRET:\n\n```\nsbt test\n```\n\nTo run a specific unit test (e.g. SimpleCoreTest):\n\n```\nsbt 'testOnly flexpret.core.test.SimpleCoreTest'\n```\n\nUnit tests are found under `src/test/scala/core/`.\n\n## Software unit tests\n\nTo run software unit tests, first build the emulator. From the top-level directory,\n\n```\nsource env.bash\ncmake -B build \u0026\u0026 cd build\nmake all install\n```\n\nThe `env.bash` file contains environment variables that must be set to build anything. Feel free to add sourcing it to your `~/.bashrc`. The install step will install a number of artifacts that describe FlexPRET's hardware configuration to the software development kit (SDK). Next, build the SDK and run the tests like so:\n\n```\ncd sdk\ncmake -B build \u0026\u0026 cd build\nmake \u0026\u0026 ctest\n```\n\nNote that the library is built from source for every test. This takes longer time but means each test can have its own permutation of the library, e.g., with and without debug flags. \n\nSome of the tests can take quite a long time; as much as 10 seconds.\n\n## Running a single software unit test\n\nWhen cmake builds the tests, it also leaves one bash script per test in the `bin/` directory. These can be run directly:\n\n```\n./bin/add\n```\n\nUnder the hood, the script runs `fp-emu`, which the FlexPRET's emulator, with a `\u003cprogram\u003e.mem` file, which is the compiled program.\n\n# Running software\n\nSoftware can both be run on an emulator and a Field-Programmable Gate Array (FPGA). Running on an FPGA requires quite a lot of setup - we recommend running on an emulator to start. Either way, you will need to [install the RISC-V compiler](#risc-v-compiler) (in particular, `riscv32-unknown-elf-*`).\n\nNote that software compiled for the emulator and FPGA are not compatible. Software is by default compiled for the emulator; to compile software for FPGA, see [Running on FPGA](#running-on-fpga).\n\n## Configuration\n\n### Hardware\n\nAll of FlexPRET's hardware configuration options are described in `./cmake/configs/default.cmake`. Other configurations are possible too; feel free to create a new file for your needs in `./cmake/configs`. When building FlexPRET, the `default.cmake` configuration file will be used by default. To specify others, pass `-DFP_CONFIG=\u003cmy_config\u003e`, e.g., `-DFP_CONFIG=highmem`. See `./scripts/run_multiple_tests.sh` for more examples. Note that not all configuration combinations are valid.\n\nBuilding FlexPRET will generate a number of artifacts that are passed onto the SDK. This is necessary to e.g., set the stack pointer upon initialization. Another use case is this:\n\n```C\n#include \u003cflexpret/hwconfig.h\u003e\n#include \u003cflexpret/thread.h\u003e\n\nfp_thread_t tid[FP_THREADS-1];\nfor (int i = 0; i \u003c FP_THREADS-1; i++) {\n    fp_thread_create(HRTT, \u0026tid[i], fnc, NULL);\n}\n```\n\nWhich will start all threads for any number of threads available on the built FlexPRET. See the tests for more example use cases.\n\n### Software\n\nSimilar to hardware configuration, software can be configured too. It can be found in `./sdk/cmake/configs`. At the time of writing, there are less options, but a similar structure is used there.\n\n## Running on emulator\n\nWe use `verilator` for emulation. Note that a modern version of Verilator is required (e.g. Verilator 4.038+).\n\nTo build the emulator, run `cmake -B build \u0026\u0026 cd build \u0026\u0026 make all install` in the root directory. This will build the default configuration and install it to the SDK. After building, try to run `fp-emu --hwconfig`. This should print out the hardware configuration of the emulator. To run a simple test,\n\n```\n# Step into SDK and build the Fibonnaci program\ncd sdk \u0026\u0026 cmake -B build \u0026\u0026 cd build \u0026\u0026 make clean fib\n\n# Build the generated script, which runs fp-emu under the hood\n./bin/fib\n```\n\nWhich should print out:\n\n```\n[0]: fib(16) is 987\n[0]: fib(20) is 6765\n[0]: \u003c...\u003e/flexpret/sdk/lib/src/syscalls.c: 50: Finish\n```\n\n### Pin service\n\nTo set pins on the FlexPRET (e.g., to emulate external interrupts or communication protocols), refer to the [emulator client README.md](emulator/clients/README.md).\n\n### Regression Test\nIt is typically helpful to run all tests at once. Assuming the present working directory is `./flexpret/sdk`:\n\n```\ncmake -B build \u0026\u0026 cd build \u0026\u0026 make \u0026\u0026 ctest\n```\n\nThis will run all single-threaded test cases if the FlexPRET configuration has a single hardware thread, and both the single-threaded and multi-threaded test cases otherwise. To run all these tests for multiple FlexPRET hardware configurations, run the script from the top-level directory:\n\n```\n./scripts/run_multiple_tests.sh\n```\n\nThis will build a number of FlexPRET configurations and run the unit tests on all of them. Feel free to add additional hardware configurations or additional unit tests.\n\n## Running on FPGA\n\nRefer to the [FPGA README](./fpga/README.md) for more information on how to get FlexPRET running on an FPGA. In order to compile software that runs on FlexPRET on FPGA, you need to set the CMake variable `TARGET` to fpga. See the `CMakeLists.txt` in `flexpret/apps/wb_uart_led/` for an example.\n\nWhen this variable is set, the generated bash script (still located in `bin/`) will be a bit different. Instead of running `fp-emu` with a `.mem` file, it will serialize the `.mem` file and attempt to transfer it to the FPGA. This assumes the bootloader is running (refer to [FPGA README](./fpga/README.md)). To override the default port used to flash, set the environment variable `FP_SDK_FPGA_FLASH_DEVICE` to a path.\n\nThe specific commands to build `wb_uart_led` are:\n\n```\n# Go to apps and build wb_uart_led\ncd $FP_PATH/apps\ncmake -B build \u0026\u0026 cd build \u0026\u0026 make clean wb_uart_led\n\n# To run the script that transfers the program to FlexPRET FPGA\ncd .. \u0026\u0026 ./bin/wb_uart_led\n```\n\nNote that compiling this software requires that the bootloader has been built. This is so the program knows how much to offset its instruction addresses by. E.g., by inspecting `$FP_PATH/apps/build/wb_uart_led/wb_uart_led.dump`, you will notice that `_start` begins at an address different from zero. The offset is the size of the bootloader you have built (and possibly have running on your FlexPRET FPGA).\n\nSo the steps to get `wb_uart_led` running on FlexPRET FPGA are:\n```\n# Build FlexPRET with default configuration and install it to SDK\ncd $FP_PATH \u0026\u0026 cmake -B build \u0026\u0026 cd build \u0026\u0026 make all install\n\n# Build SDK (including bootloader)\ncd $FP_SDK_PATH \u0026\u0026 cmake -B build \u0026\u0026 cd build \u0026\u0026 make\n\n# Generate bitstream.bit from built FlexPRET and bootloader\n# Will most likely take some time\ncd $FP_PATH \u0026\u0026 cd build \u0026\u0026 make fp-bootloader\n\n# Build wb_uart_led app\ncd $FP_PATH/apps \u0026\u0026 cmake -B build \u0026\u0026 cd build \u0026\u0026 make\n\n# Run generated script to transfer app to bootloader\ncd $FP_PATH/apps \u0026\u0026 ./bin/wb_uart_led\n```\n\nThis assumes correct hardware setup (refer to [FPGA README](./fpga/README.md)) and that the `TARGET` is set to fpga. To override which port is used to upload programs to the bootloader, set the environment variable `FP_SDK_FPGA_FLASH_DEVICE`. E.g., `export FP_SDK_FPGA_FLASH_DEVICE=/dev/ttyUSB1`.\n\nThe baudrate cannot be overriden by the user because it is part of FlexPRET's hardware configuration.\n\n# Troubleshooting\n\n## Submodules\n\nEnsure all git submodules are initialized and up-to-date.\n\n```\ngit submodule update --init --recursive\n```\n\n# Directory Structure\n- `apps/` Some example applications which exemplify how to build your own application\n- `build/` Contains FlexPRET's build, including emulator and `.tcl` scripts for FPGA\n- `cmake/` Has configuration files, input files, and other utilities for the build system\n- `emulator/` Is the FlexPRET emulator along with some clients\n- `fpga/` Contains a number of FPGA projects, including one that uses a bootloader\n- `scripts/` Various scripts\n  - `c/` Scripts for compiling C programs\n  - `hdl/` Scripts for processing HDL programs\n  - `fpga/` Scripts for configuring programs on an FPGA\n- `sdk/` Is the software development kit for FlexPRET. Refer to its [own documentation](./sdk/README.md)\n- `src/main/scala/` RTL source files\n  - `Core/` FlexPRET processor (and baseline processors) in Chisel\n  - `uart/` Verilog code for UART\n- `src/test/scala/` Unit tests\n\n# Build system overview\n\nA diagram of the CMake build system is shown in Figure 1. There are three distinct build environments, each with its own background color. The user may select any configuration from the `cmake/configs` folder by passing `-DFP_CONFIG=\u003cconfig\u003e` to `cmake`. The first step (light blue) generates `FlexPRET.v`, which can either be used to create an emulator or FPGA bitstream. It also generates a number of artifacts about its hardware configuration which must be installed to the software development kit (SDK).\n\nThe SDK is an `interface` library, meaning it does not produce a static library. Instead, it specifies a number of source files that are passed onto tests and applications. This means compiling the library in itself is unecessary when running emulated applications. The SDK also contains a number of tests, which can be run individually like an application or using `ctest`. Finally, the SDK includes a bootloader, which is required if the user wants to run FlexPRET on FPGA with a bootloader. How to do this was described in [Running on FPGA](./README.md#running-on-fpga).\n\nFinally, applications can be added outside of this repository. In that case, the SDK is linked in as a `BINARY_DIR` and `fp-app.cmake` to get the necessary functions. \n\nFigure 1: The CMake build system\n![Build system](./doc/flexpret-cmake-architecture.drawio.png)\n\n# Chisel\nWe use Chisel version 3.5.5.\n\nTo learn more about Chisel, visit its [website](http://www.chisel-lang.org/) and particularly the [documentation section](https://chisel.eecs.berkeley.edu/documentation.html).\n\n# Contributors\n* Michael Zimmer (mzimmer@eecs.berkeley.edu)  \n* Chris Shaver (shaver@eecs.berkeley.edu)  \n* Hokeun Kim (hokeunkim@eecs.berkeley.edu)  \n* David Broman (broman@eecs.berkeley.edu) \n* Edward Wang (edwardw@eecs.berkeley.edu)\n* Shaokai Lin (shaokai@berkeley.edu)\n* Erling Jellum (erling.r.jellum@ntnu.no)\n* Martin Schoeberl (masca@dtu.dk)\n* Samuel Berkun (sberkun@berkeley.edu)\n* Magnus Mæhlum (magnmaeh@stud.ntnu.no)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpretis%2Fflexpret","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpretis%2Fflexpret","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpretis%2Fflexpret/lists"}