{"id":13427693,"url":"https://github.com/bluespec/Toooba","last_synced_at":"2025-03-16T00:32:29.669Z","repository":{"id":36183291,"uuid":"177825352","full_name":"bluespec/Toooba","owner":"bluespec","description":"RISC-V Core; superscalar, out-of-order, multi-core capable; based on RISCY-OOO from MIT","archived":false,"fork":false,"pushed_at":"2024-07-25T14:24:28.000Z","size":29815,"stargazers_count":156,"open_issues_count":3,"forks_count":35,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-08-01T01:27:45.288Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluespec.png","metadata":{"files":{"readme":"README.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-26T16:14:02.000Z","updated_at":"2024-07-25T14:24:39.000Z","dependencies_parsed_at":"2024-07-25T16:43:14.899Z","dependency_job_id":null,"html_url":"https://github.com/bluespec/Toooba","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FToooba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FToooba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FToooba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluespec%2FToooba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluespec","download_url":"https://codeload.github.com/bluespec/Toooba/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221631813,"owners_count":16855012,"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:38.314Z","updated_at":"2025-03-16T00:32:29.663Z","avatar_url":"https://github.com/bluespec.png","language":"Verilog","funding_links":[],"categories":["Verilog","Open Source Core Implementations"],"sub_categories":[],"readme":"# 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\n  Piccolo is intended for low-end applications (Embedded Systems, IoT, microcontrollers, etc.).\n\n- [Flute](https://github.com/bluespec/Flute): 5-stage, in-order pipeline\n\n  Flute is intended for low-end to medium applications that require\n  64-bit operation, an MMU (Virtual Memory) and more performance than\n  Piccolo-class processors.\n\n- [Toooba](https://github.com/bluespec/Toooba): superscalar, out-of-order\n  pipeline, slight variation on MIT's RISCY-OOO\n\n  Toooba is intended as a high-end application processor.\n\nThe three repo structures are nearly identical, and the ways to build\nand run are identical.\n\n----------------------------------------------------------------\n### Note re. distribution of MIT RISCY-OOO sources.\n\nThe directory `src_Core/RISCY_OOO` contains sources copied from MIT's\n`riscy-OOO` repository.  See `LICENSE_RISCY-OOO` for MIT's license.\n\n[Note: MIT's repository is on an MIT git server, which can only be\n accessed with credentials; hence the local copy in of these files.]\n\nBluespec's modifications to files in src_Core/RISCY_OOO are relatively\nsmall and mostly additive:\n\n- To add the RISC-V 'C' extension (compressed instructions)\n- To add support for Bluespec's Tandem Verification\n- To add support for Bluespec's Debug Module.\n- To fix about bugs leading to about half a dozen failures of standard RISC-V ISA tests\n\n----------------------------------------------------------------\n### About the source codes (in BSV and Verilog)\n\nThe BSV source code in this repository, from which the synthesizable\nVerilog RTL in this repository is generated, is highly parameterized\nto allow generating many possible configurations, some of which are\nadequate to boot a Linux kernel.\n\nThe pre-generated synthesizable Verilog RTL source files in this\nrepository are for one specific configuration:\n\n1. RV64ACDFIMSU    (a.k.a. RV64GC)\n    - RV64I: base RV64 integer instructions\n    - 'A' extension: atomic memory ops\n    - 'C' extension: compressed instructions\n    - 'D' extension: double-precision floating point instructions\n    - 'F' extension: single-precision floating point instructions\n    - 'M' extension: integer multiply/divide instructions\n    - Privilege levels M (machine), S (Supervisor) and U (user)\n    - Supports external, timer, software and non-maskable interrupts\n    - Passes all riscv-isa tests for RV64ACDFIMSU\n    - Boots the Linux kernel\n\nIf you want to generate other Verilog variants, you'll need a Bluespec\n`bsc` compiler [Note: Bluespec, Inc. provides free licenses to\nacademia and for non-profit research].\n\n### Testbench included\n\nThis repository contains a simple testbench (a small SoC) with which\none can run RISC-V binaries in simulation by loading standard mem hex\nfiles and executing in Bluespec's Bluesim, Verilator simulation or\niVerilog simulation.  The testbench contains an AXI4 interconnect\nfabric that connects the CPU to models of a boot ROM, a memory, a\ntimer and a UART for console I/O.\n\n[Note: **iverilog functionality is currently limited** because we are\nstill working out robust mechanisms to import C code, which is used in\nparts of the testbench.]\n\nThis repository contains one sample build directory, to build\nan RV64ACDFIMSU simulator, using Verilator Verilog simulation.\n\nThe generated Verilog is synthesizable. Bluespec tests all this code\non Xilinx FPGAs.\n\n#### Plans\n\n- Ongoing continuous micro-architectural improvements for performance and hardware area.\n\n----------------------------------------------------------------\n## Source codes\n\nThis repository contains two levels of source code: Verilog and BSV.\n\n**Verilog RTL** can be found in directories with names suffixed in\n'_verilator' or '_iverilog' in the 'builds' directory:\n\n        builds/..._\u003cverilator or iverilog\u003e/Verilog_RTL/\n\n[There is no difference between Verilog in a Verilator directory\nvs. the corresponding iverilog directory. ]\n\nThe Verilog RTL is _synthesizable_ (and hence acceptable to\nVerilator).  It can be simulated in any Verilog simulator (we provide\nMakefiles to build simulation executables for Verilator and for Icarus\nVerilog (iverilog)).\n\nThe RTL represents RISC-V CPU RTL, plus a rudimentary surrounding SoC\nenabling immediate simulation here, and which is rich enough to enable\nbooting a Linux kernel.  Users are free to use the CPU RTL in their\nown Verilog system designs.  The top-level module for the CPU RTL is\n`Verilog_RTL/mkProc.v`.  The top-level module for the surrounding\nSoC is `Verilog_RTL/mkTop_HW_Side.v`.  The SoC has an AXI4\nfabric, a timer, a software-interrupt device, and a UART.  Additional\nlibrary RTL can be found in the directory `src_bsc_lib_RTL`.\n\n**Bluespec BSV** source code (which was used to generate the Verilog RTL) can be found in:\n\n- `src_Core/`, for the CPU core, with sub-directories:\n   - `Core/`: the top-level of the CPU Core (specifically, the files CoreW_IFC.bsv and CoreW.bsv)\n   - 'CPU/': more CPU core sources\n   - 'RISCY_OOO': the bulk of the code, taken from MIT's riscy-ooo design, with local modifications.\n   - `ISA/`:  generic types/constants/functions for the RISC-V ISA (not CPU-implementation-specific)\n   - 'PLIC/': Platform-Level Interrupt Controller (standard RISC-V spec)\n   - `BSV_Additional_Libs/`: generic utilities (not CPU-specific)\n   - `Debug_Module/`: RISC-V Debug Module to debug the CPU from GDB or other debuggers\n\n- `src_Testbench/`, for the surrounding testbench, with sub-directories:\n\n   - `Top/`: The system top-level (`Top_HW_Side.bsv`), a memory model\n       that loads from a memory hex file, and some imported C\n       functions for polled reads from the console tty (not currently\n       available for Icarus Verilog).\n\n   - `SoC/`: An interconnect, a boot ROM, a memory controller, a timer\n       and software-interrupt device, and a UART for console tty I/O.\n\n   - `Fabrics/`: Generic AXI4 code for the SoC fabric.\n\nThe BSV source code has a rich set of parameters. The provided RTL\nsource has been generated from the BSV source automatically using\nBluespec's `bsc` compiler, with certain particular sets of choices for\nthe various parameters.  The generated RTL is not parameterized.\n\nTo generate Verilog variants with other parameter choices, the user\nwill need Bluespec's `bsc` compiler.  See the next section for\nexamples of how the build is configured for different ISA features.\n\n`BSV_Additional_Libs` contains a submodule, `BlueStuff`, which must be checked out using:\n```sh\n$ git submodule update --init --recursive\n```\nThis command may need to be repeated when this parent repository\nis updated to point to newer versions of the `BlueStuff` repository.\n\nIn fact the CPU also supports a \"Tandem Verifier\" that produces an\ninstruction-by-instruction trace that can be checked for correctness\nagainst a RISC-V Golden Reference Model.  Please contact Bluespec,\nInc. for more information.\n\n----------------------------------------------------------------\n### Building and running from the Verilog sources, out of the box\n\nIn the Verilog-build directory:\n\n            builds/RV64ACDFIMSU_Toooba_verilator/\n\n  - `$ make simulator` will create a Verilog simulation executable using Verilator\n\n  - `$ make test` will run the executable on the standard RISC-V ISA\n        test `rv32ui-p-add` or `rv64ui-p-add`, which is one of the\n        tests in the `Tests/isa/` directory.  Examining the `test:`\n        target in `Makefile`, we see that it first runs the program\n        `Tests/elf_to_hex/elf_to_hex` on the `rv32ui-p-add` or\n        `rv64ui-p-add` ELF file to create a `Mem.hex` file, and then\n        runs the simulation executable which loads this `Mem.hex` file\n        into its memory.\n\n  - `$ make TEST=\u003cisa_test_name\u003e test` will run the executable on the\n        standard RISC-V ISA test whose name is supplied.\n        The full set of standard isa tests are in the `Tests/isa/` directory.\n\n  - `$ make isa_tests` will run the executable on\n      all the standard RISC-V ISA tests relevant for RV64ACDFIMSU (regression testing).\n      This uses the Python script `Tests/Run_regression.py`.\n      Please see the documentation at the top of that program for details.\n\n#### Tool dependencies:\n\nWe test our builds with the following versions\nVerilator.  Later versions are probably ok; we have observed some\nproblems with earlier versions.\n\n        $ verilator --version\n        Verilator 3.922 2018-03-17 rev verilator_3_920-32-gdf3d1a4\n\n----------------------------------------------------------------\n### What you can build and run if you have Bluespec's `bsc` compiler\n\n[Note: Bluespec, Inc. provides free licenses to academia and for non-profit research].\n\nNote: even without Bluespec's `bsc` compiler, you can use the Verilog\nsources in any of the `builds/\u003cARCH\u003e_\u003cCPU\u003e_verilator/Verilog_RTL`\ndirectories-- build and run Verilog simulations, incorporate the\nVerilog CPU into your own SoC, etc.  This section describes additional\nthings you can do with a `bsc` compiler.\n\n#### Building a Bluesim simulator\n\nIn any of the following directories:\n\n        builds/\u003cARCH\u003e_\u003cCPU\u003e_bluesim\n\n  - `$ make compile simulator`\n\nwill compile and link a Bluesim executable.  Then, you can `make test`\nor `make isa_tests` as described above to run an individual ISA test\nor run regressions on the full suite of relevant ISA tests.\n\n#### Re-generating Verilog RTL\n\nYou can regenerate the Verilog RTL in any of the\n`build/\u003cARCH\u003e_\u003cCPU\u003e_verilator/` or `build/\u003cARCH\u003e_\u003cCPU\u003e_iverilog/`\ndirectories.  Example:\n\n        $ cd  builds/RV32ACIMU_\u003cCPU\u003e_verilator\n        $ make compile\n\n#### Creating a new architecture configuration\n\n[This documentation needs to be fleshed out.] The `builds/Resources`\ndirectory contains some \"include\" files for Makefiles, and illustrate\nthe compile-time flags that determine the micro-architectural\nconfiguration.\n\nIn addition, MIT's riscy-ooo code provides further configuration\ncontrols, which can be found in:\n\n        Toooba/src_Core/RISCY_OOO/procs/RV64G_OOO/ProcConfig.bsv\n\n----------------------------------------------------------------\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluespec%2FToooba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluespec%2FToooba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluespec%2FToooba/lists"}