Clean-up README.md and top-level directory (#1318)

* Clean-up README.md and top-level directory

This removes the duplicate `scripts` and `util` directories. Furthermore
the README is condensed by collapsing the citation and adding the
CITATION file to the repository.

Signed-off-by: Florian Zaruba <florian@openhwgroup.org>

* Re-name icache req/rsp structs

The structs used to communicate with the icache have contained the
direction, which makes no sense for structs since they inherently don't
have any direction.

Signed-off-by: Florian Zaruba <florian@openhwgroup.org>

---------

Signed-off-by: Florian Zaruba <florian@openhwgroup.org>

.gitignore

@@ -43,3 +43,4 @@ xrun_results/
 /core/include/gen64_config_pkg.sv
 __pycache__
 .bender/
+Bender.lock

Bender.lock

@@ -1,45 +0,0 @@
-packages:
-  axi:
-    revision: 9251564ed67e3e71adf46dbeba62ef4435d2524c
-    version: 0.31.1
-    source:
-      Git: https://github.com/pulp-platform/axi.git
-    dependencies:
-    - common_cells
-    - common_verification
-  common_cells:
-    revision: 4dc9413990622dcbf4b37a19f792834c800da5c7
-    version: 1.28.0
-    source:
-      Git: https://github.com/pulp-platform/common_cells
-    dependencies:
-    - common_verification
-    - tech_cells_generic
-  common_verification:
-    revision: 9c07fa860593b2caabd9b5681740c25fac04b878
-    version: 0.2.3
-    source:
-      Git: https://github.com/pulp-platform/common_verification.git
-    dependencies: []
-  fpnew:
-    revision: 8dc44406b1ccbc4487121710c1883e805f893965
-    version: 0.6.6
-    source:
-      Git: https://github.com/pulp-platform/fpnew.git
-    dependencies:
-    - common_cells
-    - fpu_div_sqrt_mvp
-  fpu_div_sqrt_mvp:
-    revision: 86e1f558b3c95e91577c41b2fc452c86b04e85ac
-    version: 1.0.4
-    source:
-      Git: https://github.com/pulp-platform/fpu_div_sqrt_mvp.git
-    dependencies:
-    - common_cells
-  tech_cells_generic:
-    revision: b2a68114302af1d8191ddf34ea0e07b471911866
-    version: null
-    source:
-      Git: https://github.com/pulp-platform/tech_cells_generic.git
-    dependencies:
-    - common_verification

CITATION.cff

@@ -0,0 +1,14 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Zaruba"
+  given-names: "Florian"
+  orcid: "https://orcid.org/0000-0002-8194-6521"
+- family-names: "Benini"
+  given-names: "Luca"
+  orcid: "https://orcid.org/0000-0001-8068-3806"
+title: "The Cost of Application-Class Processing: Energy and Performance Analysis of a Linux-Ready 1.7-GHz 64-Bit RISC-V Core in 22-nm FDSOI Technology"
+version: 2.0.4
+doi: 10.1109/TVLSI.2019.2926114
+date-released: 2019-07-26
+url: "https://github.com/openhwgroup/cva6"

Makefile

@@ -277,7 +277,7 @@ vcs_build: $(dpi-library)/ariane_dpi.so
 	vcs $(if $(VERDI), -kdb -debug_access+all -lca,) -full64 -timescale=1ns/1ns -ntb_opts uvm-1.2 work.ariane_tb -error="IWNF"
 
 vcs: vcs_build
-	cd $(vcs-library) && ./simv  $(if $(VERDI), -verdi -do $(root-dir)/init_testharness.do,) +permissive -sv_lib ../work-dpi/ariane_dpi +PRELOAD=$(elf-bin) +permissive-off ++$(elf-bin)| tee vcs.log
+	cd $(vcs-library) && ./simv  $(if $(VERDI), -verdi -do $(root-dir)/util/init_testharness.do,) +permissive -sv_lib ../work-dpi/ariane_dpi +PRELOAD=$(elf-bin) +permissive-off ++$(elf-bin)| tee vcs.log
 
 # Build the TB and module using QuestaSim
 build: $(library) $(library)/.build-srcs $(library)/.build-tb $(dpi-library)/ariane_dpi.so

README.md

@@ -1,6 +1,7 @@
 ![Build Status](https://github.com/openhwgroup/cva6/actions/workflows/ci.yml/badge.svg?branch=master)
 
-# :warning: We inform you that big RTL modifications are in process to better parametrize CVA6. For deeper information, please refer to the https://github.com/openhwgroup/cva6/issues/1233 github issue :warning:
+> **Warning**
+> We inform you that big RTL modifications are in process to better parametrize CVA6. For deeper information, please refer to the https://github.com/openhwgroup/cva6/issues/1233 github issue :warning:
 
 These changes will impact CVA6 interfaces (and top-level parameters). They will be performed progressively with several pull requests over a few weeks.
 To avoid integrating a moving target in their design, CVA6 users can therefore consider pointing to a specific GitHub hash during the changes
@@ -8,9 +9,9 @@ To avoid integrating a moving target in their design, CVA6 users can therefore c
 
 # CVA6 RISC-V CPU
 
-CVA6 is a 6-stage, single issue, in-order CPU which implements the 64-bit RISC-V instruction set. It fully implements I, M, A and C extensions as specified in Volume I: User-Level ISA V 2.3 as well as the draft privilege extension 1.10. It implements three privilege levels M, S, U to fully support a Unix-like operating system. Furthermore it is compliant to the draft external debug spec 0.13.
+CVA6 is a 6-stage, single-issue, in-order CPU which implements the 64-bit RISC-V instruction set. It fully implements I, M, A and C extensions as specified in Volume I: User-Level ISA V 2.3 as well as the draft privilege extension 1.10. It implements three privilege levels M, S, U to fully support a Unix-like operating system. Furthermore, it is compliant to the draft external debug spec 0.13.
 
-It has configurable size, separate TLBs, a hardware PTW and branch-prediction (branch target buffer and branch history table). The primary design goal was on reducing critical path length.
+It has a configurable size, separate TLBs, a hardware PTW and branch-prediction (branch target buffer and branch history table). The primary design goal was on reducing critical path length.
 
 ![](docs/01_cva6_user/_static/ariane_overview.png)
 
@@ -26,7 +27,9 @@ The top-level directories of this repo:
 * **core**: Source code for the CVA6 Core only. There should be no sources in this directory used to build anything other than the CVA6 core.
 * **corev_apu**: Source code for the CVA6 APU, exclusive of the CVA6 core. There should be no sources in this directory used to build the CVA6 core.
 * **docs**: Documentation.
-* **scripts**: General scriptware.
+* **pd**: Example and CI scripts to synthesis CVA6.
+* **util**: General utility scriptware.
+* **vendor**: Third-party IP maintained outside the repository.
 
 ## Verification
 The verification environment for the CVA6 is _not_ in this Repository.
@@ -48,6 +51,10 @@ and create a new issue if your problem is not yet tracked.
 
 If you use CVA6 in your academic work you can cite us:
 
+<details>
+<summary>CVA6 Publication</summary>
+<p>
+
 ```
 @article{zaruba2019cost,
    author={F. {Zaruba} and L. {Benini}},
@@ -63,31 +70,40 @@ If you use CVA6 in your academic work you can cite us:
 }
 ```
 
+</p>
+</details>
+
 CVA6 User Documentation
 =======================
 
-   * [CVA6 RISC-V CPU](#cva6-risc-v-cpu)
+- [CVA6 RISC-V CPU](#cva6-risc-v-cpu)
-   * [Table of Contents](#table-of-contents)
+  - [Directory Structure:](#directory-structure)
-      * [Getting Started](#getting-started)
+  - [Verification](#verification)
-        * [Checkout Repo](#checkout-repo)
+  - [Contributing](#contributing)
-        * [Install Verilator Simulation Flow](#install-verilator-simulation-flow)
+  - [Issues and Troubleshooting](#issues-and-troubleshooting)
-        * [Build Model and Run Simulations](#build-model-and-run-simulations)
+  - [Publication](#publication)
-        * [Running User-Space Applications](#running-user-space-applications)
+- [CVA6 User Documentation](#cva6-user-documentation)
-      * [Physical Implementation](#physical-implementation)
+  - [Getting Started](#getting-started)
-         * [ASIC Synthesis](#asic-synthesis)
+    - [Checkout Repo](#checkout-repo)
-         * [ASIC Gate Simulation with core-v-verif repository](#asic-gate-simulation-with-core-v-verif-repository)
+    - [Install Verilator Simulation Flow](#install-verilator-simulation-flow)
-      * [FPGA Emulation](#fpga-emulation)
+    - [Build Model and Run Simulations](#build-model-and-run-simulations)
-         * [Programming the Memory Configuration File](#programming-the-memory-configuration-file)
+    - [Running User-Space Applications](#running-user-space-applications)
-         * [Preparing the SD Card](#preparing-the-sd-card)
+  - [Physical Implementation](#physical-implementation)
-         * [Generating a Bitstream](#generating-a-bitstream)
+    - [ASIC Synthesis](#asic-synthesis)
-         * [Debugging](#debugging)
+    - [ASIC Gate Simulation with `core-v-verif` repository](#asic-gate-simulation-with-core-v-verif-repository)
-         * [Preliminary Support for OpenPiton Cache System](#preliminary-support-for-openpiton-cache-system)
+  - [COREV-APU FPGA Emulation](#corev-apu-fpga-emulation)
-      * [Planned Improvements](#planned-improvements)
+    - [Programming the Memory Configuration File](#programming-the-memory-configuration-file)
-      * [Going Beyond](#going-beyond)
+    - [Preparing the SD Card](#preparing-the-sd-card)
-         * [CI Testsuites and Randomized Constrained Testing with Torture](#ci-testsuites-and-randomized-constrained-testing-with-torture)
+    - [Generating a Bitstream](#generating-a-bitstream)
-         * [Re-generating the Bootcode (ZSBL)](#re-generating-the-bootcode-zsbl)
+    - [Debugging](#debugging)
-   * [Contributing](#contributing)
+    - [Preliminary Support for OpenPiton Cache System](#preliminary-support-for-openpiton-cache-system)
-   * [Acknowledgements](#acknowledgements)
+  - [Planned Improvements](#planned-improvements)
+  - [Going Beyond](#going-beyond)
+    - [CI Testsuites and Randomized Constrained Testing with Torture](#ci-testsuites-and-randomized-constrained-testing-with-torture)
+    - [Memory Preloading](#memory-preloading)
+    - [Re-generating the Bootcode (ZSBL)](#re-generating-the-bootcode-zsbl)
+- [Contributing](#contributing-1)
+- [Acknowledgements](#acknowledgements)
 
 Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 

core/cache_subsystem/cva6_icache.sv

@@ -27,21 +27,26 @@
 
 module cva6_icache import ariane_pkg::*; import wt_cache_pkg::*; #(
   parameter ariane_pkg::cva6_cfg_t CVA6Cfg = ariane_pkg::cva6_cfg_empty,
-  parameter logic [MEM_TID_WIDTH-1:0]   RdTxId             = 0,                                  // ID to be used for read transactions
+  /// ID to be used for read transactions
-  parameter ariane_pkg::ariane_cfg_t    ArianeCfg          = ariane_pkg::ArianeDefaultConfig     // contains cacheable regions
+  parameter logic [MEM_TID_WIDTH-1:0]   RdTxId = 0,
+  /// Contains cacheable regions
+  parameter ariane_pkg::ariane_cfg_t    ArianeCfg = ariane_pkg::ArianeDefaultConfig
 ) (
   input  logic                      clk_i,
   input  logic                      rst_ni,
 
-  input  logic                      flush_i,              // flush the icache, flush and kill have to be asserted together
+  /// flush the icache, flush and kill have to be asserted together
-  input  logic                      en_i,                 // enable icache
+  input  logic                      flush_i,
-  output logic                      miss_o,               // to performance counter
+  /// enable icache
+  input  logic                      en_i,
+  /// to performance counter
+  output logic                      miss_o,
   // address translation requests
-  input  icache_areq_i_t            areq_i,
+  input  icache_areq_t              areq_i,
-  output icache_areq_o_t            areq_o,
+  output icache_arsp_t              areq_o,
   // data requests
-  input  icache_dreq_i_t            dreq_i,
+  input  icache_dreq_t              dreq_i,
-  output icache_dreq_o_t            dreq_o,
+  output icache_drsp_t              dreq_o,
   // refill port
   input  logic                      mem_rtrn_vld_i,
   input  icache_rtrn_t              mem_rtrn_i,

core/cache_subsystem/cva6_icache_axi_wrapper.sv

@@ -27,11 +27,11 @@ module cva6_icache_axi_wrapper import ariane_pkg::*; import wt_cache_pkg::*; #(
   input  logic              en_i,        // enable icache
   output logic              miss_o,      // to performance counter
   // address translation requests
-  input  icache_areq_i_t    areq_i,
+  input  icache_areq_t    areq_i,
-  output icache_areq_o_t    areq_o,
+  output icache_arsp_t    areq_o,
   // data requests
-  input  icache_dreq_i_t    dreq_i,
+  input  icache_dreq_t    dreq_i,
-  output icache_dreq_o_t    dreq_o,
+  output icache_drsp_t    dreq_o,
   // AXI refill port
   output axi_req_t          axi_req_o,
   input  axi_rsp_t          axi_resp_i

core/cache_subsystem/std_cache_subsystem.sv

@@ -32,11 +32,11 @@ module std_cache_subsystem import ariane_pkg::*; import std_cache_pkg::*; #(
     input  logic                           icache_flush_i,         // flush the icache, flush and kill have to be asserted together
     output logic                           icache_miss_o,          // to performance counter
     // address translation requests
-    input  icache_areq_i_t                 icache_areq_i,          // to/from frontend
+    input  icache_areq_t                 icache_areq_i,          // to/from frontend
-    output icache_areq_o_t                 icache_areq_o,
+    output icache_arsp_t                 icache_areq_o,
     // data requests
-    input  icache_dreq_i_t                 icache_dreq_i,          // to/from frontend
+    input  icache_dreq_t                 icache_dreq_i,          // to/from frontend
-    output icache_dreq_o_t                 icache_dreq_o,
+    output icache_drsp_t                 icache_dreq_o,
     // AMOs
     input  amo_req_t                       amo_req_i,
     output amo_resp_t                      amo_resp_o,

core/cache_subsystem/wt_cache_subsystem.sv

@@ -33,11 +33,11 @@ module wt_cache_subsystem import ariane_pkg::*; import wt_cache_pkg::*; #(
   input  logic                           icache_flush_i,         // flush the icache, flush and kill have to be asserted together
   output logic                           icache_miss_o,          // to performance counter
   // address translation requests
-  input  icache_areq_i_t                 icache_areq_i,          // to/from frontend
+  input  icache_areq_t                 icache_areq_i,          // to/from frontend
-  output icache_areq_o_t                 icache_areq_o,
+  output icache_arsp_t                 icache_areq_o,
   // data requests
-  input  icache_dreq_i_t                 icache_dreq_i,          // to/from frontend
+  input  icache_dreq_t                 icache_dreq_i,          // to/from frontend
-  output icache_dreq_o_t                 icache_dreq_o,
+  output icache_drsp_t                 icache_dreq_o,
   // D$
   // Cache management
   input  logic                           dcache_enable_i,        // from CSR

core/cva6.sv

@@ -340,10 +340,10 @@ module cva6 import ariane_pkg::*; #(
   logic                     flush_commit;
   logic                     flush_acc;
 
-  icache_areq_i_t           icache_areq_ex_cache;
+  icache_areq_t           icache_areq_ex_cache;
-  icache_areq_o_t           icache_areq_cache_ex;
+  icache_arsp_t           icache_areq_cache_ex;
-  icache_dreq_i_t           icache_dreq_if_cache;
+  icache_dreq_t           icache_dreq_if_cache;
-  icache_dreq_o_t           icache_dreq_cache_if;
+  icache_drsp_t           icache_dreq_cache_if;
 
   amo_req_t                 amo_req;
   amo_resp_t                amo_resp;

core/ex_stage.sv

@@ -104,8 +104,8 @@ module ex_stage import ariane_pkg::*; #(
     input  logic [riscv::PPNW-1:0]                 satp_ppn_i,
     input  logic [ASID_WIDTH-1:0]                  asid_i,
     // icache translation requests
-    input  icache_areq_o_t                         icache_areq_i,
+    input  icache_arsp_t                         icache_areq_i,
-    output icache_areq_i_t                         icache_areq_o,
+    output icache_areq_t                         icache_areq_o,
 
     // interface to dcache
     input  dcache_req_o_t [2:0]                    dcache_req_ports_i,

core/frontend/frontend.sv

@@ -40,8 +40,8 @@ module frontend import ariane_pkg::*; #(
   input  logic               ex_valid_i,         // exception is valid - from commit
   input  logic               set_debug_pc_i,     // jump to debug address
   // Instruction Fetch
-  output icache_dreq_i_t     icache_dreq_o,
+  output icache_dreq_t     icache_dreq_o,
-  input  icache_dreq_o_t     icache_dreq_i,
+  input  icache_drsp_t     icache_dreq_i,
   // instruction output port -> to processor back-end
   output fetch_entry_t       fetch_entry_o,       // fetch entry containing all relevant data for the ID stage
   output logic               fetch_entry_valid_o, // instruction in IF is valid

core/include/ariane_pkg.sv

@@ -796,12 +796,12 @@ package ariane_pkg;
         logic                     fetch_valid;     // address translation valid
         logic [riscv::PLEN-1:0]   fetch_paddr;     // physical address in
         exception_t               fetch_exception; // exception occurred during fetch
-    } icache_areq_i_t;
+    } icache_areq_t;
 
     typedef struct packed {
         logic                     fetch_req;       // address translation request
         logic [riscv::VLEN-1:0]   fetch_vaddr;     // virtual address out
-    } icache_areq_o_t;
+    } icache_arsp_t;
 
     // I$ data requests
     typedef struct packed {
@@ -810,7 +810,7 @@ package ariane_pkg;
         logic                     kill_s2;                // kill the last request
         logic                     spec;                   // request is speculative
         logic [riscv::VLEN-1:0]   vaddr;                  // 1st cycle: 12 bit index is taken for lookup
-    } icache_dreq_i_t;
+    } icache_dreq_t;
 
     typedef struct packed {
         logic                     ready;                  // icache is ready
@@ -819,7 +819,7 @@ package ariane_pkg;
         logic [FETCH_USER_WIDTH-1:0] user;                // User bits
         logic [riscv::VLEN-1:0]   vaddr;                  // virtual address out
         exception_t               ex;                     // we've encountered an exception
-    } icache_dreq_o_t;
+    } icache_drsp_t;
 
     // AMO request going to cache. this request is unconditionally valid as soon
     // as request goes high.

core/load_store_unit.sv

@@ -47,8 +47,8 @@ module load_store_unit import ariane_pkg::*; #(
     input  logic                     en_ld_st_translation_i,   // enable virtual memory translation for load/stores
 
     // icache translation requests
-    input  icache_areq_o_t           icache_areq_i,
+    input  icache_arsp_t           icache_areq_i,
-    output icache_areq_i_t           icache_areq_o,
+    output icache_areq_t           icache_areq_o,
 
     input  riscv::priv_lvl_t         priv_lvl_i,               // From CSR register file
     input  riscv::priv_lvl_t         ld_st_priv_lvl_i,         // From CSR register file

core/mmu_sv32/cva6_mmu_sv32.sv

@@ -39,8 +39,8 @@ module cva6_mmu_sv32 import ariane_pkg::*; #(
     input  logic                            enable_translation_i,
     input  logic                            en_ld_st_translation_i,   // enable virtual memory translation for load/stores
     // IF interface
-    input  icache_areq_o_t                  icache_areq_i,
+    input  icache_arsp_t                  icache_areq_i,
-    output icache_areq_i_t                  icache_areq_o,
+    output icache_areq_t                  icache_areq_o,
     // LSU interface
     // this is a more minimalistic interface because the actual addressing logic is handled
     // in the LSU as we distinguish load and stores, what we do here is simple address translation

core/mmu_sv39/mmu.sv

@@ -28,8 +28,8 @@ module mmu import ariane_pkg::*; #(
     input  logic                            enable_translation_i,
     input  logic                            en_ld_st_translation_i,   // enable virtual memory translation for load/stores
     // IF interface
-    input  icache_areq_o_t                  icache_areq_i,
+    input  icache_arsp_t                  icache_areq_i,
-    output icache_areq_i_t                  icache_areq_o,
+    output icache_areq_t                  icache_areq_o,
     // LSU interface
     // this is a more minimalistic interface because the actual addressing logic is handled
     // in the LSU as we distinguish load and stores, what we do here is simple address translation

core/perf_counters.sv

@@ -44,7 +44,7 @@ module perf_counters import ariane_pkg::*; #(
   input  bp_resolve_t                             resolved_branch_i,
   // for newly added events
   input  exception_t                              branch_exceptions_i,  //Branch exceptions->execute unit-> branch_exception_o
-  input  icache_dreq_i_t                          l1_icache_access_i,
+  input  icache_dreq_t                          l1_icache_access_i,
   input  dcache_req_i_t[2:0]                      l1_dcache_access_i,
   input  logic [NumPorts-1:0][DCACHE_SET_ASSOC-1:0]miss_vld_bits_i,  //For Cache eviction (3ports-LOAD,STORE,PTW)
   input  logic                                    i_tlb_flush_i,

corev_apu/tb/tb_cva6_icache/hdl/tb.sv

@@ -83,10 +83,10 @@ module tb import tb_pkg::*; import ariane_pkg::*; import wt_cache_pkg::*; #()();
   logic           flush_i;
   logic           en_i;
   logic           miss_o;
-  icache_areq_i_t areq_i;
+  icache_areq_t areq_i;
-  icache_areq_o_t areq_o;
+  icache_arsp_t areq_o;
-  icache_dreq_i_t dreq_i;
+  icache_dreq_t dreq_i;
-  icache_dreq_o_t dreq_o;
+  icache_drsp_t dreq_o;
   logic           mem_rtrn_vld_i;
   icache_rtrn_t   mem_rtrn_i;
   logic           mem_data_req_o;

corev_apu/tb/tb_cva6_icache/hdl/tlb_emul.sv

@@ -25,8 +25,8 @@ module tlb_emul import ariane_pkg::*; import wt_cache_pkg::*; #(
   input logic [63:0]     tlb_offset_i,
 
   // icache interface
-  input  icache_areq_o_t req_i,
+  input  icache_arsp_t req_i,
-  output icache_areq_i_t req_o
+  output icache_areq_t req_o
 );
 
 logic tlb_ready_d, tlb_ready_q;

docs/04_cv32a6_design/source/cv32a6_frontend.rst

@@ -127,13 +127,13 @@ The module is connected to:
    * - ``icache_dreq_o``
      - out
      - CACHES
-     - icache_dreq_i_t
+     - icache_dreq_t
      - Handshake between CACHE and FRONTEND (fetch)
 
    * - ``icache_dreq_i``
      - in
      - CACHES
-     - icache_dreq_o_t
+     - icache_drsp_t
      - Handshake between CACHE and FRONTEND (fetch)
 
    * - ``fetch_entry_o``

util/CODEOWNERS

@@ -0,0 +1,16 @@
+# Global Owners
+*  @JeanRochCoulon @zarubaf
+
+# Core
+
+core/mmu_sv39 @sjthales
+core/cvxif_example @Gchauvon
+core/cvxif_fu.sv @Gchauvon
+
+# APU
+
+corev_apu/openpiton @Jbalkind
+
+## Documentation
+
+docs/ @jquevremont