commit bc62f17032bbed872e9f3581e5ddd962055ad2e4 Author: Rishiyur S. Nikhil Date: Tue Mar 26 12:16:38 2019 -0400 Add files via upload diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b9ab5f2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +*~ +README.html +build_dir +*.bo +*.ba +*.o +obj_dir +elf_to_hex +Mem.hex +exe* +*.log +Tests/Logs +*_edited.v +*.trace_mem_load +AA_* +symbol_table.txt +vpi_wrapper_* diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..bd07fc1 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2018 Bluespec, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..86649c6 --- /dev/null +++ b/README.md @@ -0,0 +1,255 @@ +# Open-source RISC-V CPUs from Bluespec, Inc. + +This is one of a family of free, open-source RISC-V CPUs created by Bluespec, Inc. + +- [Piccolo](https://github.com/bluespec/Piccolo): 3-stage, in-order pipeline + + Piccolo is intended for low-end applications (Embedded Systems, IoT, microcontrollers, etc.). + +- [Flute](https://github.com/bluespec/Flute): 5-stage, in-order pipeline + + Flute is intended for low-end to medium applications that require + 64-bit operation, an MMU (Virtual Memory) and more performance than + Piccolo-class processors. + +- [Bassoon](https://github.com/bluespec/Bassoon): deep, out-of-order pipeline [Coming!] + +The three repo structures are nearly identical, and the ways to build +and run are identical. This README is identical--please substitute +"Piccolo" or "Flute" or "Basoon" below wherever you see . + + +### About the source codes (in BSV and Verilog) + +The BSV source code in this repository, from which the synthesizable +Verilog RTL in this repository is generated, is highly parameterized +to allow generating many possible configurations, some of which are +adequate to boot a Linux kernel. + +The pre-generated synthesizable Verilog RTL source files in this +repository are for a few specific configurations: + +1. RV32ACIMU: **(DARPA SSITH users: this is the "P1" processor)** + - RV32I: base RV32 integer instructions + - 'A' extension: atomic memory ops + - 'C' extension: compressed instructions + - 'M' extension: integer multiply/divide instructions + - Privilege levels M (machine) and U (user) + - Supports external, timer, software and non-maskable interrupts + - Passes all riscv-isa tests for RV32ACIMU + - Boots FreeRTOS + +2. RV64ACDFIMSU + - RV64I: base RV64 integer instructions + - 'A' extension: atomic memory ops + - 'C' extension: compressed instructions + - 'D' extension: double-precision floating point instructions + - 'F' extension: single-precision floating point instructions + - 'M' extension: integer multiply/divide instructions + - Privilege levels M (machine), S (Supervisor) and U (user) + - Supports external, timer, software and non-maskable interrupts + - Passes all riscv-isa tests for RV64ACDFIMSU + - Boots the Linux kernel + +If you want to generate other Verilog variants, you'll need a Bluespec +`bsc` compiler [Note: Bluespec, Inc. provides free licenses to +academia and for non-profit research]. + +The BSV source code supports: + +- RV32I or RV64I +- Optional 'A', 'C', 'D', 'F' and 'M' extensions +- Privilege level options M, MU and MSU +- For privilege S, virtual memory schemes Sv32 (RV32) and Sv39 (RV64) + +- Hardware implementation option: serial shifter (smaller hardware, slower) or barrel shifter (more HW, faster) for shift instructions +- Hardware implementation option: serial integer multiplier (smaller hardware, slower) or synthesized (more HW, faster) +- AXI4-Lite Fabric interfaces, with optional 32-bit or 64-bit datapaths (independent of RV32/RV64 choice) +- and several other localized options + +### Testbench included + +This repository contains a simple testbench (a small SoC) with which +one can run RISC-V binaries in simulation by loading standard mem hex +files and executing in Bluespec's Bluesim, Verilator simulation or +iVerilog simulation. The testbench contains an AXI4-Lite interconnect +fabric that connects the CPU to models of a boot ROM, a memory, a +timer and a UART for console I/O. + +[Note: **iverilog functionality is currently limited** because we are +still working out robust mechanisms to import C code, which is used in +parts of the testbench.] + +This repository contains several sample build directories, to build +RV32ACIMU or RV64ACDFIMSU simulators, using Bluespec Bluesim +simulation, Verilator Verilog simulation, or Icarus Verilog +("iverilog") simulation. + +The generated Verilog is synthesizable. Bluespec tests all this code +on Xilinx FPGAs. + +#### Plans + +- Ongoing continuous micro-architectural improvements for performance and hardware area. + +---------------------------------------------------------------- +## Source codes + +This repository contains two levels of source code: Verilog and BSV. + +**Verilog RTL** can be found in directories with names suffixed in +'_verilator' or '_iverilog' in the 'builds' directory: + + builds/..._/Verilog_RTL/ + +[There is no difference between Verilog in a Verilator directory +vs. the corresponding iverilog directory. ] + +The Verilog RTL is _synthesizable_ (and hence acceptable to +Verilator). It can be simulated in any Verilog simulator (we provide +Makefiles to build simulation executables for Verilator and for Icarus +Verilog (iverilog)). + +The RTL represents RISC-V CPU RTL, plus a rudimentary surrounding SoC +enabling immediate simulation here, and which is rich enough to enable +booting a Linux kernel. Users are free to use the CPU RTL in their +own Verilog system designs. The top-level module for the CPU RTL is +`Verilog_RTL/mkBRVF_Core.v`. The top-level module for the surrounding +SoC is `Verilog_RTL/mkTop_HW_Side.v`. The SoC has an AXI4-Lite +fabric, a timer, a software-interrupt device, and a UART. Additional +library RTL can be found in the directory `src_bsc_lib_RTL`. + +**Bluespec BSV** source code (which was used to generate the Verilog RTL) can be found in: + +- `src_Core/`, for the CPU core, with sub-directories: + - `ISA/`: generic types/constants/functions for the RISC-V ISA (not CPU-implementation-specific) + - `RegFiles/`: generic register files for the GPRs (General-Purpose Registers) and CSRs (Control and Status Registers) + - `Core/`: the CPU Core + - `Near_Mem_VM/`: for the MMU and first-level cache. In the CPU, + this is instantiated twice to provide completely separate + channels (MMU and Cache) for instructions and data. + - `BSV_Additional_Libs/`: generic utilities (not CPU-specific) + - `Debug_Module/`: RISC-V Debug Module to debug the CPU from GDB or other debuggers + +- `src_Testbench/`, for the surrounding testbench, with sub-directories: + + - `Top/`: The system top-level (`Top_HW_Side.bsv`), a memory model + that loads from a memory hex file, and some imported C + functions for polled reads from the console tty (not currently + available for Icarus Verilog). + + - `SoC/`: An interconnect, a boot ROM, a memory controller, a timer + and software-interrupt device, and a UART for console tty I/O. + + - `Fabrics/`: Generic AXI4-Lite code for the SoC fabric. + +The BSV source code has a rich set of parameters, mentioned above. The +provided RTL source has been generated from the BSV source +automatically using Bluespec's `bsc` compiler, with certain particular +sets of choices for the various parameters. The generated RTL is not +parameterized. + +To generate Verilog variants with other parameter choices, the user +will need Bluespec's `bsc` compiler. See the next section for +examples of how the build is configured for different ISA features. + +In fact the CPU also supports a "Tandem Verifier" that produces an +instruction-by-instruction trace that can be checked for correctness +against a RISC-V Golden Reference Model. Please contact Bluespec, +Inc. for more information. + +---------------------------------------------------------------- +### Building and running from the Verilog sources, out of the box + +In any of the Verilog-build directories: + + builds/__verilator/ + builds/__iverilog/ + + - `$ make simulator` will create a Verilog simulation executable using Verilator or iverilog, respectively + + - `$ make test` will run the executable on the standard RISC-V ISA + test `rv32ui-p-add` or `rv64ui-p-add`, which is one of the + tests in the `Tests/isa/` directory. Examining the `test:` + target in `Makefile`, we see that it first runs the program + `Tests/elf_to_hex/elf_to_hex` on the `rv32ui-p-add` or + `rv64ui-p-add` ELF file to create a `Mem.hex` file, and then + runs the simulation executable which loads this `Mem.hex` file + into its memory. + + - Following the pattern of `$ make test`, the user can run any of + the other tests in the `Tests/isa/` directory by pointing at the + chosen ELF file. + + - `$ make isa_tests` will run the executable on + all the standard RISC-V ISA tests relevant for ARCH (regression testing). + This uses the Python script `Tests/Run_regression.py`. + Please see the documentation at the top of that program for details. + +Note: an RV32ACIMU simulator will only successfully run ELF files +compiled for RV32ACIMU, privilege U and M; running it on any other ELF +file will result in illegal instruction traps. An RV64ACDFIMSU +simulator will successfully run ELF files compiled for RV64ACDFIMSU, +privilege U, S and M. + +#### Tool dependencies: + +We test our builds with the following versions of iVerilog and +Verilator. Later versions are probably ok; we have observed some +problems with earlier versions of both tools. + + $ iverilog -v + Icarus Verilog version 10.1 (stable) () + + $ verilator --version + Verilator 3.922 2018-03-17 rev verilator_3_920-32-gdf3d1a4 + +---------------------------------------------------------------- +### What you can build and run if you have Bluespec's `bsc` compiler + +[Note: Bluespec, Inc. provides free licenses to academia and for non-profit research]. + +Note: even without Bluespec's `bsc` compiler, you can use the Verilog +sources in any of the `builds/__verilator/Verilog_RTL` +directories-- build and run Verilog simulations, incorporate the +Verilog CPU into your own SoC, etc. This section describes additional +things you can do with a `bsc` compiler. + +#### Building a Bluesim simulator + +In any of the following directories: + + builds/__bluesim + + - `$ make compile simulator` + +will compile and link a Bluesim executable. Then, you can `make test` +or `make isa_tests` as described above to run an individual ISA test +or run regressions on the full suite of relevant ISA tests. + +#### Re-generating Verilog RTL + +You can regenerate the Verilog RTL in any of the +`build/__verilator/` or `build/__iverilog/` +directories. Example: + + $ cd builds/RV32ACIMU__verilator + $ make compile + +#### Creating a new architecture configuration + +In the `builds/` directory, you can create a new sub-directory to +build a new configuration of interest. For example: + + $ cd builds + $ Resources/mkBuild_Dir.py .. RV32CI bluesim + +will create a new directory: `builds\RV32CIU__bluesim` +populated with a `Makefile` to compile and link a bluesim simulation +for an RV32 CPU with 'I' and 'C' ISA options. You can build and run +that simulator as usual: + + $ cd builds/RV32CIU__bluesim + $ make compile simulator test isa_tests + +----------------------------------------------------------------