{"id":13427688,"url":"https://github.com/bluespec/Flute","last_synced_at":"2025-03-16T00:32:19.110Z","repository":{"id":40763033,"uuid":"135380993","full_name":"bluespec/Flute","owner":"bluespec","description":"RISC-V CPU, simple 5-stage in-order pipeline, for low-end applications needing MMUs and some performance","archived":false,"fork":false,"pushed_at":"2023-10-19T02:54:21.000Z","size":20521,"stargazers_count":355,"open_issues_count":10,"forks_count":56,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-28T07:45:00.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Bluespec","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluespec.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-05-30T03:07:36.000Z","updated_at":"2024-10-28T04:54:20.000Z","dependencies_parsed_at":"2023-10-20T18:19:17.588Z","dependency_job_id":null,"html_url":"https://github.com/bluespec/Flute","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/bluespec%2FFlute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FFlute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FFlute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FFlute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluespec","download_url":"https://codeload.github.com/bluespec/Flute/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243809865,"owners_count":20351403,"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-07-31T01:00:37.955Z","updated_at":"2025-03-16T00:32:16.793Z","avatar_url":"https://github.com/bluespec.png","language":"Bluespec","funding_links":[],"categories":["Bluespec","Open Source Core Implementations"],"sub_categories":[],"readme":"= Flute, a free and open-source RISC-V CPU\nRishiyur S. Nikhil, Bluespec, Inc. (c) 2021\n:revnumber: v1.0\n:revdate: 2021-05-19\n:sectnums:\n:toc:\n:toclevels: 3\n:toc-title: Contents\n:description: Highly-parameterized RISC-V CPU, from small RV32 embedded to Linux-capable RV64\n:keywords: RISC-V, Bluespec, BSV, Flute\n\n'''\n\n// ================================================================\n// SECTION\n\n== CPU microarchitecture and options\n\nFlute is one of a family of free and open-source RISC-V CPUs from\nBluespec, Inc.  (https://bluespec.com[]) For a description of the\nfamily, see Section \u003c\u003cCPU_Family\u003e\u003e.\n\nFlute's microarchitecture is a 5-stage, in-order pipeline.  The source\ncode is highly parameterized to produce hundreds of variants, ranging\nfrom a small, bare-metal RV32 CPU to a medium-size, Linux-capable RV64\nCPUs with multiple privilege levels.\n\nThere is a sketch of the module hierarchy in `Doc/Microarchitecture/Microarchitecture.pdf`.\n\n=== RISC-V ISA Spec options\n\n* RV32I or RV64I\n* Optional ISA A (Atomic instructions)\n* Optional ISA C (Compressed instructions)\n* Optional ISA M (Integer multiply and divide)\n* Optional ISA F (Single-precision IEEE floating point) +\n  Optional ISA D (Double-precision IEEE floating point)\n    ** For F and D, optional hardare divider (or trap on divide instructions)\n* Optional Privileged Architecture MU (Machine and User levels) or MSU\n  (Machine, Supervisor and User Levels)\n    ** For RV32, Privilege S implements the Sv32 Virtual Memory scheme\n    ** For RV64, Privilege S implements the Sv39 Virtual Memory scheme\n\n=== CPU microarchitecture options\n\n* Barrel-shifter (faster, more expensive hardware) or serial shifter\n  (cheaper, slower hardware) for Shift instructions\n\n* Multipliers inferred by RTL Syntheis tool (faster, more expensive\n    hardware), or serial multiplier (cheaper, slower hardware)\n    multiplication for ISA M option\n\n=== \"`Near-Memory options`\" (Caches and MMUs)\n\nFlute has separate I- and D-caches.\n\n* WT_L1: L1 only for I-Cache and D-Cache; write-through policy\n* WB_L1: L1 only for I-Cache and D-Cache; write-back policy\n* WB_L1_L2: L1 for I-Cache and D-Cache, shared coherent L2 cache; write-back policy\n\nFor all of them, an MMU is included if Privilege S is selected.\n\n=== Development options\n\n* Optional standard RISC-V Debug Module that can connect to GDB, to\n  control and observe the CPU.\n\n* Optional Tandem Verification trace generator that outputs an\n  instruction-by-instruction trace that can be compared with a golden\n  model RISC-V CPU (e.g., RISC-V Formal Specication, simulator like\n  Spike or Bluespec Cissr)\n\n// ================================================================\n// SECTION\n\n== The provided system to run out-of-the-box, including CLINT and PLIC\n\nThis repository contains a simple system (a small SoC) that\ninstantiates the CPU. The system can be compiled into a Bluesim or\nVerilog simulation, and can be synthesized for FPGA.\n\nThe immediate layer (the \"`core`\") that surrounds the CPU includes a\nCLINT (we call it \"`Near Mem IO`\") which contains the standard RISC-V\nMTIME (Real-time timer) and MTIMECMP (Timer Compare) memory-mapped\nregisters and an MSIP \"`Software Interrupt`\" memory-mapped register.\n\nThe immediate layer (the \"`core`\") that surrounds the CPU also\nincludes a standard memory-mapped PLIC (Platform-Level Interrupt\nController).\n\nThe SoC surrounding the core is based on an AMBA AXI4 interconnect, to\nwhich is connected a boot ROM model, a DRAM memory model and a UART\nmodel for serial communication.  The interconnect is parameterized for\nthe number of M (Manager) and S (Subordinate) ports, so one can attach\nmore memories, peripherals, or accelerators (needs recompilation).\n\nThe system is run in simulation by loading the DRAM memory model with\na data from a standard Verilog \"`Mem Hex`\" file (hexadecimal memory\ncontents), which can be produced from a RISC-V ELF binary file.\n\n// ================================================================\n// SECTION\n\n== Directory structure\n\nAll the hardware designs in this repository are written in BSV, an\nHLHDL (High-Level Hardware Description Language).  BSV sources files\nhave extension `.bsv`.  These are compiled to standard synthesizable\nVerilog RTL using the free and open source _bsc_ compiler\n(https://github.com/B-Lang-org/bsc[]).\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== CPU and Core, in `src_Core/`\n\nThe `src_Core/` directory contains the sources for the CPU and immediate surrounding core(s).\n\nThe CPU itself is in sub-directories `CPU`, `ISA`, and `RegFiles`.\n\nThe CLINT (unit with memory-mapped MTIME, MTIMECMP and MSIP registers) are in `Near_Mem_IO`.\n\nThe PLIC (Platform-level Interrupt Controller) is in `PLIC`.\n\nThe alternative \"`near-memory`\" subsystems (caches, MMUs) are in\n`Near_Mem_VM_WT_L1`,\n`Near_Mem_VM_WB_L1`, and\n`Near_Mem_VM_WB_L1_L2`.\n\nThe optional RISC-V Debug Module is in `Debug_Module`.\n\nTwo alterative \"`cores`\" are in `Core` (used with WT_L1 and WB_L1) and\n`Core_v2` (used with WB_L1_L2). These directories also contain the\noptional Tandem Verification generators.  These cores instantiate the\nCPU, chosen near-memory subsystem, CLINT, PLIC, optional Debug Module\nand optional Tandem Verification generator.\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== SoC and simulation top-level, in `src_Testbench/`\n\nThe SoC is in `src_Testbench/SoC`.  This includes a boot ROM model, an\nAXI4 interconnect fabric, a memory controller for DRAM, and a UART\nmodel for serial communications.\n\nThe file `SoC/SoC_Map.bsv` specifies the system's address map\n(addresses for memory, boot ROM, CLINT, PLIC, UART, etc.)\n\nThe subdirectory `src_Testbench/Fabrics/` contains the code for AXI4 interfaces,\ntransactors and fabrics.\n\nEverything in the SoC and below is synthesizable, and can be\nsynthesized for FPGA.\n\nThe `src_Testbench/Top/` subdirectory is the only part that is meant\nfor simulaton only (not synthesizable). It contains a thin layer\naround the SoC to provide a simulation clock and reset, a memory model\nfor the DRAM, and connections from the UART to the terminal.\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== ISA tests (in `Tests/`)\n\nThe directory `Tests/isa` is a copy of the \"`official`\" RISC-V ISA\ntests (original is at https://github.com/riscv/riscv-tests[]).  It\nalso contains compiled versions of all the tests (each has a RISC-V\nELF file and an \"`objdump`\" file that shows its disassemby).\n\nThe directory `Tests/elf_to_hex` contains a small C program to convert\nan ELF file to a \"`Mem Hex`\" memory hexadecimal contents file.\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== Provided example builds (including generated Verilogs)\n\nAs mentioned earlier, one can generate hundreds of variants of Flute\ndepending on the choice of configuration parameters.  This repository\ncontains \"`build`\" directories for a few particular configurations,\nboth to provide an out-of-the-box experience and to serve as example\ntemplates which you can modify to create your own variant:\n\nThe following are for RV32I + C (Compressed instructions), bare-metal\n(M and U privilege levels). One builds for the Bluesim simulator, the\nother for Icarus Verilog (iverilog):\n\n[source]\n----\nbuilds/Flute_RV32CI_MU_WT_L1_bluesim_tohost/\nbuilds/Flute_RV32CI_MU_WT_L1_iverilog_tohost/\n----\n\nThe following are for RV64GC (RV64IMAFDC), privilege levels M, S and\nU, virtual memory Sv39. One builds for the Bluesim simulator, the\nother for a Verilator simulator.  These have booted FreeRTOS, Linux\nand FreeBSD, in simulation and on FPGA.\n\n[source]\n----\nbuilds/Flute_RV64GC_MSU_WB_L1_L2_bluesim_tohost/\nbuilds/Flute_RV64GC_MSU_WB_L1_L2_verilator_tohost/\n----\n\n// ================================================================\n// SECTION\n\n== Building and running simulations (Bluesim or Verilog simulation)\n\nFor some of the actions below, you need to have installed the free and\nopen-source _bsc_ compiler, which you can find at\nhttps://github.com/B-Lang-org/bsc[].\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== Building for Bluesim simulation (_bsc_ needed)\n\nIn one of the Bluesim build directories,\ne.g,. `builds/Flute_RV32CI_MU_WT_L1_bluesim_tohost/` the command\n\n[source]\n----\n$ make compile simulator\n----\n\nwill compile and build a Bluesim simulator.\n\nSee section below for how to run the simulation.\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== Building for Verilator simulation (_bsc_ not needed)\n\nEach of the Verilator build directories,\ne.g,. `builds/Flute_RV64GC_MSU_WB_L1_L2_verilator_tohost/`\ncontains a `Verilog_RTL` directory where we have already generated the\nVerilog RTL sources for you from the BSV sources.\n\n_You do not need the free and open-source bsc compiler to just build\nthe Verilog simulator from the Verilog sources._\n\nThe following command will build a Verilator simulation executable.\n\n[source]\n----\n$ make simulator\n----\n\nSee section below for how to run the simulation.\n\n// ----------------\n// SUBSUBSECTION\n\n==== Regenerating the Verilog RTL (_bsc_ needed)\n\n[source]\n----\n$ make compile\n----\n\nwill regenerate the Verilog files in the `Verilog_RTL` directory.\n\n// ----------------------------------------------------------------\n// SUBSECTION\n\n=== Running a simulation (Bluesim or Verilog simulation)\n\nOnce you have built a Bluesim, IVerilog or Verilator simulator as\ndescribed in the previous sections, you can run it as follows (_bsc_\nis not needed for this).\n\nTo run a single ISA test:\n\n[source]\n----\n$ make test\n----\n\nThis runs the default ISA test (`Tests/isa/rv32ui-p-add` for RV32,\n`Tests/isa/rv64ui-p-add` for RV64), and prints an instruction trace\nduring execution.  (First, it uses an `elf_to_hex` program, provided\nin the `Tests/` directory, to convert the relevant ELF file into a\n\"`Mem Hex`\" memory-contents file, which is loaded into the memory\nmodel at the start of simulation).\n\nYou can choose a different ISA test from the `Tests/isa/` directory by\nspecifying it on the command line, like this:\n\n[source]\n----\n$ make test TEST=rv64ui-v-ld\n----\n\nNote: if you specify a test that contains an instruction outside the\nset of instructions for your build (e.g., an ELF that uses C\n(compressed) instructions for a build that does not support C) this\nwill result in an illegal instruction trap, as expected.\n\nYou can run all relevant ISA tests (i.e., all those tests that are\nrelevant for the build's chosen ISA options) with:\n\n[source]\n----\n$ make isa_tests\n----\n\nThis will spawn multiple parallel processes to run run through all the\nrelevant tests.  The `Logs` subdirectory contains a log for each ISA\ntest that was run.\n\n`make isa_tests` actually invokes the Python program\n`Tests/Run_regression.py`, which you can run directly if you wish.\nRunning it with `--help` will describe its command-line arguments,\nincluding the ISA architecture string, using which it selects the\n\"`relevant`\" ISA tests.\n\nThe following will \"`clean`\" your build directory.  The first command\njust deletes intermediate files and directories created during\ncreation of the simulator.  The latter will also deleted the simulator\nitself and restore the directory to its pristine state.\n\n[source]\n----\n$ make clean\n$ make full_clean\n----\n\n// ----------------\n\n==== Running your own ELF file on Flute\n\nIf you look at the actions taken by the Makefile in the above\nexamples, you can see how you can substitute your own ELF file as a\nprogram to run.\n\n// ================================================================\n// SECTION\n\n== Creating a new architecture configuration\n\nIn the `builds/` directory, you can create a new sub-directory to\nbuild a new configuration of interest.  For example:\n\n[source]\n----\n$ cd  builds\n$ Resources/mkBuild_Dir.py  ..  RV32IMAC  MU  WT_L1  bluesim  tohost\n----\n\nwill create a new directory: `Flute_RV32ACIM_MU_WT_L1_bluesim_tohost/`\npopulated with a `Makefile` to compile and link a bluesim simulation\nfor an RV32I CPU with M,A, and C ISA options, M and U privilege\nlevels, L1 I-Cache and D-Cache with write-through policy (no L2\ncache), for building a Bluesim simulator, and which observes the\n`tohost` memory location for test completion (which is the standard\nmethod in ISA tests to signal completion).\n\nYou can build and run that simulator as usual:\n\n[source]\n----\n$ make compile simulator test isa_tests\n----\n\n// ================================================================\n// SECTION\n\n'''\n[#CPU_Family]\n== Other open-source RISC-V CPUs from Bluespec, Inc.\n\nThis is one of a family of free, open-source RISC-V CPUs created by Bluespec, Inc.\n\n* Piccolo (https://github.com/bluespec/Piccolo[]): 3-stage, in-order pipeline +\n  For low-end applications (Embedded Systems, IoT, microcontrollers, etc.).\n\n* Flute (https://github.com/bluespec/Flute[]): 5-stage, in-order pipeline. +\n  For low-end to medium applications that require 32-bit or\n  64-bit operation, an MMU (Virtual Memory) and more performance.\n\n* Toooba (https://github.com/bluespec/Toooba[]): superscalar, deep, out-of-order RV64\n  pipeline, using MIT's RISCY-OOO core.\n\nAll of them are written in entirely in BSV, an HLHDL (High-Level\nHardware Description Language).\n\nThe three repo structures are nearly identical, and the ways to build\nand run are nearly identical.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluespec%2FFlute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluespec%2FFlute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluespec%2FFlute/lists"}