diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b7cb121d2c..ecefdf2e1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ document is recommended reading. 1. From GitHub: [fork](https://help.github.com/articles/fork-a-repo/) the [cve2](https://github.com/openhwgroup/cve2) repository 2. Clone repository: `git clone https://github.com/[your_github_username]/cve2` 3. Create your feature branch: `git checkout -b .`
Please uniquify your branch name. See the [Git Cheats](https://github.com/openhwgroup/core-v-verif/blob/master/GitCheats.md) -for a useful nominclature. +for a useful nomenclature. 4. Make your edits... 5. Commit your changes: `git commit -m 'Add some feature' -s` 6. Push feature branch: `git push origin ` diff --git a/README.md b/README.md index 23d220fa01..3f2725019b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ The core will be made compatible with the OpenHW Group OBI protocol, it will use # CV32E20 RISC-V Core -CV32E20 is a production-quality open source source 32-bit RISC-V CPU core written in +CV32E20 is a production-quality open source 32-bit RISC-V CPU core written in SystemVerilog. The CPU core is heavily parametrizable and well-suited for embedded control applications. CV32E20 is being extensively verified and has seen multiple tape-outs. CV32E20 supports the Integer (I) or Embedded (E), @@ -16,7 +16,7 @@ Integer Multiplication and Division (M), and Compressed (C) extensions. The block diagram below shows the *small* parametrization with a 2-stage pipeline. -

+

CV32E20 was initially developed as part of the [PULP platform](https://www.pulp-platform.org) under the name ["Zero-riscy"](https://doi.org/10.1109/PATMOS.2017.8106976), and has been @@ -47,10 +47,12 @@ Only the person who actually performs the merge can add these labels (you need c ## Configuration + + CV32E20 offers several configuration parameters to meet the needs of various application scenarios. The options include different choices for the architecture of the multiplier unit, as well as a range of performance and security features. The table below indicates performance, area, and verification status for a few selected configurations. -These are configurations on which lowRISC is focusing for performance evaluation and design verification (see [supported configs](cve2_configs.yaml)). +These are configurations on which OpenHW is focusing for performance evaluation and design verification (see [supported configs](cve2_configs.yaml)). | Config | "micro" | "small" | | --------------------------------- | ------- | --------------------- | @@ -72,9 +74,9 @@ Notes: Green indicates that verification is close to complete. Amber indicates that some verification has been performed, but the configuration is still experimental. Red indicates a configuration with minimal/no verification. -* v.1.0.0 of the RISC-V Bit-Manipulation Extension is supported as well as the remaining sub-extensions of draft v.0.93 of the bitmanip spec. + ## Documentation (to be updated) @@ -82,11 +84,11 @@ The CVE2 documentation can be [read online at ReadTheDocs](https://docs.openhwgroup.org/projects/cve2-user-manual/en/latest/). It is also contained in the `doc` folder of this repository. -## Examples + ## Contributing diff --git a/doc/01_specification/index.rst b/doc/01_specification/index.rst index 4c113a5abb..eaaa026b99 100644 --- a/doc/01_specification/index.rst +++ b/doc/01_specification/index.rst @@ -5,6 +5,8 @@ CV32E20 Specification License ======= +Copyright (c) 2025 Eclipse Foundation + Copyright 2022-2023 OpenHW Group Copyright 2018-2022 lowRISC Revision 8d044a3d @@ -29,18 +31,17 @@ limitations under the License. Introduction ============ -The OpenHW Group CV32E20, or simply E20, is a :term:`RISC-V` processor core that +The OpenHW Foundation CV32E20, or simply E20, is a :term:`RISC-V` processor core that is targeted for the ultra-low-end of the 32-bit microcontroller (:term:`MCU`) application space. Likely uses include any “constrained compute socket” or as the processor element in embedded :term:`SoC` subsystems. The core design was originally developed as the PULPino *ZeroRISCY* processor by ETH Zürich and the University of Bologna and later enhanced -by the lowRISC consortium as the *Ibex* core. For this project, the Ibex -design description is copied and further enhanced by the OpenHW Group. -The design is qualified using the industrial-strength -Core-V-Verification methodologies. The source :term:`RTL` code is written in -SystemVerilog and maintained by the OpenHW Group. +by the lowRISC consortium as the `*Ibex* core `_. In 2023 a fork of Ibex was made +by the OpenHW Foundation and given the name *CVE2*. The CVE2 is a simplified version +of Ibex and qualified using the industrial-strength +Core-V-Verification methodologies. The source :term:`RTL` code is written in SystemVerilog and maintained by the OpenHW Foundation. This specification is organized as requirements that apply to the “Scope of the :term:`IP`". The Revision 0.1 of this requirements document is intended @@ -50,15 +51,14 @@ possibly beyond) design releases. Subsequent revision numbers are placeholders for these enhancements after the initial project freeze (PF) gate. -The requirement list is to be approved by the OpenHW Group Technical +The requirement list is to be approved by the OpenHW Foundation Technical Work Group (:term:`TWG`), as well as any subsequent change requests. -The specification is complemented by a user's guide. +The specification is complemented by a :ref:`user's guide`. A `List of Abbreviations`_ is available at the end of this document. -This development is co-sponsored by NXP and Intrinsix, a wholly owned -subsidiary of CEVA. +This development is co-sponsored by NXP and Intrinsix ( acquired by Cadence Design Systems in 2023...), and by the EU-funded `TRISTAN project `_. Scope ===== @@ -68,7 +68,7 @@ Scope of the IP The **scope of the IP** is the processor core subsystem that is specified below and that is verified with a 100% coverage goal. In the -verification plans, the scope of the IP can be partitioned into two DUTs +verification plans, the scope of the IP can be partitioned into two :term:`DUTs` (designs under test) - one covering the processor core itself, and a :term:`coreplex` covering the processor "core complex" which adds debug capabilities, an interrupt controller and system bus protocol @@ -78,8 +78,9 @@ The scope of the IP is the **CV32E20 hardware** supporting all the features used in products based on the E20 core. A high-level block diagram of the E20 core is shown below: -.. image:: ../03_reference/images/blockdiagram.svg - :alt: CV32E20 Blockdiagram +.. image:: ../03_reference/images/blockdiagram.drawio.svg + :width: 100% + :alt: CV32E20 block diagram As displayed in this core block diagram, the E20 is a 2-stage pipelined implementation featuring a 32-bit Harvard memory architecture for @@ -91,17 +92,16 @@ As displayed in the above figure, the IP comprises: - The CV32E20 processor core with dual 32-bit Harvard memory interfaces - - Instruction fetch bus, data load/store bus. Protocol is protocol is - [OPENHW-OBI]_ + - Instruction fetch bus and data load/store :term:`OBI` [OPENHW-OBI]_ buses - - Support for both RV32I (32 x 32b GPRs) and RV32E (16 x 32b GPRs) + - Support for both RV32I (32 x 32b :term:`GPRs`) and RV32E (16 x 32b GPRs) - Support for :term:`ISA` extensions: C (compressed) and M (multiply & divide) - - Support for basic set of Configuration & Status Registers (CSRs) + - Support for basic set of Configuration & Status Registers (:term:`CSRs`) -At the coreplex design level, the following functions are added to the +At the :term:`coreplex` design level, the following functions are added to the processor core: - Debug module including the :term:`DTM` @@ -123,7 +123,7 @@ an option...") versus a desired goal ("...\ *should* support...", The following topics are beyond the scope of this specification: - Software (SW layers), such as compilers, assemblers and :term:`OSes` - (although these could be part of the OpenHW Group CV32E20 project) + (although these could be part of the OpenHW Foundation CV32E20 project) - Software emulation of RISC-V optional extensions (feasible but the scope of the IP is the core and coreplex hardware) @@ -139,17 +139,17 @@ parameters. Below is the list of golden configurations that will undergo verification in the project and their main parameters. The full list of parameters for each golden configuration are detailed in the user guide. -+----------------------------+-----------------+----------------------+ -| Configuration | Target | RV32{E,I} ISA | -+----------------------------+-----------------+----------------------+ -| cv32e2_emc_fpga | :term:`FPGA` | RV32EMC | -+----------------------------+-----------------+----------------------+ -| cv32e2_imc_fpga | FPGA | RV32IMC | -+----------------------------+-----------------+----------------------+ -| cv32e2_emc_asic | :term:`ASIC` | RV32EMC | -+----------------------------+-----------------+----------------------+ -| cv32e2_imc_asic | ASIC | RV32IMC | -+----------------------------+-----------------+----------------------+ ++----------------------------+-----------------+----------------------+-------+ +| **Configuration** | **Target** | **RV32{E,I} ISA** |**TRL**| ++----------------------------+-----------------+----------------------+-------+ +| cv32e2_emc_fpga | :term:`FPGA` | RV32EMC | | ++----------------------------+-----------------+----------------------+-------+ +| cv32e2_imc_fpga | FPGA | RV32IMC | | ++----------------------------+-----------------+----------------------+-------+ +| cv32e2_emc_asic | :term:`ASIC` | RV32EMC | | ++----------------------------+-----------------+----------------------+-------+ +| cv32e2_imc_asic | ASIC | RV32IMC | | ++----------------------------+-----------------+----------------------+-------+ References ========== @@ -178,7 +178,7 @@ identify the versions of RISC-V extensions from these specifications. April 7, 2022. .. [OPENHW-OBI] OpenHW Open Bus Interface (OBI) protocol, version 1.4, - https://github.com/openhwgroup/core-v-docs/blob/master/cores/obi/OBI-v1.4.pdf + https://github.com/openhwgroup/obi/blob/main/OBI-v1.4.pdf .. [AMBA-AHB] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), https://developer.arm.com/documentation/ihi0033/latest @@ -242,7 +242,7 @@ Operating modes (Privilege Levels) | PVL-10 | CV32E20 shall support only little-endian memory | | | organizations. | +--------+--------------------------------------------------------------+ -| PVL-20 | CV32E20 shall support **machine** and **user** | +| PVL-20 | CV32E20 shall support **machine** and **user** | | | privilege modes. | +--------+--------------------------------------------------------------+ | PVL-30 | CV32E20 shall export the CPU's operating mode as an address | @@ -267,143 +267,138 @@ implemented set of CSRs is intentionally minimized. The implemented set of CSRs includes the following registers: -+--------+--------------------------------------------------------------+ -| CSR-20 | CV32E20 shall implement these mandatory Machine Mode CSRs as | -| | per specifications in [RVpriv]_. Optional registers are | -| | *highlighted*. The registers are listed based on ascending | -| | CSR number. | -| | | -| | CSR Number CSR Register Description | -| | | -| | 0x300 mstatus // machine status | -| | | -| | 0x301 misa // machine isa and extensions | -| | | -| | 0x304 mie // machine interrupt enable register | -| | | -| | 0x305 mtvec // machine trap vector base address | -| | | -| | 0x320 mcountinhibit // HPM-10: machine counter inhibit | -| | register | -| | | -| | *0x323 mhpmevent3 // HPM-20: perf monitor event selector* | -| | | -| | *0x324 mhpmevent4 // HPM-20: perf monitor event selector* | -| | | -| | *0x325 mhpmevent5 // HPM-20: perf monitor event selector* | -| | | -| | *0x326 mhpmevent6 // HPM-20: perf monitor event selector* | -| | | -| | *0x327 mhpmevent7 // HPM-20: perf monitor event selector* | -| | | -| | *0x328 mhpmevent8 // HPM-20: perf monitor event selector* | -| | | -| | *0x329 mhpmevent9 // HPM-20: perf monitor event selector* | -| | | -| | *0x32a mhpmevent10 // HPM-20: perf monitor event selector* | -| | | -| | *0x32b mhpmevent11 // HPM-20: perf monitor event selector* | -| | | -| | *0x32c mhpmevent12 // HPM-20: perf monitor event selector* | -| | | -| | 0x340 mscratch // machine scratch register | -| | | -| | 0x341 mepc // machine exception program counter | -| | | -| | 0x342 mcause // machine cause register | -| | | -| | 0x343 mtval // machine trap value register | -| | | -| | 0x344 mip // machine interrupt pending register | -| | | -| | 0x7a0 tselect // trigger select register | -| | | -| | 0x7a1 tdata1 // trigger data register 1 | -| | | -| | 0x7a2 tdata2 // trigger data register 2 | -| | | -| | 0x7a3 tdata3 // trigger data register 3 | -| | | -| | 0x7a8 mcontext // machine context register | -| | | -| | 0x7aa scontext // supervisor context register | -| | | -| | 0x7b0 dcsr // debug control and status register | -| | | -| | 0x7b1 dpc // debug pc register | -| | | -| | 0x7b2 dscratch0 // debug scratch register 0 | -| | | -| | 0x7b3 dscratch1 // debug scratch register 2 | -| | | -| | 0x7c0 cpuctrl // cpu control register | -| | | -| | 0xb00 mcycle // HPM-10: machine cycle counter | -| | | -| | 0xb02 minstret // HPM-10: machine insts retired counter | -| | | -| | *0xb03 mpmcounter3 // HPM-10: number of load/store cycles* | -| | | -| | *0xb04 mpmcounter4 // HPM-10: number of inst fetch cycles* | -| | | -| | *0xb05 mpmcounter5 // HPM-10: number of load cycles* | -| | | -| | *0xb06 mpmcounter6 // HPM-10: number of store cycles* | -| | | -| | *0xb07 mpmcounter7 // HPM-10: number of jump cycles* | -| | | -| | *0xb08 mpmcounter8 // HPM-10: number of conditional br | -| | cycles* | -| | | -| | *0xb09 mpmcounter9 // HPM-10: number of cond br taken | -| | cycles* | -| | | -| | *0xb0a mpmcounter10 // HPM-10: number of return inst cycles* | -| | | -| | *0xb0b mpmcounter11 // HPM-10: number of wfi cycles* | -| | | -| | *0xb0c mpmcounter12 // HPM-10: number of divide cycles* | -| | | -| | 0xb80 mcycleh // HPM-10: upper word of mcycle | -| | | -| | 0xb82 minstreth // HPM-10: upper word of minstret | -| | | -| | *0xb83 mpmcounter3h // HPM-20: upper word of mpmcounter3* | -| | | -| | *0xb84 mpmcounter4h // HPM-20: upper word of mpmcounter4* | -| | | -| | *0xb85 mpmcounter5h // HPM-20: upper word of mpmcounter5* | -| | | -| | *0xb86 mpmcounter6h // HPM-20: upper word of mpmcounter6* | -| | | -| | *0xb87 mpmcounter7h // HPM-20: upper word of mpmcounter7* | -| | | -| | *0xb88 mpmcounter8h // HPM-20: upper word of mpmcounter8* | -| | | -| | *0xb89 mpmcounter9h // HPM-20: upper word of mpmcounter9* | -| | | -| | *0xb8a mpmcounter10h // HPM-20: upper word of mpmcounter10* | -| | | -| | *0xb8b mpmcounter11h // HPM-20: upper word of mpmcounter11* | -| | | -| | *0xb8c mpmcounter12h // HPM-20: upper word of mpmcounter12* | -| | | -| | 0xc00 cycle // user mode cycle, lower 32b | -| | | -| | 0xc02 instret // user mode instret, lower 32b | -| | | -| | 0xc80 cycleh // user mode cycle, upper 32b | -| | | -| | 0xc82 instreth // user mode instret, upper 32b | -| | | -| | 0xf11 mvendorid // machine vendor ID | -| | | -| | 0xf12 marchid // machine architecture ID | -| | | -| | 0xf13 mimpid // machine implementation ID | -| | | -| | 0xf14 mhartid // hardware thread ID | -+--------+--------------------------------------------------------------+ ++--------+-----------------------------------------------------------------------------+ +| CSR-20 | CV32E20 shall implement these mandatory Machine Mode CSRs as per | +| | specifications in [RVpriv]_. Optional registers are *highlighted*. The | +| | registers are listed based on ascending CSR number. | +| | | +| +---------+-------------------+-----------------------------------------------+ +| | 0x300 | mstatus | machine status | +| +---------+-------------------+-----------------------------------------------+ +| | 0x301 | misa | machine isa and extensions | +| +---------+-------------------+-----------------------------------------------+ +| | 0x304 | mie | machine interrupt enable register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x305 | mtvec | machine trap vector base address | +| +---------+-------------------+-----------------------------------------------+ +| | 0x320 | mcountinhibit | HPM-10: machine counter inhibit register | +| +---------+-------------------+-----------------------------------------------+ +| | *0x323* | *mhpmevent3* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x324* | *mhpmevent4* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x325* | *mhpmevent5* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x326* | *mhpmevent6* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x327* | *mhpmevent7* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x328* | *mhpmevent8* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x329* | *mhpmevent9* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x32a* | *mhpmevent10* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x32b* | *mhpmevent11* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | *0x32c* | *mhpmevent12* | *HPM-20: perf monitor event selector* | +| +---------+-------------------+-----------------------------------------------+ +| | 0x340 | mscratch | machine scratch register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x341 | mepc | machine exception program counter | +| +---------+-------------------+-----------------------------------------------+ +| | 0x342 | mcause | machine cause register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x343 | mtval | machine trap value register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x344 | mip | machine interrupt pending register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7a0 | tselect | trigger select register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7a1 | tdata1 | trigger data register 1 | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7a2 | tdata2 | trigger data register 2 | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7a3 | tdata3 | trigger data register 3 | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7a8 | mcontext | machine context register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7aa | scontext | supervisor context register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7b0 | dcsr | debug control and status register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7b1 | dpc | debug pc register | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7b2 | dscratch0 | debug scratch register 0 | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7b3 | dscratch1 | debug scratch register 2 | +| +---------+-------------------+-----------------------------------------------+ +| | 0x7c0 | cpuctrl | cpu control register | +| +---------+-------------------+-----------------------------------------------+ +| | 0xb00 | mcycle | HPM-10: machine cycle counter | +| +---------+-------------------+-----------------------------------------------+ +| | 0xb02 | minstret | HPM-10: machine insts retired counter | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb03* | *mhpmcounter3* | *HPM-10: number of load/store cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb04* | *mhpmcounter4* | *HPM-10: number of inst fetch cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb05* | *mhpmcounter5* | *HPM-10: number of load cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb06* | *mhpmcounter6* | *HPM-10: number of store cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb07* | *mhpmcounter7* | *HPM-10: number of jump cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb08* | *mhpmcounter8* | *HPM-10: number of conditional br cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb09* | *mhpmcounter9* | *HPM-10: number of cond br taken cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb0a* | *mhpmcounter10* | *HPM-10: number of return inst cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb0b* | *mhpmcounter11* | *HPM-10: number of wfi cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb0c* | *mhpmcounter12* | *HPM-10: number of divide cycles* | +| +---------+-------------------+-----------------------------------------------+ +| | 0xb80 | mcycleh | HPM-10: upper word of mcycle | +| +---------+-------------------+-----------------------------------------------+ +| | 0xb82 | minstreth | HPM-10: upper word of minstret | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb83* | *mhpmcounter3h* | *HPM-20: upper word of *mhpmcounter3* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb84* | *mhpmcounter4h* | *HPM-20: upper word of *mhpmcounter4* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb85* | *mhpmcounter5h* | *HPM-20: upper word of *mhpmcounter5* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb86* | *mhpmcounter6h* | *HPM-20: upper word of *mhpmcounter6* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb87* | *mhpmcounter7h* | *HPM-20: upper word of *mhpmcounter7* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb88* | *mhpmcounter8h* | *HPM-20: upper word of *mhpmcounter8* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb89* | *mhpmcounter9h* | *HPM-20: upper word of *mhpmcounter9* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb8a* | *mhpmcounter10h* | *HPM-20: upper word of *mhpmcounter10* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb8b* | *mhpmcounter11h* | *HPM-20: upper word of *mhpmcounter11* | +| +---------+-------------------+-----------------------------------------------+ +| | *0xb8c* | *mhpmcounter12h* | *HPM-20: upper word of *mhpmcounter12* | +| +---------+-------------------+-----------------------------------------------+ +| | 0xc00 | cycle | user mode cycle, lower 32b | +| +---------+-------------------+-----------------------------------------------+ +| | 0xc02 | instret | user mode instret, lower 32b | +| +---------+-------------------+-----------------------------------------------+ +| | 0xc80 | cycleh | user mode cycle, upper 32b | +| +---------+-------------------+-----------------------------------------------+ +| | 0xc82 | instreth | user mode instret, upper 32b | +| +---------+-------------------+-----------------------------------------------+ +| | 0xf11 | mvendorid | machine vendor ID | +| +---------+-------------------+-----------------------------------------------+ +| | 0xf12 | marchid | machine architecture ID | +| +---------+-------------------+-----------------------------------------------+ +| | 0xf13 | mimpid | machine implementation ID | +| +---------+-------------------+-----------------------------------------------+ +| | 0xf14 | mhartid | hardware thread ID | ++--------+---------+-------------------+-----------------------------------------------+ CSR hardware performance counters --------------------------------- @@ -419,167 +414,138 @@ used to provide a fully coherent 64-bit register read that provides protection against any “race condition” involving an overflow from the lower order 32-bit register. -+--------+---------------------------------------------------------------+ -| HPM-10 | CV32E20 shall implement the 64-bit mcycle and minstret | -| | standard performance counters (including their upper 32 bits | -| | counterparts mcycleh and minstreth) as per [RVpriv]_: | -| | | -| | CSR Number PM Counter Description | -| | | -| | 0x320 mcountinhibit // machine-mode | -| | | -| | 0xb00 mcycle // machine mode cycle, lower 32 bits | -| | | -| | 0xb02 minstret // machine mode instret, lower 32 bits | -| | | -| | 0xb80 mcycleh // machine mode cycle, upper 32 bits | -| | | -| | 0xb82 minstreth // machine mode instret, upper 32 bits | -| | | -| | 0xc00 cycle // user mode cycle, lower 32b | -| | | -| | 0xc02 instret // user mode instret, lower 32b | -| | | -| | 0xc80 cycleh // user mode cycle, upper 32b | -| | | -| | 0xc82 instreth // user mode instret, upper 32b | -+--------+---------------------------------------------------------------+ -| HPM-20 | CV32E20 should support 10 optional event counters | -| | (mhpmcounterX{h}) and their associated event selector | -| | (mhpmeventX) performance monitoring registers. *The default | -| | width of these registers is 32 bits*. | -| | | -| | These registers are intended to provide hardware performance | -| | monitoring capabilities in FPGA development targets (and/or | -| | ASIC SoC targets). | -| | | -| | CSR Number PM Counter Description | -| | | -| | 0xb03 mhpmcounter3 // m-mode performance-monitoring counter 3 | -| | | -| | // NumCyclesLSU, lower 32 bits | -| | | -| | 0xb04 mphmcounter4 // m-mode performance-monitoring counter 4 | -| | | -| | // NumCyclesIF, lower 32 bits | -| | | -| | 0xb05 mphmcounter5 // m-mode performance-monitoring counter 5 | -| | | -| | // NumLoads, lower 32 bits | -| | | -| | 0xb06 mphmcounter6 // m-mode performance-monitoring counter 6 | -| | | -| | // NumStores, lower 32 bits | -| | | -| | 0xb07 mphmcounter7 // m-mode performance-monitoring counter 7 | -| | | -| | // NumJumps, lower 32 bits | -| | | -| | 0xb08 mphmcounter8 // m-mode performance-monitoring counter 8 | -| | | -| | // NumBranches, lower 32 bits | -| | | -| | 0xb09 mphmcounter9 // m-mode performance-monitoring counter 9 | -| | | -| | // NumBranchesTaken, lower 32 bits | -| | | -| | 0xb0a mphmcounter10 // m-mode performance-monitoring counter | -| | 10 | -| | | -| | // NumInstrRetC, lower 32 bits | -| | | -| | 0xb0b mphmcounter11 // m-mode performance-monitoring counter | -| | 11 | -| | | -| | // NumCyclesWFI, lower 32 bits | -| | | -| | 0xb0c mphmcounter12 // m-mode performance-monitoring counter | -| | 12 | -| | | -| | // NumCyclesDivWait, lower 32 bits | -| | | -| | 0xb83 mhpmcounter3h // m-mode performance-monitoring counter | -| | 3 | -| | | -| | // NumCyclesLSU, upper 32 bits | -| | | -| | 0xb84 mphmcounter4h // m-mode performance-monitoring counter | -| | 4 | -| | | -| | // NumCyclesIF, upper 32 bits | -| | | -| | 0xb85 mphmcounter5h // m-mode performance-monitoring counter | -| | 5 | -| | | -| | // NumLoads, upper 32 bits | -| | | -| | 0xb86 mphmcounter6h // m-mode performance-monitoring counter | -| | 6 | -| | | -| | // NumStores, upper 32 bits | -| | | -| | 0xb87 mphmcounter7h // m-mode performance-monitoring counter | -| | 7 | -| | | -| | // NumJumps, upper 32 bits | -| | | -| | 0xb88 mphmcounter8h // m-mode performance-monitoring counter | -| | 8 | -| | | -| | // NumBranches, upper 32 bits | -| | | -| | 0xb89 mphmcounter9h // m-mode performance-monitoring counter | -| | 9 | -| | | -| | // NumBranchesTaken, upper 32 bits | -| | | -| | 0xb8a mphmcounter10h // m-mode performance-monitoring counter | -| | 10 | -| | | -| | // NumInstrRetC, upper 32 bits | -| | | -| | 0xb8b mphmcounter11h // m-mode performance-monitoring counter | -| | 11 | -| | | -| | // NumCyclesWFI, upper 32 bits | -| | | -| | 0xb8c mphmcounter12h // m-mode performance-monitoring counter | -| | 12 | -| | | -| | // NumCyclesDivWait, upper 32 bits | -| | | -| | The mphmeventX registers are the event selectors and | -| | enable/disable the corresponding mphmcounterX registers. The | -| | association of the events with the mphmcounterX registers are | -| | hardwired. | -| | | -| | CSR Number Event Selector Description: event ID/bit, reset | -| | value | -| | | -| | 0x323 mhpmevent3 // 3, 0x0000_0008 | -| | | -| | 0x324 mphmevent4 // 4, 0x0000_0010 | -| | | -| | 0x325 mphmevent5 // 5, 0x0000_0020 | -| | | -| | 0x326 mphmevent6 // 6, 0x0000_0040 | -| | | -| | 0x327 mphmevent7 // 7, 0x0000_0080 | -| | | -| | 0x328 mphmevent8 // 8, 0x0000_0100 | -| | | -| | 0x329 mphmevent9 // 9, 0x0000_0200 | -| | | -| | 0x32a mphmevent10 // 10, 0x0000_0400 | -| | | -| | 0x32b mphmevent11 // 11, 0x0000_0800 | -| | | -| | 0x32c mphmevent12 // 12, 0x0000_1000 | -+--------+---------------------------------------------------------------+ ++--------+------------------------------------------------------------------------+ +| HPM-10 | CV32E20 shall implement the 64-bit mcycle and minstret | +| | standard performance counters (including their upper 32 bits | +| | counterparts mcycleh and minstreth) as per [RVpriv]_: | +| | | +| | | +| +------------+---------------+-------------------------------------------+ +| | CSR Number | PM Counter | Description | +| +------------+---------------+-------------------------------------------+ +| | 0x320 | mcountinhibit | machine-mode | +| +------------+---------------+-------------------------------------------+ +| | 0xb00 | mcycle | machine mode cycle, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb02 | minstret | machine mode instret, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb80 | mcycleh | machine mode cycle, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb82 | minstreth | machine mode instret, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xc00 | cycle | user mode cycle, lower 32b | +| +------------+---------------+-------------------------------------------+ +| | 0xc02 | instret | user mode instret, lower 32b | +| +------------+---------------+-------------------------------------------+ +| | 0xc80 | cycleh | user mode cycle, upper 32b | +| +------------+---------------+-------------------------------------------+ +| | 0xc82 | instreth | user mode instret, upper 32b | ++--------+------------------------------------------------------------------------+ +| HPM-20 | CV32E20 should support 10 optional event counters | +| | (mhpmcounterX{h}) and their associated event selector | +| | (mhpmeventX) performance monitoring registers. *The default | +| | width of these registers is 32 bits*. | +| | | +| | These registers are intended to provide hardware performance | +| | monitoring capabilities in FPGA development targets (and/or | +| | ASIC SoC targets). | +| | | +| +------------+---------------+-------------------------------------------+ +| | CSR Number | PM Counter | Description | +| +------------+---------------+-------------------------------------------+ +| | 0xb03 | mhpmcounter3 | m-mode performance-monitoring counter 3 | +| | | | NumCyclesLSU, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb04 | mhpmcounter4 | m-mode performance-monitoring counter 4 | +| | | | NumCyclesIF, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb05 | mhpmcounter5 | m-mode performance-monitoring counter 5 | +| | | | NumLoads, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb06 | mhpmcounter6 | m-mode performance-monitoring counter 6 | +| | | | NumStores, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb07 | mhpmcounter7 | m-mode performance-monitoring counter 7 | +| | | | NumJumps, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb08 | mhpmcounter8 | m-mode performance-monitoring counter 8 | +| | | | NumBranches, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb09 | mhpmcounter9 | m-mode performance-monitoring counter 9 | +| | | | NumBranchesTaken, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb0a | mhpmcounter10 | m-mode performance-monitoring counter 10 | +| | | | NumInstrRetC, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb0b | mhpmcounter11 | m-mode performance-monitoring counter 11 | +| | | | NumCyclesWFI, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb0c | mhpmcounter12 | m-mode performance-monitoring counter 12 | +| | | | NumCyclesDivWait, lower 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb83 | mhpmcounter3h | m-mode performance-monitoring counter 3 | +| | | | NumCyclesLSU, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb84 | mhpmcounter4h | m-mode performance-monitoring counter 4 | +| | | | NumCyclesIF, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb85 | mhpmcounter5h | m-mode performance-monitoring counter 5 | +| | | | NumLoads, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb86 | mhpmcounter6h | m-mode performance-monitoring counter 6 | +| | | | NumStores, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb87 | mhpmcounter7h | m-mode performance-monitoring counter 7 | +| | | | NumJumps, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb88 | mhpmcounter8h | m-mode performance-monitoring counter 8 | +| | | | NumBranches, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb89 | mphmcounter9h | m-mode performance-monitoring counter 9 | +| | | | NumBranchesTaken, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb8a | mphmcounter10h| m-mode performance-monitoring counter 10 | +| | | | NumInstrRetC, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb8b | mphmcounter11h| m-mode performance-monitoring counter 11 | +| | | | NumCyclesWFI, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | 0xb8c | mphmcounter12h| m-mode performance-monitoring counter 12 | +| | | | NumCyclesDivWait, upper 32 bits | +| +------------+---------------+-------------------------------------------+ +| | | +| | The mphmeventX registers are the event selectors and | +| | enable/disable the corresponding mphmcounterX registers. The | +| | association of the events with the mphmcounterX registers are | +| | hardwired. | +| | | +| +------------+----------------+--------------+---------------------------+ +| | CSR Number | Event Selector | event ID/bit | reset value | +| +------------+----------------+--------------+---------------------------+ +| | 0x323 | mhpmevent3 | 3 | `0x0000_0008` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x324 | mhpmevent4 | 4 | `0x0000_0010` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x325 | mhpmevent5 | 5 | `0x0000_0020` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x326 | mhpmevent6 | 6 | `0x0000_0040` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x327 | mhpmevent7 | 7 | `0x0000_0080` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x328 | mhpmevent8 | 8 | `0x0000_0100` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x329 | mhpmevent9 | 9 | `0x0000_0200` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x32a | mhpmevent10 | 10 | `0x0000_0400` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x32b | mhpmevent11 | 11 | `0x0000_0800` | ++--------+------------+----------------+--------------+---------------------------+ +| | 0x32c | mhpmevent12 | 12 | `0x0000_1000` | ++--------+------------+----------------+--------------+---------------------------+ .. note:: The Ibex documentation is incorrect/confusing about the optional - presence of mpmcounter{11,12}. This specification assumes the Ibex + presence of mhpmcounter{11,12}. This specification assumes the Ibex documentation is simply incorrect for these 2 counters. .. note:: @@ -649,6 +615,7 @@ CV32E20 coreplex memory bus | | HPROT_WIDTH 4 | | | | | | HMASTER_WIDTH 0 | +| | | +--------+-------------------------------------------------------------+ | MEM-60 | The CV32E20 coreplex AHB5 bus protocol shall not support | | | signaling associated with exclusive accesses - this implies | @@ -674,7 +641,7 @@ Debug +---------+------------------------------------------------------------+ | DBG-10 | CV32E20 shall implement the features outlined in Chapter 4 | -| | of [RVdbg]. | +| | of [RVdbg-STABLE]_ | +---------+------------------------------------------------------------+ In addition, there can be an external debug module, not in the scope of @@ -700,7 +667,7 @@ IRQs, but is not yet ratified at the time of specification. +---------+------------------------------------------------------------+ .. note:: - It should be noted that Ibex had implemented a custom mechanism for NMI + It should be noted that CVE2 had implemented a custom mechanism for NMI recovery. A standard RISC-V way of NMI recovery is in draft stage. In future, the custom mechanism could be reworked to follow the standard. @@ -793,7 +760,7 @@ the integration in FPGA and ASIC design flows: | | requirement. | +---------+------------------------------------------------------------+ -List of Abbreviations +List of abbreviations ===================== .. glossary:: diff --git a/doc/02_user/getting_started.rst b/doc/02_user/getting_started.rst index e9c6041c57..b9f0745ea9 100644 --- a/doc/02_user/getting_started.rst +++ b/doc/02_user/getting_started.rst @@ -1,9 +1,9 @@ .. _getting-started: -Getting Started with Ibex +Getting Started with CVE2 ========================= -This page discusses initial steps and requirements to start using Ibex in your design. +This page discusses initial steps and requirements to start using CVE2 in your design. Identification CSRs ------------------- @@ -12,7 +12,7 @@ The RISC-V Privileged Architecture specifies several read-only CSRs that identif These are ``mvendorid``, ``marchid`` and ``mimpid``. The fixed, read-only values for these CSRs are defined in :file:`rtl/cve2_pkg.sv`. Implementers should carefully consider appropriate values for these registers. -Ibex, as an open source implementation, has an assigned architecture ID (``marchid``) of 0x23 (equivalent to 0d35). +CVE2, as an open source implementation, has an assigned architecture ID (``marchid``) of 0x23 (equivalent to 0d35). (Allocations are specified in `marchid.md of the riscv-isa-manual repository `_.) If significant changes are made to the micro-architecture a different architecture ID should be used. The vendor ID and implementation ID (``mvendorid`` and ``mimpid``). The vendor ID (mvendorid) is assigned the value 0x602 and the implementation ID (mimpid) is assigned the value 0x0. diff --git a/doc/02_user/index.rst b/doc/02_user/index.rst index e1158776f8..f7786be3b7 100644 --- a/doc/02_user/index.rst +++ b/doc/02_user/index.rst @@ -1,8 +1,10 @@ -Ibex User Guide +.. _cve2_user_guide: + +CVE2 User Guide =============== -The Ibex User Guide provides all necessary information to use Ibex. -It is aimed at hardware developers integrating Ibex into a design, and software developers writing software running on Ibex. +The CVE2 User Guide provides all necessary information to use CVE2. +It is aimed at hardware developers integrating CVE2 into a design, and software developers writing software running on CVE2. .. toctree:: :maxdepth: 1 diff --git a/doc/02_user/integration.rst b/doc/02_user/integration.rst index 29534a8aca..ced65da57b 100644 --- a/doc/02_user/integration.rst +++ b/doc/02_user/integration.rst @@ -14,12 +14,10 @@ Instantiation Template .. code-block:: verilog cve2_top #( - .MHPMCounterNum ( 0 ), + .MHPMCounterNum ( 10 ), .MHPMCounterWidth ( 40 ), .RV32E ( 0 ), - .RV32M ( cve2_pkg::RV32MFast ), - .RndCnstLfsrSeed ( cve2_pkg::RndCnstLfsrSeedDefault ), - .RndCnstLfsrPerm ( cve2_pkg::RndCnstLfsrPermDefault ) + .RV32M ( cve2_pkg::RV32MFast ) ) u_top ( // Clock and reset .clk_i (), @@ -38,7 +36,6 @@ Instantiation Template .instr_rvalid_i (), .instr_addr_o (), .instr_rdata_i (), - .instr_rdata_intg_i (), .instr_err_i (), // Data memory interface @@ -51,9 +48,27 @@ Instantiation Template .data_wdata_o (), .data_wdata_intg_o (), .data_rdata_i (), - .data_rdata_intg_i (), .data_err_i (), + // Core-V Extension Interface (CV-X-IF) + // Issue Interface + .x_issue_valid_o (), + .x_issue_ready_i (), + .x_issue_req_o (), + .x_issue_resp_i (), + + // Register Interface + .x_register_o (), + + // Commit Interface + .x_commit_valid_o (), + .x_commit_o (), + + // Result Interface (), + .x_result_valid_i (), + .x_result_ready_o (), + .x_result_i (), + // Interrupt inputs .irq_software_i (), .irq_timer_i (), @@ -95,13 +110,13 @@ Parameters | | | | "cve2_pkg::RV32MSingleCycle": 1-2 cycle multiplier, iterative divider | +------------------------------+---------------------+------------+-----------------------------------------------------------------------+ -Any parameter marked *EXPERIMENTAL* when enabled is not verified to the same standard as the rest of the Ibex core. +Any parameter marked *EXPERIMENTAL* when enabled is not verified to the same standard as the rest of the CVE2 core. -Note that Ibex uses SystemVerilog enum parameters e.g. for ``RV32M``. +Note that CVE2 uses SystemVerilog enum parameters e.g. for ``RV32M``. This is well supported by most tools but some care is needed when overriding these parameters at the top level: * Synopsys VCS does not support overriding enum and string parameters at the top level via command line. - As a workaround, SystemVerilog defines are used in Ibex top level files simulated with VCS. + As a workaround, SystemVerilog defines are used in CVE2 top level files simulated with VCS. These defines can be set via command line. * Yosys does not support overriding enum parameters at the top level by setting enum names. diff --git a/doc/02_user/system_requirements.rst b/doc/02_user/system_requirements.rst index ed9f83f331..c9fad46b0b 100644 --- a/doc/02_user/system_requirements.rst +++ b/doc/02_user/system_requirements.rst @@ -1,31 +1,32 @@ System and Tool Requirements ============================ -The Ibex CPU core is written in SystemVerilog. -We try to achieve a balance between the used language features (as described in our `style guide `_) and reasonably wide tool support. +The CVE2 CPU core is written in SystemVerilog. +We try to achieve a balance between the used language features (as described in lowRISC's `style guide `_) and reasonably wide tool support. -The following tools are known to work with the RTL code of Ibex. -Please `file an issue `_ if you experience problems with any of the listed tools, or if you have successfully used a tool with Ibex which is not listed here. +The following tools are known to work with the RTL code of CVE2. +Please `file an issue `_ if you experience problems with any of the listed tools, or if you have successfully used a tool with CVE2 which is not listed here. +- Altair DSim - Synopsys Design Compiler - Xilinx Vivado, version |tool_requirements.vivado| and up. - Verilator, version |tool_requirements.verilator| and up. - Synopsys VCS, version at least |tool_requirements.vcs|. - Cadence Incisive/Xcelium -- Mentor Questa +- Siemens EDA Questa - Aldec Riviera Pro To run the UVM testbench a RTL simulator which supports SystemVerilog and UVM 1.2 is required. The `documentation of riscv-dv `_ contains a list of supported simulators. -To compile code that runs on Ibex, you'll need a RISC-V toolchain. +To compile code that runs on CVE2, you'll need a RISC-V toolchain. This isn't part of the core as such, but is necessary for verification. See the :doc:`Verification <../03_reference/verification>` section of the Reference Guide for more details about which toolchains the project currently uses for testing. Tools with known issues ----------------------- -Not all EDA tools have enough SystemVerilog support to be able to work with the Ibex code base. +Not all EDA tools have enough SystemVerilog support to be able to work with the CVE2 code base. Users of such tools are encouraged to file issues with the vendor. As a workaround, tools like `sv2v `_ can pre-process the source code to an older version of Verilog. diff --git a/doc/03_reference/cosim.rst b/doc/03_reference/cosim.rst index e491db9017..b8209261fb 100644 --- a/doc/03_reference/cosim.rst +++ b/doc/03_reference/cosim.rst @@ -1,179 +1,184 @@ -.. _cosim: +.. + Co-simulation System ==================== -Overview --------- +.. todo:: + + The co-simulation system needs to be recreated for the CVE2. + +.. Overview +.. -------- -A co-simulation system is provided that can run in either the Ibex UVM DV environment or with Simple System. -This system runs a RISC-V ISS (currently only Spike is supported) in lockstep with an Ibex core. -All instructions executed by Ibex and memory transactions generated are checked against the behaviour of the ISS. -This system supports memory errors, interrupt and debug requests which are observed in the RTL simulation and forwarded to the ISS so the ISS and RTL remain in sync. -The system uses a generic interface to allow support of multiple ISSes. -Only VCS is supported as a simulator, though no VCS specific functionality is required so adding support for another simulator should be straight-forward. +.. A co-simulation system is provided that can run in either the Ibex UVM DV environment or with Simple System. +.. This system runs a RISC-V ISS (currently only Spike is supported) in lockstep with an Ibex core. +.. All instructions executed by Ibex and memory transactions generated are checked against the behaviour of the ISS. +.. This system supports memory errors, interrupt and debug requests which are observed in the RTL simulation and forwarded to the ISS so the ISS and RTL remain in sync. +.. The system uses a generic interface to allow support of multiple ISSes. +.. Only VCS is supported as a simulator, though no VCS specific functionality is required so adding support for another simulator should be straight-forward. -To run the co-simulation system, a particular version of Spike is required (see the Setup and Usage section, below). +.. To run the co-simulation system, a particular version of Spike is required (see the Setup and Usage section, below). -The RISC-V Formal Interface (RVFI) is used to provide information about retired instructions and instructions that produce synchronous traps for checking. -The RVFI has been extended to provide interrupt and debug information and the value of the ``mcycle`` CSR. -These extended signals have the prefix ``rvfi_ext`` +.. The RISC-V Formal Interface (RVFI) is used to provide information about retired instructions and instructions that produce synchronous traps for checking. +.. The RVFI has been extended to provide interrupt and debug information and the value of the ``mcycle`` CSR. +.. These extended signals have the prefix ``rvfi_ext`` -The co-simulation system is EXPERIMENTAL. -It is disabled by default in the UVM DV environment currently, however it is intended to become the primary checking method for the UVM testbench. +.. The co-simulation system is EXPERIMENTAL. +.. It is disabled by default in the UVM DV environment currently, however it is intended to become the primary checking method for the UVM testbench. -Setup and Usage ---------------- +.. Setup and Usage +.. --------------- -Clone the `lowRISC fork of Spike `_ and check out the ``ibex-cosim-v0.1`` tag. -Other, later, versions called ``ibex-cosim-v*`` may also work but there's no guarantee of backwards compatibility. -Follow the Spike build instructions to build and install Spike. -The build will install multiple header files and libraries, it is recommended a custom install location (using ``--prefix=`` with ``configure``) is used to avoid cluttering system directories. -The ``--enable-commitlog`` and ``--enable-misaligned`` options must be passed to ``configure``. +.. Clone the `lowRISC fork of Spike `_ and check out the ``ibex-cosim-v0.1`` tag. +.. Other, later, versions called ``ibex-cosim-v*`` may also work but there's no guarantee of backwards compatibility. +.. Follow the Spike build instructions to build and install Spike. +.. The build will install multiple header files and libraries, it is recommended a custom install location (using ``--prefix=`` with ``configure``) is used to avoid cluttering system directories. +.. The ``--enable-commitlog`` and ``--enable-misaligned`` options must be passed to ``configure``. -Once built, the ``CVE2_COSIM_ISS_ROOT`` environment variable must be set to the Spike root install directory (as given by ``--prefix=`` to ``configure``) in order to build either the UVM DV environment or Simple System with co-simulation support. +.. Once built, the ``CVE2_COSIM_ISS_ROOT`` environment variable must be set to the Spike root install directory (as given by ``--prefix=`` to ``configure``) in order to build either the UVM DV environment or Simple System with co-simulation support. -To build/run the UVM DV environment with the co-simulator add the ``COSIM=1`` argument to the make command. -To build Simple System with the co-simulator build the ``lowrisc:cve2:cve2_simple_system_cosim`` core. +.. To build/run the UVM DV environment with the co-simulator add the ``COSIM=1`` argument to the make command. +.. To build Simple System with the co-simulator build the ``lowrisc:cve2:cve2_simple_system_cosim`` core. -Quick Build and Run Instructions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. Quick Build and Run Instructions +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Build and install the co-simulator +.. Build and install the co-simulator -.. code-block:: bash +.. .. code-block:: bash - # Get the Ibex co-simulation spike branch - git clone -b cve2_cosim https://github.com/lowRISC/riscv-isa-sim.git riscv-isa-sim-cosim +.. # Get the Ibex co-simulation spike branch +.. git clone -b cve2_cosim https://github.com/lowRISC/riscv-isa-sim.git riscv-isa-sim-cosim - # Setup build directory - cd riscv-isa-sim-cosim - mkdir build - cd build +.. # Setup build directory +.. cd riscv-isa-sim-cosim +.. mkdir build +.. cd build - # Configure and build spike - ../configure --enable-commitlog --enable-misaligned --prefix=/opt/spike-cosim - sudo make -j8 install +.. # Configure and build spike +.. ../configure --enable-commitlog --enable-misaligned --prefix=/opt/spike-cosim +.. sudo make -j8 install - # Setup CVE2_COSIM_ISS_ROOT so build flow can find the co-simulator - export CVE2_COSIM_ISS_ROOT=/opt/spike-cosim +.. # Setup CVE2_COSIM_ISS_ROOT so build flow can find the co-simulator +.. export CVE2_COSIM_ISS_ROOT=/opt/spike-cosim -Run the UVM DV regression with co-simulation enabled +.. Run the UVM DV regression with co-simulation enabled -.. code-block:: bash +.. .. code-block:: bash - # Run regression with co-simulation enabled - cd /dv/uvm/core_cve2 - make COSIM=1 +.. # Run regression with co-simulation enabled +.. cd /dv/uvm/core_cve2 +.. make COSIM=1 -Build and run Simple System with the co-simulation enabled +.. Build and run Simple System with the co-simulation enabled -.. code-block:: bash +.. .. code-block:: bash - # Build simulator - fusesoc --cores-root=. run --target=sim --setup --build lowrisc:cve2:cve2_simple_system_cosim --RV32E=0 --RV32M=cve2_pkg::RV32MFast +.. # Build simulator +.. fusesoc --cores-root=. run --target=sim --setup --build lowrisc:cve2:cve2_simple_system_cosim --RV32E=0 --RV32M=cve2_pkg::RV32MFast - # Build coremark test binary, with performance counter dump disabled. The - # co-simulator system doesn't produce matching performance counters in spike so - # any read of those CSRs results in a mismatch and a failure. - make -C ./examples/sw/benchmarks/coremark SUPPRESS_PCOUNT_DUMP=1 +.. # Build coremark test binary, with performance counter dump disabled. The +.. # co-simulator system doesn't produce matching performance counters in spike so +.. # any read of those CSRs results in a mismatch and a failure. +.. make -C ./examples/sw/benchmarks/coremark SUPPRESS_PCOUNT_DUMP=1 - # Spike's libsoftfloat.so needs to be accessible so add it to LD_LIBRARY_PATH - export LD_LIBRARY_PATH=/opt/spike-cosim/lib:$LD_LIBRARY_PATH +.. # Spike's libsoftfloat.so needs to be accessible so add it to LD_LIBRARY_PATH +.. export LD_LIBRARY_PATH=/opt/spike-cosim/lib:$LD_LIBRARY_PATH - # Run coremark binary with co-simulation checking - build/lowrisc_cve2_cve2_simple_system_cosim_0/sim-verilator/Vcve2_simple_system --meminit=ram,examples/sw/benchmarks/coremark/coremark.elf +.. # Run coremark binary with co-simulation checking +.. build/lowrisc_cve2_cve2_simple_system_cosim_0/sim-verilator/Vcve2_simple_system --meminit=ram,examples/sw/benchmarks/coremark/coremark.elf -Co-simulation details ----------------------- +.. Co-simulation details +.. ---------------------- -The co-simulation system uses DPI calls to link the DV and ISS sides together. -A C++ interface is defined in ``dv/cosim/cosim.h`` with a DPI wrapper provided by ``dv/cosim/cosim_dpi.cc`` and ``dv/cosim/cosim_dpi.h``. -A ``chandle``, which points to some class instance that implements the interface, must be provided by the DV environment. -All the co-simulation DPI calls take this ``chandle`` as a first argument. +.. The co-simulation system uses DPI calls to link the DV and ISS sides together. +.. A C++ interface is defined in ``dv/cosim/cosim.h`` with a DPI wrapper provided by ``dv/cosim/cosim_dpi.cc`` and ``dv/cosim/cosim_dpi.h``. +.. A ``chandle``, which points to some class instance that implements the interface, must be provided by the DV environment. +.. All the co-simulation DPI calls take this ``chandle`` as a first argument. -The details below discuss the C++ interface. -The DPI version of the interface is almost identical, with all functions prefaced with ``riscv_cosim`` and taking a ``chandle`` of the co-simulation instance to use. +.. The details below discuss the C++ interface. +.. The DPI version of the interface is almost identical, with all functions prefaced with ``riscv_cosim`` and taking a ``chandle`` of the co-simulation instance to use. -The core function of the co-simulation interface is the ``step`` function: +.. The core function of the co-simulation interface is the ``step`` function: -.. code-block:: c++ +.. .. code-block:: c++ - virtual bool step(uint32_t write_reg, uint32_t write_reg_data, uint32_t pc, bool sync_trap); +.. virtual bool step(uint32_t write_reg, uint32_t write_reg_data, uint32_t pc, bool sync_trap); -``step`` takes arguments giving the PC of the most recently retired or synchronously trapping instruction in the DUT along with details of any register write that occurred. +.. ``step`` takes arguments giving the PC of the most recently retired or synchronously trapping instruction in the DUT along with details of any register write that occurred. -Where ``step`` is provided with a retired (successfully executed) instruction it steps the ISS by one instruction and checks it executed the same instruction, with the same register write result, as the DUT. +.. Where ``step`` is provided with a retired (successfully executed) instruction it steps the ISS by one instruction and checks it executed the same instruction, with the same register write result, as the DUT. -When ``step`` is provided with an instruction that produces a synchronous trap, it checks the ISS also traps on the same instruction but does not step to the next executed instruction. -That instruction will be the first instruction of the trap handler and will be checked/stepped by the next call to ``step`` when it retires from the DUT. +.. When ``step`` is provided with an instruction that produces a synchronous trap, it checks the ISS also traps on the same instruction but does not step to the next executed instruction. +.. That instruction will be the first instruction of the trap handler and will be checked/stepped by the next call to ``step`` when it retires from the DUT. -Any data memory accesses that the ISS produces during the ``step`` are checked against observed DUT memory accesses. +.. Any data memory accesses that the ISS produces during the ``step`` are checked against observed DUT memory accesses. -``step`` returns false if any checks have failed. -If any errors occur during the step they can be accessed via ``get_errors`` which returns a vector of error messages. -For the DPI interface errors are accessed using ``riscv_cosim_get_num_errors`` and ``riscv_cosim_get_error``. -When errors have been checked they can be cleared with ``clear_errors``. +.. ``step`` returns false if any checks have failed. +.. If any errors occur during the step they can be accessed via ``get_errors`` which returns a vector of error messages. +.. For the DPI interface errors are accessed using ``riscv_cosim_get_num_errors`` and ``riscv_cosim_get_error``. +.. When errors have been checked they can be cleared with ``clear_errors``. -Trap Handling -^^^^^^^^^^^^^ +.. Trap Handling +.. ^^^^^^^^^^^^^ -Traps are separated into two categories, synchronous and asynchronous. -Synchronous traps are caused by a particular instruction's execution (e.g. an illegal instruction). -Asynchronous traps are caused by external interrupts. -Note that in Ibex error responses to both loads and store produce a synchronous trap so the co-simulation system has the same behaviour. +.. Traps are separated into two categories, synchronous and asynchronous. +.. Synchronous traps are caused by a particular instruction's execution (e.g. an illegal instruction). +.. Asynchronous traps are caused by external interrupts. +.. Note that in Ibex error responses to both loads and store produce a synchronous trap so the co-simulation system has the same behaviour. -A synchronous trap is associated with a particular instruction and prevents that instruction from completing its execution. -That instruction doesn't retire, but is still made visible on the RVFI. -The ``rvfi_trap`` signal is asserted for an instruction that causes a synchronous trap. -As described above ``step`` should be called for any instruction that causes a synchronous trap to check the trap is also seen by the ISS. +.. A synchronous trap is associated with a particular instruction and prevents that instruction from completing its execution. +.. That instruction doesn't retire, but is still made visible on the RVFI. +.. The ``rvfi_trap`` signal is asserted for an instruction that causes a synchronous trap. +.. As described above ``step`` should be called for any instruction that causes a synchronous trap to check the trap is also seen by the ISS. -An asynchronous trap can be seen as occurring between instructions and as such doesn't have an associated instruction, nothing will be seen on RVFI with ``rvfi_trap`` set. -The co-simulation system will immediately take any pending asynchronous trap when ``step`` is called, expecting the instruction checked with ``step`` to be the first instruction of the trap handler. +.. An asynchronous trap can be seen as occurring between instructions and as such doesn't have an associated instruction, nothing will be seen on RVFI with ``rvfi_trap`` set. +.. The co-simulation system will immediately take any pending asynchronous trap when ``step`` is called, expecting the instruction checked with ``step`` to be the first instruction of the trap handler. -While a debug request is not strictly an asynchronous trap (it doesn't use the same exception handling mechanism), they work identically to asynchronous traps for the co-simulation system. -When a debug request is pending when ``step`` is called the co-simulation will expect the instruction checked by ``step`` to be the first instruction of the debug handler. +.. While a debug request is not strictly an asynchronous trap (it doesn't use the same exception handling mechanism), they work identically to asynchronous traps for the co-simulation system. +.. When a debug request is pending when ``step`` is called the co-simulation will expect the instruction checked by ``step`` to be the first instruction of the debug handler. -Interrupts and Debug Requests -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. Interrupts and Debug Requests +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The DV environment must observe any incoming interrupts and debug requests generated by the testbench and notify the co-simulation system of them using ``set_mip``, ``set_debug_req`` and ``set_nmi``. -An interrupt or debug request will take immediate effect at the next ``step`` (if architecturally required to do so). -The DV environment is responsible for determining when to call ``set_mip``, ``set_debug_req`` and ``set_nmi`` to ensure a RTL and co-simulation match. +.. The DV environment must observe any incoming interrupts and debug requests generated by the testbench and notify the co-simulation system of them using ``set_mip``, ``set_debug_req`` and ``set_nmi``. +.. An interrupt or debug request will take immediate effect at the next ``step`` (if architecturally required to do so). +.. The DV environment is responsible for determining when to call ``set_mip``, ``set_debug_req`` and ``set_nmi`` to ensure a RTL and co-simulation match. -The state of the incoming interrupts and debug request is sampled when an instruction moves from IF to ID/EX. -The sampled state is tracked with the rest of the RVFI pipeline and used to call ``set_mip``, ``set_debug_req`` and ``set_nmi`` when the instruction is output by the RVFI. -See the comments in :file:`rtl/cve2_core.sv`, around the ``new_debug_req``, ``new_nmi`` and ``new_irq`` signals for further details. +.. The state of the incoming interrupts and debug request is sampled when an instruction moves from IF to ID/EX. +.. The sampled state is tracked with the rest of the RVFI pipeline and used to call ``set_mip``, ``set_debug_req`` and ``set_nmi`` when the instruction is output by the RVFI. +.. See the comments in :file:`rtl/cve2_core.sv`, around the ``new_debug_req``, ``new_nmi`` and ``new_irq`` signals for further details. -Memory Access Checking and Bus Errors -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. Memory Access Checking and Bus Errors +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The co-simulation system must be informed of all Dside accesses performed by the RTL using ``notify_dside_access``. -See :file:`dv/cosim/cosim.h` for further details. -As Ibex doesn't perform speculative Dside memory accesses, all notified accesses are expected to match with accesses performed by the ISS in the same order they are notified. +.. The co-simulation system must be informed of all Dside accesses performed by the RTL using ``notify_dside_access``. +.. See :file:`dv/cosim/cosim.h` for further details. +.. As Ibex doesn't perform speculative Dside memory accesses, all notified accesses are expected to match with accesses performed by the ISS in the same order they are notified. -Accesses notified via ``notify_dside_access`` can specify they saw an error response, the co-simulation system will produce the appropriate trap when the ISS attempts to access the address that saw the error. +.. Accesses notified via ``notify_dside_access`` can specify they saw an error response, the co-simulation system will produce the appropriate trap when the ISS attempts to access the address that saw the error. -Accesses must be notified before they occur in the ISS for the access matching and trapping on errors to work. +.. Accesses must be notified before they occur in the ISS for the access matching and trapping on errors to work. -Iside accesses from Ibex can be speculative, so there is no simple link between accesses produced by the RTL and the accesses performed by the ISS for the Iside. -This means no direct checking of Iside accesses is done, however errors on the Iside accesses that result in an instruction fault trap need to be notified to the co-simulation system. -``set_iside_error`` does this, it is provided with the address that saw the bus error and it should be called immediately before the ``step`` that will process the trap. -The co-simulation system will produce an instruction fault trap if it attempts to access the provided error address in the ``step`` call following the ``set_iside_error`` call. +.. Iside accesses from Ibex can be speculative, so there is no simple link between accesses produced by the RTL and the accesses performed by the ISS for the Iside. +.. This means no direct checking of Iside accesses is done, however errors on the Iside accesses that result in an instruction fault trap need to be notified to the co-simulation system. +.. ``set_iside_error`` does this, it is provided with the address that saw the bus error and it should be called immediately before the ``step`` that will process the trap. +.. The co-simulation system will produce an instruction fault trap if it attempts to access the provided error address in the ``step`` call following the ``set_iside_error`` call. -Two methods are available for dealing with bus errors on the Iside, they differ in where they probe. -One probes on the external instr_X memory interface, the other probes internally within the IF stage. -The probe used is selected by the ``probe_imem_for_err`` field of the ``core_cve2_cosim_cfg`` structure. -When set external probing is used, otherwise internal probing is used. +.. Two methods are available for dealing with bus errors on the Iside, they differ in where they probe. +.. One probes on the external instr_X memory interface, the other probes internally within the IF stage. +.. The probe used is selected by the ``probe_imem_for_err`` field of the ``core_cve2_cosim_cfg`` structure. +.. When set external probing is used, otherwise internal probing is used. -Both probe points look for addresses that have seen bus errors. -If an instruction entering ID/EX fetches from an address that has seen a bus error (as recorded by one of the probing methods) its ``rvfi_order_id`` is recorded. -When a faulting instruction is reported on the RVFI and its ``rvfi_order_id`` matches a recorded faulting one ``set_iside_error`` is called with the faulting address before the next ``step``. +.. Both probe points look for addresses that have seen bus errors. +.. If an instruction entering ID/EX fetches from an address that has seen a bus error (as recorded by one of the probing methods) its ``rvfi_order_id`` is recorded. +.. When a faulting instruction is reported on the RVFI and its ``rvfi_order_id`` matches a recorded faulting one ``set_iside_error`` is called with the faulting address before the next ``step``. -The external interface probe should be used when it is guaranteed that a bus error to address A on the external interface results in a fetch error the next time an instruction with address A is observed entering the ID/EX stage (providing no successful access to A has occurred in the mean time). -Otherwise the internal probe should be used. -When Ibex is used with the prefetch buffer this guarantee holds and the external probe can be used. -When Ibex is used with the instruction cache this guarantee does not hold and the internal probe must be used. +.. The external interface probe should be used when it is guaranteed that a bus error to address A on the external interface results in a fetch error the next time an instruction with address A is observed entering the ID/EX stage (providing no successful access to A has occurred in the mean time). +.. Otherwise the internal probe should be used. +.. When Ibex is used with the prefetch buffer this guarantee holds and the external probe can be used. +.. When Ibex is used with the instruction cache this guarantee does not hold and the internal probe must be used. -Care should be taken when using the internal probe as it will miss any bug that causes instruction faults to be ignored by the prefetch buffer or ICache (or whatever else has been used in place of these by a custom implementation). -In the case of the Ibex ICache a separate testbench ensures instruction faults are dealt with appropriately within the ICache. +.. Care should be taken when using the internal probe as it will miss any bug that causes instruction faults to be ignored by the prefetch buffer or ICache (or whatever else has been used in place of these by a custom implementation). +.. In the case of the Ibex ICache a separate testbench ensures instruction faults are dealt with appropriately within the ICache. \ No newline at end of file diff --git a/doc/03_reference/coverage_plan.rst b/doc/03_reference/coverage_plan.rst index 7b21a74a5e..4306d26de0 100644 --- a/doc/03_reference/coverage_plan.rst +++ b/doc/03_reference/coverage_plan.rst @@ -1,310 +1,312 @@ .. _coverage-plan: -Coverage Plan -============= - -.. note:: - Work to implement the functional coverage described in this plan is on-going and the plan itself is not yet complete. - -Introduction ------------- -Ibex functional coverage is split into two major categories: - -* Architectural coverage - which is concerned with instructions being executed and exercising various features of the RISC-V architecture (e.g. PMP) and does not consider the details of how this execution occurs. -* Microarchitectural coverage - which is concerned with the specifics of the RTL operation, ensuring interesting corner cases are seen along with various micro-architectural events (e.g. the different kinds of stall) and combinations of them. - -Architectural coverage is not Ibex specific. It can be determined directly from a trace of executed instructions and is handled by RISCV-DV, details can be found in the `RISCV-DV documentation `_. - -Microarchitectural coverage will probe the Ibex RTL directly and is described here. -There is some inevitable overlap between architectural and microarchitectural coverage but we aim to minimise it. - -Microarchitectural Events and Behaviour ---------------------------------------- -Below are lists of specific things from the microarchitecture that will be included in functional coverage. -Each of the points listed below must be covered. -This will be further combined using cross coverage which is described in the section below. - -Instructions -^^^^^^^^^^^^ - -Categories -"""""""""" -``cp_instr_category_id`` - -Instructions can be grouped into a number of categories. -Each category exercises different data and control paths in the core. -For example the ``ADD`` and ``SUB`` instructions are in the same category as they are almost identical for the microarchitecture (both read two registers and write to one, both feed operands to the ALU and take their result from it, both have the same response to interrupts etc; the only difference is the ALU operation). - -Instructions can be compressed or uncompressed but that isn't factored into the instruction categories below (excepting for illegal instructions). -The decompression occurs in the IF stage and is invisible to the ID/EX stage so isn't relevant for instruction execution. -A separate set of category-agnostic compressed instruction behaviour is considered instead. - -An instruction category is sampled at the ID/EX stage (which is where all the varying behaviours actually occur). -Some categories are just a single instruction, which is named without further description. - - -* **ALU** - All of the reg/reg reg/imm instructions that use the ALU. - This is any RISC-V instruction with an opcode of ``7'b0010011`` or ``7'b0110011`` (``cve2_pkg::OPCODE_OP`` and ``cve2_pkg::OPCODE_OP_IMM``) other than the ``MUL*`` and ``DIV*`` family of instructions (from RV32M). -* **Mul** - Any ``MUL*`` instruction (from RV32M). -* **Div** - Any ``DIV*`` instruction (from RV32M). -* **Branch** - Any ``B*`` family branch instruction. -* **Jump** - ``JAL``/``JALR`` -* **Load** - Any ``L*`` family load instruction. -* **Store** - Any ``S*`` family load instruction. -* **CSRAccess** - Any instruction from Zicsr. -* **EBreakDbg**/**EBreakExc** - An ``EBREAK`` instruction that either enters debug mode (Dbg) or causes an exception (Exc). - Which occurs depends upon the setting of ``dcsr.ebreakm`` / ``dcsr.ebreaku`` combined with the privilege level of executed instruction. -* ``ECALL`` -* ``MRET`` -* ``DRET`` -* ``WFI`` -* ``FENCE.I`` -* **FetchError** - Any instruction that saw a fetch error. -* **CompressedIllegal** - Any compressed instruction with an illegal encoding. -* **UncompressedIllegal** - Any uncompressed instruction with an illegal encoding. -* **CSRIllegal** - Any instruction attempting a CSR access that is not allowed. -* **PrivIllegal** - Illegal due to privilege level or being in/out of debug mode. -* **OtherIllegal** - Any other instruction that raises an Illegal instruction exception that isn't in the other categories. -* **None** - No instruction in ID/EX stage. - -Stalls -"""""" -``cp_stall_type_id`` - -Not all instructions can see all kinds of stalls. -A stall category is sampled at the ID/EX stage only (as stalls in IF and WB don't break down into categories). - -* **Instr** - A stall caused by a multi-cycle instruction. - This can be seen by instructions from categories: - - * **MUL** - * **DIV** - * **Branch** - * **Jump** - -* **LdHz** - A load hazard, the instruction in ID/EX depends upon the result of a load that is awaiting a response in writeback. - This can be seen by instructions from categories: - - * **ALU** - * **Mul** - * **Div** - * **Branch** - * **Jump** - * **Load** - * **Store** - * **CSRAccess** - -* **Mem** - Memory stall, the instruction in ID/EX is awaiting a prior memory request to complete before it can begin (to allow precise interrupts on a memory error response). This can be seen for all instruction categories - -Privilege Level -""""""""""""""" -Ibex can operate at either the M (machine) or U (user) privilege levels. -Different aspects of the Ibex microarchitecture can be using different privilege levels at once. - -* ``cp_priv_mode_if`` - Privilege level of IF stage instruction. -* ``cp_priv_mode_id`` - Privilege level of ID/EX stage instruction. -* ``cp_priv_mode_lsu`` - Privilege level of LSU operation (ID/EX privilege level modified by ``mstatus.mprv`` and ``mstatus.mpp`` settings). - -Note that the privilege level of the instruction in WB isn't retained by the microarchitecture and is not relevant to coverage. -Any instruction that reaches WB can be considered bound to retire and any relevant checks and functionality altered by the privilege mode is dealt with at an earlier stage. - -Hazards -""""""" -Ibex hazards all occur in the interaction between the ID and EX stage. - -* RAW Reg - Read after write hazard, instruction in ID/EX reads a register that writeback is writing. - Split into two versions: - - * RAW load - Instruction in ID/EX reading from destination of load in writeback. - Produces a stall (Category LdHz) and shouldn't forward data. - Covered by ``cp_stall_type_id`` - * ``cp_wb_reg_no_load_hz`` - Instruction in writeback isn't a load. - Handled with data forwarding and no stall. - -* RAW Load/Store bytes - Load with bytes overlapping a store immediately before it. - -State Specific Behaviour -"""""""""""""""""""""""" -Some instructions will behave differently depending upon the state of the processor (e.g. the privilege level the instruction executes at, CSR settings or whether the processor is in debug mode). - -* Instruction illegal in U Mode (cover execution in U and M mode). - - * ``MRET`` - * ``WFI`` - * Access to M-mode CSR. - -* Debug mode instructions (cover execution in and out of debug mode). - - * ``DRET`` - * Access to debug CSRs. - - * ``dcsr`` - * ``dpc`` - * ``dscratch0`` - * ``dscratch1`` - - * Access to trigger CSRs (also possible in M mode: cover execution in M mode, debug mode and U mode). - - * ``tselect`` - * ``tdata1`` - * ``tdata2`` - * ``tdata3`` - * ``mcontext`` - * ``scontext`` - -* Loads/stores with ``mstatus.mprv`` set and unset. -* EBreak behaviour in U/M mode with different ``dcsr.ebreakm`` / ``dcsr.ebreaku`` settings. - -Pipeline State -^^^^^^^^^^^^^^ -Each pipeline stage has some associated state. +.. TODO This needs to be updated following https://github.com/openhwgroup/cve2/issues/281 + +.. Coverage Plan +.. ============= + +.. .. note:: +.. Work to implement the functional coverage described in this plan is on-going and the plan itself is not yet complete. + +.. Introduction +.. ------------ +.. CVE2 functional coverage is split into two major categories: + +.. * Architectural coverage - which is concerned with instructions being executed and exercising various features of the RISC-V architecture (e.g. PMP) and does not consider the details of how this execution occurs. +.. * Microarchitectural coverage - which is concerned with the specifics of the RTL operation, ensuring interesting corner cases are seen along with various micro-architectural events (e.g. the different kinds of stall) and combinations of them. + +.. Architectural coverage is not CVE2 specific. It can be determined directly from a trace of executed instructions and is handled by RISCV-DV, details can be found in the `RISCV-DV documentation `_. + +.. Microarchitectural coverage will probe the CVE2 RTL directly and is described here. +.. There is some inevitable overlap between architectural and microarchitectural coverage but we aim to minimise it. + +.. Microarchitectural Events and Behaviour +.. --------------------------------------- +.. Below are lists of specific things from the microarchitecture that will be included in functional coverage. +.. Each of the points listed below must be covered. +.. This will be further combined using cross coverage which is described in the section below. + +.. Instructions +.. ^^^^^^^^^^^^ + +.. Categories +.. """""""""" +.. ``cp_instr_category_id`` + +.. Instructions can be grouped into a number of categories. +.. Each category exercises different data and control paths in the core. +.. For example the ``ADD`` and ``SUB`` instructions are in the same category as they are almost identical for the microarchitecture (both read two registers and write to one, both feed operands to the ALU and take their result from it, both have the same response to interrupts etc; the only difference is the ALU operation). + +.. Instructions can be compressed or uncompressed but that isn't factored into the instruction categories below (excepting for illegal instructions). +.. The decompression occurs in the IF stage and is invisible to the ID/EX stage so isn't relevant for instruction execution. +.. A separate set of category-agnostic compressed instruction behaviour is considered instead. + +.. An instruction category is sampled at the ID/EX stage (which is where all the varying behaviours actually occur). +.. Some categories are just a single instruction, which is named without further description. + + +.. * **ALU** - All of the reg/reg reg/imm instructions that use the ALU. +.. This is any RISC-V instruction with an opcode of ``7'b0010011`` or ``7'b0110011`` (``cve2_pkg::OPCODE_OP`` and ``cve2_pkg::OPCODE_OP_IMM``) other than the ``MUL*`` and ``DIV*`` family of instructions (from RV32M). +.. * **Mul** - Any ``MUL*`` instruction (from RV32M). +.. * **Div** - Any ``DIV*`` instruction (from RV32M). +.. * **Branch** - Any ``B*`` family branch instruction. +.. * **Jump** - ``JAL``/``JALR`` +.. * **Load** - Any ``L*`` family load instruction. +.. * **Store** - Any ``S*`` family load instruction. +.. * **CSRAccess** - Any instruction from Zicsr. +.. * **EBreakDbg**/**EBreakExc** - An ``EBREAK`` instruction that either enters debug mode (Dbg) or causes an exception (Exc). +.. Which occurs depends upon the setting of ``dcsr.ebreakm`` / ``dcsr.ebreaku`` combined with the privilege level of executed instruction. +.. * ``ECALL`` +.. * ``MRET`` +.. * ``DRET`` +.. * ``WFI`` +.. * ``FENCE.I`` +.. * **FetchError** - Any instruction that saw a fetch error. +.. * **CompressedIllegal** - Any compressed instruction with an illegal encoding. +.. * **UncompressedIllegal** - Any uncompressed instruction with an illegal encoding. +.. * **CSRIllegal** - Any instruction attempting a CSR access that is not allowed. +.. * **PrivIllegal** - Illegal due to privilege level or being in/out of debug mode. +.. * **OtherIllegal** - Any other instruction that raises an Illegal instruction exception that isn't in the other categories. +.. * **None** - No instruction in ID/EX stage. + +.. Stalls +.. """""" +.. ``cp_stall_type_id`` + +.. Not all instructions can see all kinds of stalls. +.. A stall category is sampled at the ID/EX stage only (as stalls in IF and WB don't break down into categories). + +.. * **Instr** - A stall caused by a multi-cycle instruction. +.. This can be seen by instructions from categories: + +.. * **MUL** +.. * **DIV** +.. * **Branch** +.. * **Jump** + +.. * **LdHz** - A load hazard, the instruction in ID/EX depends upon the result of a load that is awaiting a response in writeback. +.. This can be seen by instructions from categories: + +.. * **ALU** +.. * **Mul** +.. * **Div** +.. * **Branch** +.. * **Jump** +.. * **Load** +.. * **Store** +.. * **CSRAccess** + +.. * **Mem** - Memory stall, the instruction in ID/EX is awaiting a prior memory request to complete before it can begin (to allow precise interrupts on a memory error response). This can be seen for all instruction categories + +.. Privilege Level +.. """"""""""""""" +.. CVE2 can operate at either the M (machine) or U (user) privilege levels. +.. Different aspects of the CVE2 microarchitecture can be using different privilege levels at once. + +.. * ``cp_priv_mode_if`` - Privilege level of IF stage instruction. +.. * ``cp_priv_mode_id`` - Privilege level of ID/EX stage instruction. +.. * ``cp_priv_mode_lsu`` - Privilege level of LSU operation (ID/EX privilege level modified by ``mstatus.mprv`` and ``mstatus.mpp`` settings). + +.. Note that the privilege level of the instruction in WB isn't retained by the microarchitecture and is not relevant to coverage. +.. Any instruction that reaches WB can be considered bound to retire and any relevant checks and functionality altered by the privilege mode is dealt with at an earlier stage. + +.. Hazards +.. """"""" +.. CVE2 hazards all occur in the interaction between the ID and EX stage. + +.. * RAW Reg - Read after write hazard, instruction in ID/EX reads a register that writeback is writing. +.. Split into two versions: + +.. * RAW load - Instruction in ID/EX reading from destination of load in writeback. +.. Produces a stall (Category LdHz) and shouldn't forward data. +.. Covered by ``cp_stall_type_id`` +.. * ``cp_wb_reg_no_load_hz`` - Instruction in writeback isn't a load. +.. Handled with data forwarding and no stall. + +.. * RAW Load/Store bytes - Load with bytes overlapping a store immediately before it. + +.. State Specific Behaviour +.. """""""""""""""""""""""" +.. Some instructions will behave differently depending upon the state of the processor (e.g. the privilege level the instruction executes at, CSR settings or whether the processor is in debug mode). + +.. * Instruction illegal in U Mode (cover execution in U and M mode). + +.. * ``MRET`` +.. * ``WFI`` +.. * Access to M-mode CSR. + +.. * Debug mode instructions (cover execution in and out of debug mode). + +.. * ``DRET`` +.. * Access to debug CSRs. + +.. * ``dcsr`` +.. * ``dpc`` +.. * ``dscratch0`` +.. * ``dscratch1`` + +.. * Access to trigger CSRs (also possible in M mode: cover execution in M mode, debug mode and U mode). + +.. * ``tselect`` +.. * ``tdata1`` +.. * ``tdata2`` +.. * ``tdata3`` +.. * ``mcontext`` +.. * ``scontext`` + +.. * Loads/stores with ``mstatus.mprv`` set and unset. +.. * EBreak behaviour in U/M mode with different ``dcsr.ebreakm`` / ``dcsr.ebreaku`` settings. + +.. Pipeline State +.. ^^^^^^^^^^^^^^ +.. Each pipeline stage has some associated state. -* ``cp_if_stage_state`` - IF stage full and fetching, full and idle, empty and fetching, or empty and idle. - General IF stage full and stalled uninteresting as will only occur when ID stage is full and stalled. -* ``cp_wb_stage_state`` - WB stage full and stalled, full and unstalled, or empty -* ``cp_id_stage_state`` - ID stage full and stalled, full and unstalled, or empty. -* Controller (within ID stage) state machine states +.. * ``cp_if_stage_state`` - IF stage full and fetching, full and idle, empty and fetching, or empty and idle. +.. General IF stage full and stalled uninteresting as will only occur when ID stage is full and stalled. +.. * ``cp_wb_stage_state`` - WB stage full and stalled, full and unstalled, or empty +.. * ``cp_id_stage_state`` - ID stage full and stalled, full and unstalled, or empty. +.. * Controller (within ID stage) state machine states - * Possible transitions between these states. - Those marked with a '*' are of particular interest and should be crossed with instruction categories and other coverpoints as appropriate to fully explore the transitions. +.. * Possible transitions between these states. +.. Those marked with a '*' are of particular interest and should be crossed with instruction categories and other coverpoints as appropriate to fully explore the transitions. - * ``RESET`` -> ``BOOT_SET`` - * ``BOOT_SET`` -> ``FIRST_FETCH`` - * ``FIRST_FETCH`` -> ``DECODE`` - * ``FIRST_FETCH`` -> ``IRQ_TAKEN`` - * ``FIRST_FETCH`` -> ``DBG_TAKEN_IF`` - * ``DECODE`` -> ``FLUSH`` * - * ``DECODE`` -> ``DBG_TAKEN_IF`` * - * ``DECODE`` -> ``IRQ_TAKEN`` * - * ``IRQ_TAKEN`` -> ``DECODE`` - * ``DBG_TAKEN_IF`` -> ``DECODE`` - * ``DBG_TAKEN_ID`` -> ``DECODE`` - * ``FLUSH`` -> ``DECODE`` * - * ``FLUSH`` -> ``DBG_TAKEN_ID`` - * ``FLUSH`` -> ``WAIT_SLEEP`` - * ``FLUSH`` -> ``DBG_TAKEN_IF`` * - * ``WAIT_SLEEP`` -> ``SLEEP`` - * ``SLEEP`` -> ``FIRST_FETCH`` +.. * ``RESET`` -> ``BOOT_SET`` +.. * ``BOOT_SET`` -> ``FIRST_FETCH`` +.. * ``FIRST_FETCH`` -> ``DECODE`` +.. * ``FIRST_FETCH`` -> ``IRQ_TAKEN`` +.. * ``FIRST_FETCH`` -> ``DBG_TAKEN_IF`` +.. * ``DECODE`` -> ``FLUSH`` * +.. * ``DECODE`` -> ``DBG_TAKEN_IF`` * +.. * ``DECODE`` -> ``IRQ_TAKEN`` * +.. * ``IRQ_TAKEN`` -> ``DECODE`` +.. * ``DBG_TAKEN_IF`` -> ``DECODE`` +.. * ``DBG_TAKEN_ID`` -> ``DECODE`` +.. * ``FLUSH`` -> ``DECODE`` * +.. * ``FLUSH`` -> ``DBG_TAKEN_ID`` +.. * ``FLUSH`` -> ``WAIT_SLEEP`` +.. * ``FLUSH`` -> ``DBG_TAKEN_IF`` * +.. * ``WAIT_SLEEP`` -> ``SLEEP`` +.. * ``SLEEP`` -> ``FIRST_FETCH`` -Exceptions/Interrupts/Debug -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Exceptions, interrupts and debug entry can all cause control flow changes combined with CSR writes and privilege level changes and work quite similarly within the controller but not identically. -Furthermore they can all occur together and must be appropriately prioritised (consider a instruction with hardware trigger point matching it, that causes some exception and an interrupt is raised the cycle it enters the ID/EX stage) +.. Exceptions/Interrupts/Debug +.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. Exceptions, interrupts and debug entry can all cause control flow changes combined with CSR writes and privilege level changes and work quite similarly within the controller but not identically. +.. Furthermore they can all occur together and must be appropriately prioritised (consider a instruction with hardware trigger point matching it, that causes some exception and an interrupt is raised the cycle it enters the ID/EX stage) -* Exception from instruction fetch error (covered by the **FetchError** instruction category). -* Exception from instruction PMP violation. -* Exception from illegal instruction (covered by the illegal instruction categories). -* Exception from memory fetch error. -* Exception from memory access PMP violation. -* Unaligned access cases (both accesses saw error, first or second only saw error, or neither saw error) for both kinds of memory exceptions. -* Interrupt raised/taken. +.. * Exception from instruction fetch error (covered by the **FetchError** instruction category). +.. * Exception from instruction PMP violation. +.. * Exception from illegal instruction (covered by the illegal instruction categories). +.. * Exception from memory fetch error. +.. * Exception from memory access PMP violation. +.. * Unaligned access cases (both accesses saw error, first or second only saw error, or neither saw error) for both kinds of memory exceptions. +.. * Interrupt raised/taken. - * Interrupt raised/taken for each available interrupt line. - For cross coverage, the precise interrupt that's raised/taken is not relevant and it only needs to be grouped by NMI vs non-NMI. - * Interrupt raised/taken the first cycle an instruction is in ID/EX or some other cycle the instruction is in ID/EX. +.. * Interrupt raised/taken for each available interrupt line. +.. For cross coverage, the precise interrupt that's raised/taken is not relevant and it only needs to be grouped by NMI vs non-NMI. +.. * Interrupt raised/taken the first cycle an instruction is in ID/EX or some other cycle the instruction is in ID/EX. -* External debug request. -* Instruction executed when debug single step enabled. -* Instruction matches hardware trigger point. -* Ibex operating in debug mode. +.. * External debug request. +.. * Instruction executed when debug single step enabled. +.. * Instruction matches hardware trigger point. +.. * CVE2 operating in debug mode. -PMP -^^^ -* Each region configured with different matching modes. +.. PMP +.. ^^^ +.. * Each region configured with different matching modes. - * Off - * TOR - * NA4 - * NAPOT +.. * Off +.. * TOR +.. * NA4 +.. * NAPOT -* Each region configured with all possible permissions including locked/unlocked. +.. * Each region configured with all possible permissions including locked/unlocked. - * Different permissions with MML enabled and disabled, separate cover points for R/W/X/L values with and without MML. +.. * Different permissions with MML enabled and disabled, separate cover points for R/W/X/L values with and without MML. -* Access fail & pass. +.. * Access fail & pass. - * All combinations of unaligned access split across a boundary, both halves pass, neither pass, just the first passes, just the second passes. - * Higher priority entry allows access that lower priority entry prevents. - * Compressed instruction access (16-bit) passes PMP but 32-bit access at same address crosses PMP region boundary. +.. * All combinations of unaligned access split across a boundary, both halves pass, neither pass, just the first passes, just the second passes. +.. * Higher priority entry allows access that lower priority entry prevents. +.. * Compressed instruction access (16-bit) passes PMP but 32-bit access at same address crosses PMP region boundary. -* Each field of mssecfg enabled/disabled with relevant functionality tested. +.. * Each field of mssecfg enabled/disabled with relevant functionality tested. - * RLB - rule locking bypass. +.. * RLB - rule locking bypass. - * Modify locked region with RLB set. - * Try to enable RLB when RLB is disabled and locked regions present. +.. * Modify locked region with RLB set. +.. * Try to enable RLB when RLB is disabled and locked regions present. - * MMWP - machine mode whitelist policy. +.. * MMWP - machine mode whitelist policy. - * M-mode access fail due to not matching any PMP regions. - * Try to disable when enabled. +.. * M-mode access fail due to not matching any PMP regions. +.. * Try to disable when enabled. - * MML - machine mode lockdown policy. +.. * MML - machine mode lockdown policy. - * Try to disable when enabled. +.. * Try to disable when enabled. - * Access close to PMP region modification that allows/disallows that access. +.. * Access close to PMP region modification that allows/disallows that access. -CSRs -^^^^ -Basic read/write functionality must be tested on all implemented CSRs. +.. CSRs +.. ^^^^ +.. Basic read/write functionality must be tested on all implemented CSRs. -* Read from CSR. -* Write to CSR. +.. * Read from CSR. +.. * Write to CSR. - * Write to read only CSR. +.. * Write to read only CSR. -* Write illegal/unsupported value to WARL field. -* Access to CSR disallowed due to privilege level/debug mode. -* Read and write from/to an unimplemented CSR +.. * Write illegal/unsupported value to WARL field. +.. * Access to CSR disallowed due to privilege level/debug mode. +.. * Read and write from/to an unimplemented CSR -CSRs addresses do not need to be crossed with the variety of CSR instructions as these all use the same basic read & write interface into ``cve2_cs_registers``. -Coverage of the above points will be sampled at the ``cve2_cs_registers`` interface (as opposed to sampling CSR instructions). +.. CSRs addresses do not need to be crossed with the variety of CSR instructions as these all use the same basic read & write interface into ``cve2_cs_registers``. +.. Coverage of the above points will be sampled at the ``cve2_cs_registers`` interface (as opposed to sampling CSR instructions). -Miscellaneous -^^^^^^^^^^^^^ -Various points of interest do not fit into the categories above. +.. Miscellaneous +.. ^^^^^^^^^^^^^ +.. Various points of interest do not fit into the categories above. -* Instruction unstalled - Cover the cycle an instruction is unstalled having just been stalled. -* Stalled awaiting an instruction fetch. -* Double fault. -* Awake from sleep. -* Interrupt/Debug whilst entering sleep. +.. * Instruction unstalled - Cover the cycle an instruction is unstalled having just been stalled. +.. * Stalled awaiting an instruction fetch. +.. * Double fault. +.. * Awake from sleep. +.. * Interrupt/Debug whilst entering sleep. -Cross Coverage --------------- -Much of the more complex behaviour lies at the combination of the individual microarchitectural behaviours above. -Cross coverage is used to capture that. -There are some broad crosses containing many bins aiming to capture all combinations of some generalised behaviours as well as some more specific ones to capture all combinations of behaviours focused on a particular area. +.. Cross Coverage +.. -------------- +.. Much of the more complex behaviour lies at the combination of the individual microarchitectural behaviours above. +.. Cross coverage is used to capture that. +.. There are some broad crosses containing many bins aiming to capture all combinations of some generalised behaviours as well as some more specific ones to capture all combinations of behaviours focused on a particular area. -Cross coverage will be intentionally broad. -Where it is proving hard to hit particular bins they will be reviewed in more detail to determine if they're impossible to hit or if simply hard to hit and whether hitting them provides meaningful gains to verification quality. +.. Cross coverage will be intentionally broad. +.. Where it is proving hard to hit particular bins they will be reviewed in more detail to determine if they're impossible to hit or if simply hard to hit and whether hitting them provides meaningful gains to verification quality. -Excluded bins will either become illegal bins (where they are impossible to hit, so a failure will be seen if they are hit) or ignore bins (where they don't factor into coverage statistics). -There must be a documented reason a particular bin is added to the illegal or ignore bins. +.. Excluded bins will either become illegal bins (where they are impossible to hit, so a failure will be seen if they are hit) or ignore bins (where they don't factor into coverage statistics). +.. There must be a documented reason a particular bin is added to the illegal or ignore bins. -* All combinations of privilege levels across IF, ID/EX and LSU -* Instruction Categories x Pipeline stage states across IF, ID/EX and WB +.. * All combinations of privilege levels across IF, ID/EX and LSU +.. * Instruction Categories x Pipeline stage states across IF, ID/EX and WB - * Covers all possibilities of instruction combinations that could fill the pipeline. State only for IF/WB suffices to cover this as all the interesting per instruction behaviour occurs in ID/EX. - * All bins containing instruction categories other than **None** ignored when ID/EX stage is empty. +.. * Covers all possibilities of instruction combinations that could fill the pipeline. State only for IF/WB suffices to cover this as all the interesting per instruction behaviour occurs in ID/EX. +.. * All bins containing instruction categories other than **None** ignored when ID/EX stage is empty. -* Instructions Categories x ID/EX Privilege level -* Instruction Categories x Stall Categories +.. * Instructions Categories x ID/EX Privilege level +.. * Instruction Categories x Stall Categories - * Illegal bins will be used to exclude instruction and stall categories that cannot occur. +.. * Illegal bins will be used to exclude instruction and stall categories that cannot occur. -* Instruction Categories x Hazards -* Instruction Categories x Debug Mode -* Instruction Categories x IF/WB full or empty -* Instruction Categories x Controller state transitions of interest -* Interrupt taken/Debug mode entry/Pipe flush x instruction unstalled x instruction category +.. * Instruction Categories x Hazards +.. * Instruction Categories x Debug Mode +.. * Instruction Categories x IF/WB full or empty +.. * Instruction Categories x Controller state transitions of interest +.. * Interrupt taken/Debug mode entry/Pipe flush x instruction unstalled x instruction category - * Three separate cross coverage groups: one for interrupt, debug and pipe flush. - * Covers all instruction categories being interrupted/entering debug mode/flushing the pipeline both where this occurs during a stall and when it occurs just when they've unstalled. +.. * Three separate cross coverage groups: one for interrupt, debug and pipe flush. +.. * Covers all instruction categories being interrupted/entering debug mode/flushing the pipeline both where this occurs during a stall and when it occurs just when they've unstalled. -* PMP exception x load/store error exception x instruction category x stall type x unstalled x irq pending x debug req +.. * PMP exception x load/store error exception x instruction category x stall type x unstalled x irq pending x debug req - * Large cross to cover all possibilities of combinations between interrupt, debug and exceptions for all instruction categories across all stall behaviours. +.. * Large cross to cover all possibilities of combinations between interrupt, debug and exceptions for all instruction categories across all stall behaviours. -* PMP regions x permissions x access fail/pass +.. * PMP regions x permissions x access fail/pass diff --git a/doc/03_reference/cs_registers.rst b/doc/03_reference/cs_registers.rst index 39b0337798..40498b6b6b 100644 --- a/doc/03_reference/cs_registers.rst +++ b/doc/03_reference/cs_registers.rst @@ -3,7 +3,7 @@ Control and Status Registers ============================ -Ibex implements all the Control and Status Registers (CSRs) listed in the following table according to the RISC-V Privileged Specification, version 1.11. +CVE2 implements all the Control and Status Registers (CSRs) listed in the following table according to the RISC-V Privileged Specification, version 1.11. +---------+--------------------+--------+-----------------------------------------------+ | Address | Name | Access | Description | @@ -143,7 +143,7 @@ CSR Address: ``0x301`` Reset Value: ``0x4010_1104`` ``misa`` is a WARL register which describes the ISA supported by the hart. -On Ibex, ``misa`` is hard-wired, i.e. it will remain unchanged after any write. +On CVE2, ``misa`` is hard-wired, i.e. it will remain unchanged after any write. Detailed: @@ -404,7 +404,7 @@ Reset Value: ``0x2800_1000`` Accessible in Debug Mode or M-Mode. Since native triggers are not supported, writes to this register from M-Mode will be ignored. -Ibex only implements one type of trigger, instruction address match. +CVE2 only implements one type of trigger, instruction address match. Most fields of this register will read as a fixed value to reflect the mode that is supported. +-------+------+------------------------------------------------------------------+ @@ -471,7 +471,7 @@ Reset Value: ``0x0000_0000`` Accessible in Debug Mode or M-Mode. -Ibex does not support the features requiring this register, so writes are ignored and it will always read as zero. +CVE2 does not support the features requiring this register, so writes are ignored and it will always read as zero. Machine Context Register (mcontext) ----------------------------------- @@ -482,7 +482,7 @@ Reset Value: ``0x0000_0000`` Accessible in Debug Mode or M-Mode. -Ibex does not support the features requiring this register, so writes are ignored and it will always read as zero. +CVE2 does not support the features requiring this register, so writes are ignored and it will always read as zero. Supervisor Context Register (scontext) -------------------------------------- @@ -493,7 +493,7 @@ Reset Value: ``0x0000_0000`` Accessible in Debug Mode or M-Mode. -Ibex does not support the features requiring this register, so writes are ignored and it will always read as zero. +CVE2 does not support the features requiring this register, so writes are ignored and it will always read as zero. .. _csr-dcsr: @@ -505,7 +505,7 @@ CSR Address: ``0x7B0`` Reset Value: ``0x4000_0003`` Accessible in Debug Mode only. -Ibex implements the following bit fields. +CVE2 implements the following bit fields. Other bit fields read as zero. +-------+------+------------------------------------------------------------------+ @@ -526,7 +526,7 @@ Other bit fields read as zero. +-------+------+------------------------------------------------------------------+ | 1:0 | WARL | **prv:** Privilege level the core was operating in when Debug | | | | Mode was entered. May be modified by debugger to change | -| | | privilege level. Ibex allows transitions to all supported modes. | +| | | privilege level. CVE2 allows transitions to all supported modes. | | | | (M- and U-Mode). | +-------+------+------------------------------------------------------------------+ @@ -577,7 +577,7 @@ Reset Value: ``0x0000_0000`` Custom CSR to control runtime configuration of CPU components. Accessible in Machine Mode only. -Ibex implements the following bit fields. +CVE2 implements the following bit fields. Other bit fields read as zero. +-------+------+------------------------------------------------------------------+ @@ -603,7 +603,7 @@ Time Registers (time(h)) CSR Address: ``0xC01 / 0xC81`` -The User Mode ``time(h)`` registers are not implemented in Ibex. +The User Mode ``time(h)`` registers are not implemented in CVE2. Any access to these registers will trap. It is recommended that trap handler software provides a means of accessing platform-defined ``mtime(h)`` timers where available. diff --git a/doc/03_reference/exception_interrupts.rst b/doc/03_reference/exception_interrupts.rst index 3a010e78de..c08800dee2 100644 --- a/doc/03_reference/exception_interrupts.rst +++ b/doc/03_reference/exception_interrupts.rst @@ -3,7 +3,7 @@ Exceptions and Interrupts ========================= -Ibex implements trap handling for interrupts and exceptions according to the RISC-V Privileged Specification, version 1.11. +CVE2 implements trap handling for interrupts and exceptions according to the RISC-V Privileged Specification, version 1.11. When entering an interrupt/exception handler, the core sets the ``mepc`` CSR to the current program counter and saves ``mstatus``.MIE to ``mstatus``.MPIE. All exceptions cause the core to jump to the base address of the vector table in the ``mtvec`` CSR. @@ -20,14 +20,14 @@ It is assumed that the boot address is supplied via a register to avoid long pat Privilege Modes --------------- -Ibex supports operation in Machine Mode (M-Mode) and User Mode (U-Mode). +CVE2 supports operation in Machine Mode (M-Mode) and User Mode (U-Mode). The core resets into M-Mode and will jump to M-Mode on any interrupt or exception. On execution of an MRET instruction, the core will return to the Privilege Mode stored in ``mstatus``.MPP. Interrupts ---------- -Ibex supports the following interrupts. +CVE2 supports the following interrupts. +-------------------------+-------+--------------------------------------------------+ | Interrupt Input Signal | ID | Description | @@ -51,7 +51,7 @@ For more information, see the :ref:`cs-registers` documentation. If multiple interrupts are pending, they are handled in the priority order defined by the RISC-V Privileged Specification, version 1.11 (see Machine Interrupt Registers, Section 3.1.9). The fast interrupts have a platform defined priority. -In Ibex they take priority over all other interrupts and between fast interrupts the highest priority is given to the interrupt with the lowest ID. +In CVE2 they take priority over all other interrupts and between fast interrupts the highest priority is given to the interrupt with the lowest ID. The NMI is enabled independent of the values in the ``mstatus`` and ``mie`` CSRs, and it is not visible through the ``mip`` CSR. It has interrupt ID 31, i.e., it has the highest priority of all interrupts and the core jumps to the trap-handler base address (in ``mtvec``) plus 0x7C to handle the NMI. @@ -67,7 +67,7 @@ In Debug Mode, all interrupts including the NMI are ignored independent of ``mst Recoverable Non-Maskable Interrupt ---------------------------------- -To support recovering from an NMI happening during a trap handling routine, Ibex features additional CSRs for backing up ``mstatus``.MPP, ``mstatus``.MPIE, ``mepc`` and ``mcause``. +To support recovering from an NMI happening during a trap handling routine, CVE2 features additional CSRs for backing up ``mstatus``.MPP, ``mstatus``.MPIE, ``mepc`` and ``mcause``. These CSRs are not accessible by software running on the core. These CSRs are nonstandard. @@ -77,7 +77,7 @@ For more information, see `the corresponding proposal `_ for energy-efficient computing. +CVE2 development started in 2015 under the name "Zero-riscy" as part of the `PULP platform `_ for energy-efficient computing. Much of the code was developed by simplifying the RV32 CPU core "RI5CY" to demonstrate how small a RISC-V CPU core could actually be `[1] `_. To make it even smaller, support for the "E" extension was added under the code name "Micro-riscy". In the PULP ecosystem, the core is used as the control core for PULP, PULPino and PULPissimo. In December 2018 lowRISC took over the development of Zero-riscy and renamed it to Ibex. +In 2023 the OpenHW Foundation forked Ibex and renamed the fork CVE2. References ---------- diff --git a/doc/03_reference/images/blockdiagram.drawio.svg b/doc/03_reference/images/blockdiagram.drawio.svg new file mode 100644 index 0000000000..3f0d4246ff --- /dev/null +++ b/doc/03_reference/images/blockdiagram.drawio.svg @@ -0,0 +1,950 @@ + + + + + + + + + + + + + + +
+
+
+

+ + prefetch +
+ buffer + +

+
+
+
+ + + prefetch... + + + + + + + + + +
+
+
+

+ + compressed +
+ decoder + +

+
+
+
+ + + compressed... + + + + + + + +
+
+
+

+
+

+
+
+
+ + + + + + + + + +
+
+
+

+ + decoder + +

+
+
+
+ + + decoder + + + + + + + + + + + + + + +
+
+
+

+ RF +
+ IM +

+
+
+
+ + + RF... + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+

+ controller +

+
+
+
+ + + controller + + + + + + + +
+
+
+

+ sleep unit +

+
+
+
+ + + sleep unit + + + + + + + +
+
+
+

+ data memory interface +

+
+
+
+ + + data memory interface + + + + + + + +
+
+
+

+ instruction memory interface +

+
+
+
+ + + instruction memory interface + + + + + + + + + + + + + + + + + + +
+
+
+

+ + PC +
+ RF +
+ IM + +

+
+
+
+ + + PC... + + + + + + + + + + + + +
+
+
+

+
+

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+

+ debug interface +

+
+
+
+ + + debug interface + + + + + + + +
+
+
+

+ interrrupt interface +

+
+
+
+ + + interrrupt interface + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ rA +
+
+
+ + + rA + + + + + + + +
+
+
+ + register + +
+ + file + +
+
+
+ + + register... + + + + + + + +
+
+
+ DA +
+
+
+ + + DA + + + + + + + +
+
+
+ rB +
+
+
+ + + rB + + + + + + + +
+
+
+ DIA +
+
+
+ + + DIA + + + + + + + +
+
+
+ DB +
+
+
+ + + DB + + + + + + + +
+
+
+ + CV32E20 + +
+
+
+ + + CV32E20 + + + + + + + +
+
+
+

+ + + eXtension InterFace +
+ (CV-X-IF) + + +
+

+
+
+
+ + + eXtension InterFace... + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + issue +
+ commit + +
+
+
+ + + issue... + + + + + + + +
+
+
+ + result + +
+
+
+ + + result + + + + + + + + + + + + + + + +
+
+
+ + + X + + +
+
+
+ + + X + + + + + + + + + + + + + + + + +
+
+
+

+ MULT/DIV +

+
+
+
+ + + MULT/DIV + + + + + + + + + + + + + +
+
+
+ result +
+
+
+ + + resu... + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + + + + + +
+
+
+

+ ALU +

+
+
+
+ + + ALU + + + + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + + + + + + + + +
+
+
+ result +
+
+
+ + + resu... + + + + + + + +
+
+
+

+ CSR +

+
+
+
+ + + CSR + + + + + + + + + + + + + + + + + +
+
+
+ RD +
+
+
+ + + RD + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + +
+
+
+

+ LSU +

+
+
+
+ + + LSU + + + + + + + + + + + + + + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/doc/03_reference/images/blockdiagram.svg b/doc/03_reference/images/blockdiagram.svg deleted file mode 100644 index 7ff76cd5b8..0000000000 --- a/doc/03_reference/images/blockdiagram.svg +++ /dev/null @@ -1,2303 +0,0 @@ - -image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -PC - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -IFID - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -IM - - - - - - - - - - - - - -RF - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -IM - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -RF - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -CV32E20 - - - - - - - - - - -registerfile - -DIA - -rB - -rA - -DA - -DB - - - - - - - - - - - - -CSR - -OpA - -OpB - -RD - -ALU - -OpB - - - -RD - -OpA - -MULT - -OpA - -OpB - -RD - - - - - - - - - - - - - - - - - - - - - - - - - - - -prefetchbuffer - - - - - -decodercontroller - -aligner - - - - - - - - - - - - - - - - -LSUOpAOpBcompressdecodersleep unitinterrupt interfacedebug interfaceinstructioninterfacedatainterfaceRD diff --git a/doc/03_reference/images/de_ex_stage.drawio.svg b/doc/03_reference/images/de_ex_stage.drawio.svg new file mode 100644 index 0000000000..9ebf5b49b4 --- /dev/null +++ b/doc/03_reference/images/de_ex_stage.drawio.svg @@ -0,0 +1,885 @@ + + + + + + + + + + + + +
+
+
+

+ + + eXtension InterFace +
+ (CV-X-IF) + + +
+

+
+
+
+ + + eXtension InterFace... + + + + + + + + + + + + +
+
+
+

+
+

+
+
+
+ + + + + + + + +
+
+
+

+ LSU +

+
+
+
+ + + LSU + + + + + + + + +
+
+
+ + EX Block + +
+
+
+ + + EX Block + + + + + + + + + + + + + +
+
+
+

+ + PC +
+ RF +
+ IM + +

+
+
+
+ + + PC... + + + + + + + + + + + + +
+
+
+

+ IM +
+ RF +

+
+
+
+ + + IM... + + + + + + + + + + + + +
+
+
+

+
+

+
+
+
+ + + + + + + + + +
+
+
+

+ + controller + +

+
+
+
+ + + controller + + + + + + + + + + + +
+
+
+ + ID Stage + +
+
+
+ + + ID Stage + + + + + + + +
+
+
+ IF Stage +
+
+
+ + + IF Sta... + + + + + + + + + +
+
+
+

+ CSR +

+
+
+
+ + + CSR + + + + + + + + + + + + + + + + +
+
+
+ RD +
+
+
+ + + RD + + + + + + + +
+
+
+

+ MULT/DIV +
+

+
+
+
+ + + MULT/DIV + + + + + + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + + + + + + + + + +
+
+
+

+ data memory nterface +

+
+
+
+ + + data memory nterface + + + + + + + + + + + + + + + + +
+
+
+ 32 +
+
+
+ + + 32 + + + + + + +
+
+
+ 32 +
+
+
+ + + 32 + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + CVE2 Core + +
+
+
+ + + CVE2 Core + + + + + + + + +
+
+
+

+ ALU +

+
+
+
+ + + ALU + + + + + + + + + + +
+
+
+ OpA +
+
+
+ + + OpA + + + + + + + + + +
+
+
+ OpB +
+
+
+ + + OpB + + + + + + + + +
+
+
+ mdiv_OpA +
+
+
+ + + mdiv_OpA + + + + + + +
+
+
+ mdiv_OpB +
+
+
+ + + mdiv_OpB + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ result +
+
+
+ + + result + + + + + + +
+
+
+ result +
+
+
+ + + result + + + + + + + +
+
+
+

+ + decoder + +

+
+
+
+ + + decoder + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+

+ + reg file + +

+
+
+
+ + + reg file + + + + + + + +
+
+
+ + Wr + +
+
+
+ + + Wr + + + + + + + + + + + +
+
+
+ + RdA + +
+
+
+ + + RdA + + + + + + +
+
+
+ + RdB + +
+
+
+ + + RdB + + + + + + + + +
+
+
+ wdata_o +
+
+
+ + + wdata_o + + + + + + +
+
+
+ addr_o +
+
+
+ + + addr_o + + + + + + +
+
+
+ rdata_o +
+
+
+ + + rdata_o + + + + + + +
+
+
+ debug_req_i +
+
+
+ + + debug_req_i + + + + + + +
+
+
+ jump_target_ex +
+
+
+ + + jump_target_ex + + + + + + + + +
+
+
+ + IM + +
+
+
+ + + IM + + + + + + +
+
+
+ + result + +
+
+
+ + + result + + + + + + +
+
+
+ + commit +
+ +
+
+
+ + + commi... + + + + + + +
+
+
+ + issue +
+ +
+
+
+ + + issue + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/doc/03_reference/images/de_ex_stage.svg b/doc/03_reference/images/de_ex_stage.svg deleted file mode 100644 index 5b0d1eb9d5..0000000000 --- a/doc/03_reference/images/de_ex_stage.svg +++ /dev/null @@ -1,1128 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - CSR - - IM - ID Stage - - EX Block - - IDEX - - - Decoder - - - Controller - - - Reg File - - - ALU - - - OpA - OpB - - MULTDIV - - - - RdA - RdB - Wr - - IM - - PC - RF - - RF - IM - - - - - - - - - - - - - LSU - - - - - - - - Data Mem - - - - - - - addr_o - wdata_o - rdata_i - Ibex Core - - - - - - - - - - - OpA - OpB - - - - - - - - - - - - - - - - - - - - - 32 - - 32 - IM - - - debug_req_i - jump_target_ex - - - diff --git a/doc/03_reference/images/if_stage.drawio.svg b/doc/03_reference/images/if_stage.drawio.svg new file mode 100644 index 0000000000..e34a135163 --- /dev/null +++ b/doc/03_reference/images/if_stage.drawio.svg @@ -0,0 +1,353 @@ + + + + + + + + + + + + + + + + + +
+
+
+

+
+

+
+
+
+ + + + + + + + +
+
+
+

+ instruction memory interface +

+
+
+
+ + + instruction memory interface + + + + + + + +
+
+
+ ID/EX +
+ Stage +
+
+
+ + + ID/EX... + + + + + + + + +
+
+
+

+ + compressed +
+ decoder + +

+
+
+
+ + + compressed... + + + + + + + +
+
+
+

+
+
+
+ + + + + + + + +
+
+
+ + prefetch + +
+ + buffer + +
+
+
+ + + prefetch... + + + + + + + +
+
+
+

+ aligner +

+

+

+
+
+
+ + + aligner... + + + + + + +
+
+
+ + Fetch FIFO + +
+
+
+ + + Fetch FIFO + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ addr_o +
+
+
+ + + addr_o + + + + + + +
+
+
+

+ rdata_o +

+
+
+
+ + + rdata_o + + + + + + + +
+
+
+ 32 +
+
+
+ + + 32 + + + + + + +
+
+
+ + IF Stage + +
+
+
+ + + IF Stage + + + + + + + + + + + + + + + + + + +
+
+
+ + CVE2 Core + +
+
+
+ + + CVE2 Core + + + + + + + +
+
+
+ jump_target_ex +
+
+
+ + + jump_target_ex + + + + + + + + + +
+
+
+ instr_rdata_id_o +
+
+
+ + + instr_rd... + + + + + + + + + + + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + \ No newline at end of file diff --git a/doc/03_reference/images/if_stage.svg b/doc/03_reference/images/if_stage.svg deleted file mode 100644 index 3c7c87f851..0000000000 --- a/doc/03_reference/images/if_stage.svg +++ /dev/null @@ -1,668 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - IF Stage - - PrefetchBuffer - - - Instruction Mem - - - addr_o - - - rdata_i - - 32 - - - CompDecoder - - - IDEX - - - Ibex Core - - - - - - - - - - - - - - - - - - - - - - FetchFIFO - jump_target_ex - - - - - - diff --git a/doc/03_reference/index.rst b/doc/03_reference/index.rst index 4a69124ab1..a1b7920b81 100644 --- a/doc/03_reference/index.rst +++ b/doc/03_reference/index.rst @@ -1,8 +1,8 @@ -Ibex Reference Guide +CVE2 Reference Guide ==================== -The Ibex Reference Guide provides background information. -It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand Ibex in depth. +The CVE2 Reference Guide provides background information. +It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand CVE2 in depth. .. toctree:: :maxdepth: 2 diff --git a/doc/03_reference/instruction_decode_execute.rst b/doc/03_reference/instruction_decode_execute.rst index 3a4ec40894..d06cfe0791 100644 --- a/doc/03_reference/instruction_decode_execute.rst +++ b/doc/03_reference/instruction_decode_execute.rst @@ -3,18 +3,19 @@ Instruction Decode and Execute ============================== -.. figure:: images/de_ex_stage.svg - :name: de_ex_stage +.. figure:: images/de_ex_stage.drawio.svg + :name: de_ex_stage.drawio.svg + :width: 100% :align: center Instruction Decode and Execute -The Instruction Decode and Execute stage takes instruction data from the instruction fetch stage (which has been converted to the uncompressed representation in the compressed instruction case). +The Instruction Decode and Execute stage takes instruction data from the :ref:`Instruction Fetch (IF) ` stage (which has been converted to the uncompressed representation in the compressed instruction case). The instructions are decoded and executed all within one cycle including the register read and write. The stage is made up of multiple sub-blocks which are described below. -Instruction Decode Block (ID) ------------------------------ +Instruction Decode Stage (ID) block +----------------------------------- Source File: :file:`rtl/cve2_id_stage.sv` The Instruction Decode (ID) controls the overall decode/execution process. @@ -38,11 +39,12 @@ Decoder ------- Source File: :file:`rtl/cve2_decoder.sv` -The decoder takes uncompressed instruction data and issues appropriate control signals to the other blocks to execute the instruction. +The Decoder takes uncompressed instruction data and issues appropriate control signals to the other blocks to execute the instruction. +It is also responsible for the offloading of extended instructions to a coprocessor through the eXtension Interface (CV-X-IF), when optionally enabled on the CV32E20X configurations. Register File ------------- -Source Files: :file:`rtl/cve2_register_file_ff.sv` :file:`rtl/cve2_register_file_fpga.sv` :file:`rtl/cve2_register_file_latch.sv` +Source File: :file:`rtl/cve2_register_file_ff.sv` See :ref:`register-file` for more details. @@ -50,7 +52,7 @@ Execute Block ------------- Source File: :file:`rtl/cve2_ex_block.sv` -The execute block contains the ALU and the multiplier/divider blocks, it does little beyond wiring and instantiating these blocks. +The Execute Block contains the ALU and the multiplier/divider blocks, it does little beyond wiring and instantiating these blocks. Arithmetic Logic Unit (ALU) --------------------------- @@ -173,9 +175,9 @@ See :ref:`load-store-unit` for more details. .. rubric:: Footnotes -.. [#B_draft] Ibex fully implements the ratified version 1.0.0 of the RISC-V Bit-Manipulation Extension including the Zba, Zbb, Zbc and Zbs sub-extensions. - In addition, Ibex also supports the remaining Zbe, Zbf, Zbp, Zbr and Zbt sub-extensions as defined in draft version 0.93 of the RISC-V Bit-Manipulation Extension. +.. [#B_draft] CVE2 fully implements the ratified version 1.0.0 of the RISC-V Bit-Manipulation Extension including the Zba, Zbb, Zbc and Zbs sub-extensions. + In addition, CVE2 also supports the remaining Zbe, Zbf, Zbp, Zbr and Zbt sub-extensions as defined in draft version 0.93 of the RISC-V Bit-Manipulation Extension. Note that the latter sub-extensions may change before being ratified as a standard by the RISC-V Foundation. - Ibex will be updated to match future versions of the specification. + CVE2 will be updated to match future versions of the specification. Prior to ratification this may involve backwards incompatible changes. Additionally, neither GCC or Clang have committed to maintaining support upstream for unratified versions of the specification. diff --git a/doc/03_reference/instruction_fetch.rst b/doc/03_reference/instruction_fetch.rst index 0d6106d7c7..5b6387b65a 100644 --- a/doc/03_reference/instruction_fetch.rst +++ b/doc/03_reference/instruction_fetch.rst @@ -4,22 +4,23 @@ Instruction Fetch ================= :file:`rtl/cve2_if_stage.sv.` -.. figure:: images/if_stage.svg +.. figure:: images/if_stage.drawio.svg :name: if_stage + :width: 100% :align: center Instruction Fetch (IF) stage -The Instruction Fetch (IF) stage of the core is able to supply one instruction to the Instruction-Decode (ID) stage per cycle if the instruction cache or the instruction memory is able to serve one instruction per cycle. +The Instruction Fetch (IF) stage of the core is able to supply one instruction to the Instruction Decode stage (ID) block, part of the Instruction Decode and Execution (ID/EX) stage :ref:`Instruction Decode and Execution (ID/EX)`, per cycle if the instruction cache or the instruction memory is able to serve one instruction per cycle. Instructions are fetched into a prefetch buffer (:file:`rtl/cve2_prefetch_buffer.sv`) for optimal performance and timing closure reasons. This buffer simply fetches instructions linearly until it is full. -The instructions themselves are stored along with the Program Counter (PC) they came from in the fetch FIFO (:file:`rtl/cve2_fetch_fifo.sv`). -The fetch FIFO has a feedthrough path so when empty a new instruction entering the FIFO is immediately made available on the FIFO output. +The instructions themselves are stored along with the Program Counter (PC) in the fetch FIFO (:file:`rtl/cve2_fetch_fifo.sv`). +The fetch FIFO has a feedthrough path so, when empty, a new instruction entering the FIFO is immediately made available on the FIFO output. A localparam ``DEPTH`` gives a configurable depth which is set to 3 by default. The top-level of the instruction fetch controls the prefetch buffer (in particular flushing it on branches/jumps/exception and beginning prefetching from the appropriate new PC) and supplies new instructions to the ID/EX stage along with their PC. -Compressed instructions are expanded by the IF stage so the decoder can always deal with uncompressed instructions (the ID stage still receives the compressed instruction for placing into ``mtval`` on an illegal instruction exception). +Compressed instructions are expanded by the IF stage, so the decoder can always deal with uncompressed instructions (the ID block still receives the compressed instruction for placing into ``mtval`` on an illegal instruction exception). Instruction-Side Memory Interface --------------------------------- @@ -48,8 +49,6 @@ The main difference is that the instruction interface does not allow for write t +-----------------------------+-----------+-----------------------------------------------+ | ``instr_rdata_i[31:0]`` | input | Data read from memory | +-----------------------------+-----------+-----------------------------------------------+ -| ``instr_rdata_intg_i[6:0]`` | input | Data integrity bits from memory | -+-----------------------------+-----------+-----------------------------------------------+ | ``instr_err_i`` | input | Memory access error | +-----------------------------+-----------+-----------------------------------------------+ @@ -66,6 +65,6 @@ The LSB of the instruction address is ignored internally. Protocol -------- -The protocol used to communicate with the instruction cache or the instruction memory is very similar to the protocol used by the LSU on the data interface of Ibex. +The protocol used to communicate with the instruction cache or the instruction memory is very similar to the protocol used by the LSU on the data interface of CVE2. See the description of the LSU in :ref:`LSU Protocol` for details about this protocol. diff --git a/doc/03_reference/load_store_unit.rst b/doc/03_reference/load_store_unit.rst index c9eb6c9e1a..5fbdf48af2 100644 --- a/doc/03_reference/load_store_unit.rst +++ b/doc/03_reference/load_store_unit.rst @@ -31,10 +31,6 @@ Signals that are used by the LSU: | ``data_wdata_o[31:0]`` | output | Data to be written to memory, sent together | | | | with ``data_req_o`` | +----------------------------+-----------+-----------------------------------------------+ -| ``data_wdata_intg_o[6:0]`` | output | Integrity bits to be written to memory, sent | -| | | together with ``data_req_o`` (not used unless | -| | | the SecureIbex parameter is set) | -+----------------------------+-----------+-----------------------------------------------+ | ``data_gnt_i`` | input | The other side accepted the request. | | | | Outputs may change in the next cycle. | +----------------------------+-----------+-----------------------------------------------+ @@ -49,20 +45,17 @@ Signals that are used by the LSU: +----------------------------+-----------+-----------------------------------------------+ | ``data_rdata_i[31:0]`` | input | Data read from memory | +----------------------------+-----------+-----------------------------------------------+ -| ``data_rdata_intg_i[6:0]`` | input | Integrity bits read from memory (ignored | -| | | unless the SecureIbex parameter is set) | -+----------------------------+-----------+-----------------------------------------------+ -Bus Integrity Checking ----------------------- +.. Bus Integrity Checking +.. ---------------------- -The core can optionally generate and verify check bits sent alongside the data for memory accesses. -Checkbits are generated and checked using an inverted 39/32 Hsaio code (see :file:`vendor/lowrisc_ip/ip/prim/rtl/prim_secded_inv_39_32_enc.sv`). -When this feature is used, any mismatch in checkbits will generate a major alert. +.. The core can optionally generate and verify check bits sent alongside the data for memory accesses. +.. Checkbits are generated and checked using an inverted 39/32 Hsaio code (see :file:`vendor/lowrisc_ip/ip/prim/rtl/prim_secded_inv_39_32_enc.sv`). +.. When this feature is used, any mismatch in checkbits will generate a major alert. -This feature is only used if the core is configured with the SecureIbex parameter set. -For all other configurations, the integrity signals can be ignored. +.. This feature is only used if the core is configured with the SecureIbex parameter set. +.. For all other configurations, the integrity signals can be ignored. Misaligned Accesses ------------------- diff --git a/doc/03_reference/performance_counters.rst b/doc/03_reference/performance_counters.rst index a6ab32543f..0ecb0e0915 100644 --- a/doc/03_reference/performance_counters.rst +++ b/doc/03_reference/performance_counters.rst @@ -3,17 +3,17 @@ Performance Counters ==================== -Ibex implements performance counters according to the RISC-V Privileged Specification, version 1.11 (see Hardware Performance Monitor, Section 3.1.11). +CVE2 implements performance counters according to the RISC-V Privileged Specification, version 1.11 (see Hardware Performance Monitor, Section 3.1.11). The performance counters are placed inside the Control and Status Registers (CSRs) and can be accessed with the ``CSRRW(I)`` and ``CSRRS/C(I)`` instructions. -Ibex implements the clock cycle counter ``mcycle(h)``, the retired instruction counter ``minstret(h)``, as well as the 29 event counters ``mhpmcounter3(h)`` - ``mhpmcounter31(h)`` and the corresponding event selector CSRs ``mhpmevent3`` - ``mhpmevent31``, and the ``mcountinhibit`` CSR to individually enable/disable the counters. +CVE2 implements the clock cycle counter ``mcycle(h)``, the retired instruction counter ``minstret(h)``, as well as the 29 event counters ``mhpmcounter3(h)`` - ``mhpmcounter31(h)`` and the corresponding event selector CSRs ``mhpmevent3`` - ``mhpmevent31``, and the ``mcountinhibit`` CSR to individually enable/disable the counters. ``mcycle(h)`` and ``minstret(h)`` are always available and 64 bit wide. The ``mhpmcounter`` performance counters are optional (unavailable by default) and parametrizable in width. Event Selector -------------- -The following events can be monitored using the performance counters of Ibex. +The following events can be monitored using the performance counters of CVE2. +--------------+------------------+---------------------------------------------------------+ | Event ID/Bit | Event Name | Event Description | @@ -68,10 +68,9 @@ The ``mcycle(h)`` and ``minstret(h)`` counters are always available and 64 bit w The event counters ``mhpmcounter3(h)`` - ``mhpmcounter31(h)`` are parametrizable. Their width can be parametrized between 1 and 64 bit through the ``WidthMHPMCounters`` parameter, which defaults to 40 bit wide counters. -The number of available event counters ``mhpmcounterX(h)`` can be controlled via the ``NumMHPMCounters`` parameter. -By default (``NumMHPMCounters`` set to 0), no counters are available to software. -Set ``NumMHPMCounters`` to a value between 1 and 8 to make the counters ``mhpmcounter3(h)`` - ``mhpmcounter10(h)`` available as listed below. -Setting ``NumMHPMCounters`` to values larger than 8 does not result in any more performance counters. +The number of available event counters ``mhpmcounterX(h)`` can be controlled via the ``MHPMCounterNum``, set to 10 by default. +Set ``MHPMCounterNum`` to a value between 1 and 10 to make the counters ``mhpmcounter3(h)`` - ``mhpmcounter12(h)`` available as listed below. +Setting ``MHPMCounterNum`` to values larger than 10 does not result in any more performance counters. Unavailable counters always read 0. diff --git a/doc/03_reference/pipeline_details.rst b/doc/03_reference/pipeline_details.rst index 389e81fcee..2606ffe79e 100644 --- a/doc/03_reference/pipeline_details.rst +++ b/doc/03_reference/pipeline_details.rst @@ -1,33 +1,38 @@ .. _pipeline-details: -.. figure:: images/blockdiagram.svg - :name: ibex-pipeline +.. figure:: images/blockdiagram.drawio.svg + :name: cve2-pipeline + :width: 100% :align: center - Ibex Pipeline + CVE2 Pipeline Pipeline Details ================ -Ibex has a 2-stage pipeline, the 2 stages are: +CVE2 has a 2-stage pipeline, the 2 stages are: Instruction Fetch (IF) - Fetches instructions from memory via a prefetch buffer, capable of fetching 1 instruction per cycle if the instruction side memory system allows. See :ref:`instruction-fetch` for details. + Represented in light yellow in :numref:`cve2-pipeline`, it Fetches instructions from memory via a prefetch buffer, capable of fetching 1 instruction per cycle if the instruction side memory system allows. See :ref:`instruction-fetch` for details. Instruction Decode and Execute (ID/EX) - Decodes fetched instruction and immediately executes it, register read and write all occurs in this stage. - Multi-cycle instructions will stall this stage until they are complete See :ref:`instruction-decode-execute` for details. + Represented in light blue in :numref:`cve2-pipeline`, it decodes fetched instruction and immediately executes it, register read and write all occurs in this stage. + Multi-cycle instructions will stall this stage until they are complete. See :ref:`instruction-decode-execute` for details. All instructions require two cycles minimum to pass down the pipeline. One cycle in the IF stage and one in the ID/EX stage. Not all instructions can complete in the ID/EX stage in one cycle so will stall there until they complete. -This means the maximum IPC (Instructions per Cycle) Ibex can achieve is 1 when multi-cycle instructions aren't used. +This means the maximum IPC (Instructions per Cycle) CVE2 can achieve is 1 when multi-cycle instructions aren't used. See Multi- and Single-Cycle Instructions below for the details. -Third Pipeline Stage --------------------- -Ibex can be configured to have a third pipeline stage (Writeback) which has major effects on performance and instruction behaviour. -This feature is *EXPERIMENTAL* and the details of its impact are not yet documented here. -All of the information presented below applies only to the two stage pipeline provided in the default configurations. +.. TODO there is no third-pipeline stage (cve2_wb.sv) implemented on the current version code. I substituted the text below for a note +.. Third Pipeline Stage +.. -------------------- +.. CVE2 can be configured to have a third pipeline stage (Writeback) which has major effects on performance and instruction behaviour. +.. This feature is *EXPERIMENTAL* and the details of its impact are not yet documented here. +.. All of the information presented below applies only to the two stage pipeline provided in the default configurations. + +.. note:: + An optional third pipeline stage is planned to be implemented on the block Writeback (file :file:`rtl/cve2_wb.sv`). Currently it implements the default write-through mode. It is represented in light purple in :numref:`cve2-pipeline`. Multi- and Single-Cycle Instructions ------------------------------------ diff --git a/doc/03_reference/pmp.rst b/doc/03_reference/pmp.rst index d53794ef70..3029bcd706 100644 --- a/doc/03_reference/pmp.rst +++ b/doc/03_reference/pmp.rst @@ -3,7 +3,7 @@ Physical Memory Protection (PMP) ================================ -The Physical Memory Protection (PMP) unit implements region-based memory access checking in-accordance with the RISC-V Privileged Specification, version 1.11 and includes the Trusted Execution Environment (TEE) working group proposal `PMP Enhancements for memory access and execution prevention on Machine mode (Smepmp) version 0.9.3 `_. +The Physical Memory Protection (PMP) unit is a `potential future design enhancement on the CVE2 `_ that implements region-based memory access checking in-accordance with the RISC-V Privileged Specification, version 1.11, and includes the Trusted Execution Environment (TEE) working group proposal `PMP Enhancements for memory access and execution prevention on Machine mode (Smepmp) version 0.9.3 `_. The following local parameters are available to control PMP checking: +----------------+---------------+----------------------------------------------------------+ @@ -37,7 +37,7 @@ PMP Enhancements ---------------- These are described in more detail in `PMP Enhancements for memory access and execution prevention on Machine mode (Smepmp) version 0.9.3 `_. -If Ibex is configured to include PMP (PMPEnable is not zero) the PMP enhancements are always included. +If CVE2 is configured to include PMP (PMPEnable is not zero) the PMP enhancements are always included. Use of the enhanced behavior is optional, if no writes to ``mseccfg`` occur PMP behavior will remain exactly as specified in the RISC-V privileged specification. The enhancements add: diff --git a/doc/03_reference/rvfi.rst b/doc/03_reference/rvfi.rst index 066fd29c4a..5b9d5e99cf 100644 --- a/doc/03_reference/rvfi.rst +++ b/doc/03_reference/rvfi.rst @@ -3,7 +3,7 @@ RISC-V Formal Interface ======================= -Ibex supports the `RISC-V Formal Interface (RVFI) `_. +CVE2 supports the `RISC-V Formal Interface (RVFI) `_. This interface basically decodes the current instruction and provides additional insight into the core state thereby enabling formal verification. Examples of such information include opcode, source and destination registers, program counter, as well as address and data for memory operations. @@ -11,8 +11,8 @@ Examples of such information include opcode, source and destination registers, p Formal Verification ------------------- -The signals provided by RVFI can be used to formally verify compliance of Ibex with the `RISC-V specification `_. +The signals provided by RVFI can be used to formally verify compliance of CVE2 with the `RISC-V specification `_. -Currently, the implementation is restricted to support the "I" and "C" extensions, and Ibex is not yet formally verified. +Currently, the implementation is restricted to support the "I" and "C" extensions, and CVE2 is not yet formally verified. It predecessor "Zero-riscy" had been tested, but this required changes to the core as well as to the tool used in the process (`yosys `_). -The formal verification of the Ibex core is work in progress. +The formal verification of the CVE2 core is work in progress. diff --git a/doc/03_reference/testplan.rst b/doc/03_reference/testplan.rst index 4430994b68..40646f8a26 100644 --- a/doc/03_reference/testplan.rst +++ b/doc/03_reference/testplan.rst @@ -2,103 +2,106 @@ .. note:: - This testplan is a work in progress still being implemented so this document may not match the implemented verification in the repository. - -Test Plan -========= - -Goals ------ - -* Verify compliance with all the RISC-V specifications CVE2 supports. -* Ensure correct functionality is maintained across all possible behaviours of external interfaces (interrupts, memory responses, debug requests etc). -* Hit all functional coverage points, described in :ref:`coverage-plan`. - -Testbench Architecture ----------------------- - -.. figure:: images/tb2.svg - :alt: Testbench Architecture - - Architecture of the UVM testbench for Ibex core - -Ibex utilises a co-simulation checking approach described in detail in :ref:`cosim`. -With the co-simulation system all instructions Ibex executes and all external events such as an interrupts or memory errors are fed to a golden model. -The results of every instruction execution and every memory access are crossed checked against the golden model with any mismatches resulting in a test failure. -The aim is to check all possible externally observable behaviours of ``cve2_top`` against the golden model. -The golden model used is the `Spike RISC-V ISS `_. - -The testbench uses UVM. -It consists of 3 agents: - -Co-simulation Agent: - This has multiple monitors. - One monitors the RVFI interface which provides details of retired instructions. - The other monitors relate to fetched instructions and instruction memory errors; more details are provided in :ref:`coverage-plan`. - Additionally it connects to the monitor of the Memory Interface Agent for the instruction and data side via analysis ports. - The monitored transactions are used by a scoreboard to provide information to the co-simulation system allowing it to step the golden model and check its execution and memory activity against Ibex's behaviour. - -Memory Interface Agent - This provides a driver and a monitor for the :ref:`Ibex Memory Interface Protocol`. - The driver provides fully randomised and configurable timings for responses and randomisation of error responses. - Two agents are instantiated; one for the data memory interface the other for the instruction memory interface. - Read data for memory responses is provided from a backing memory; write requests update the contents of the backing memory. - This is separate from the memory used by the golden model in the co-simulation agent. - The contents of these two memories will be identical unless there is a mismatch resulting in a failure. - The backing memory is held in a memory model as a separate UVM component. - The two agents use the same backing memory so they have a coherent view of memory. - -IRQ Agent - This provides a driver and a monitor for the IRQ interface. - It provides randomised interrupt stimulus to Ibex when a test requests it. - Constraints can be used to control types of interrupts generated (e.g. NMI or not) and whether multiple interrupts should be raised together. - -Debug and reset signals are a single wire each so do not have a dedicated agent. -Instead any sequence that wishes to use them will directly manipulate them via a virtual interface - -The testbench instantiates the agents described above along with the memory model used by both the data and instruction side memory agents. -A test consists of executing a pre-built binary (which is loaded into the memory model at the start of the test via backdoor accesses) along with configuring agents to provide appropriate stimulus for the test. -Some tests may use the agents to generate stimulus at particular times (e.g. interrupts). -A test may perform additional checking on top of the co-simulation golden model comparison where appropriate (e.g. ensuring a raised interrupt has caused an exception). - -Stimulus Strategy ------------------ - -Stimulus falls into two categories: - -* Instructions to execute: These are generated by the `RISC-V DV random instruction `_ generator and provided to the testbench via a raw binary file. -* Activity on external interfaces. - -Instructions are generated ahead of time so the test has no control over them at run time. -All external interfaces have their stimulus generated at run time so can be controlled by the test. -It is the responsibility of the regression run environment to ensure generated instructions are matched with appropriate tests (e.g. ensuring an exception handler is present where interrupts are expected). - -Stimulus generation will use a coverage based approach. -Stimulus is developed based upon the :ref:`coverage-plan`. -Where coverage is not being hit stimulus will be added to hit it. - -Tests ------ - -As with stimulus, test sequence development uses a coverage based approach. -Tests will be added such that all coverage in the :ref:`coverage-plan` can be hit. -Not all the details of specific tests will be documented here. -The test list (`dv/uvm/core_cve2/riscv_dv_extension/testlist.yaml `_), provides an exhaustive list of all tests along with a brief description of what the test does. - -A test will execute a binary whilst running zero or more sequences that provide stimulus to external interfaces of ``cve2_top``. -As the memory interfaces are all driven by Ibex, with any testbench generated activity in response to a request from Ibex, they do not require explicit sequences run by the test. -Instead the test can configure the randomisation of memory delays as it wishes. -Memory errors can be configured to always occur in statically defined areas of the memory map or a sequence can be used to inject them via the memory interface agent. - -The following sequences are available for tests to use. -Each sequence is derived from a base sequence which provides controls to repeat the sequence at fixed or random internals, forever or after a random number of repeats. -Full details can be found in `dv/uvm/core_cve2/tests/core_cve2_seq_lib.sv `_. - -* ``irq_raise_seq`` - Raises one or more interrupts. - The testbench binary can write to a special memory location to acknowledge the interrupt and cause it to drop. - Alternatively the testbench can drop it after a given amount of time. -* ``debug_seq`` - Raises the external debug request. - The testbench binary can write to a special memory location to acknowledge the request and cause it to drop. - Alternatively the testbench can drop it after a given amount of time. -* ``mem_error_seq`` - Injects a memory error in either the instruction side or data side, so the next access results in an error response. -* ``reset_seq`` - Resets the core. + This testplan is a work in progress still being implemented, so this document may not match the implemented verification in the repository. + .. TODO This needs to be updated following https://github.com/openhwgroup/cve2/issues/281 + + +.. Test Plan +.. ========= + +.. Goals +.. ----- + +.. * Verify compliance with all the RISC-V specifications CVE2 supports. +.. * Ensure correct functionality is maintained across all possible behaviours of external interfaces (interrupts, memory responses, debug requests etc). +.. * Hit all functional coverage points, described in :ref:`coverage-plan`. + +.. Testbench Architecture +.. ---------------------- + +.. .. figure:: images/tb2.svg +.. :alt: Testbench Architecture + +.. Architecture of the UVM testbench for CVE2 core + +.. CVE2 utilises a co-simulation checking approach described in detail in :ref:`cosim`. +.. With the co-simulation system all instructions CVE2 executes and all external events such as an interrupts or memory errors are fed to a golden model. +.. The results of every instruction execution and every memory access are crossed checked against the golden model with any mismatches resulting in a test failure. +.. The aim is to check all possible externally observable behaviours of ``cve2_top`` against the golden model. +.. The golden model used is the `Spike RISC-V ISS `_. + +.. The testbench uses UVM. +.. It consists of 3 agents: + +.. Co-simulation Agent: +.. This has multiple monitors. +.. One monitors the RVFI interface which provides details of retired instructions. +.. The other monitors relate to fetched instructions and instruction memory errors; more details are provided in :ref:`coverage-plan`. +.. Additionally, it connects to the monitor of the Memory Interface Agent for the instruction and data side via analysis ports. +.. The monitored transactions are used by a scoreboard to provide information to the co-simulation system allowing it to step the golden model and check its execution and memory activity against CVE2's behaviour. + +.. Memory Interface Agent +.. This provides a driver and a monitor for the :ref:`CVE2 Memory Interface Protocol`. +.. The driver provides fully randomised and configurable timings for responses and randomisation of error responses. +.. Two agents are instantiated; one for the data memory interface the other for the instruction memory interface. +.. Read data for memory responses is provided from a backing memory; write requests update the contents of the backing memory. +.. This is separate from the memory used by the golden model in the co-simulation agent. +.. The contents of these two memories will be identical unless there is a mismatch resulting in a failure. +.. The backing memory is held in a memory model as a separate UVM component. +.. The two agents use the same backing memory, so they have a coherent view of memory. + +.. IRQ Agent +.. This provides a driver and a monitor for the IRQ interface. +.. It provides randomised interrupt stimulus to CVE2 when a test requests it. +.. Constraints can be used to control types of interrupts generated (e.g. NMI or not) and whether multiple interrupts should be raised together. + +.. Debug and reset signals are a single wire each so do not have a dedicated agent. +.. Instead, any sequence that wishes to use them will directly manipulate them via a virtual interface + +.. The testbench instantiates the agents described above along with the memory model used by both the data and instruction side memory agents. +.. A test consists of executing a pre-built binary (which is loaded into the memory model at the start of the test via backdoor accesses) along with configuring agents to provide appropriate stimulus for the test. +.. Some tests may use the agents to generate stimulus at particular times (e.g. interrupts). +.. A test may perform additional checking on top of the co-simulation golden model comparison where appropriate (e.g. ensuring a raised interrupt has caused an exception). + +.. Stimulus Strategy +.. ----------------- + +.. Stimulus falls into two categories: + +.. * Instructions to execute: These are generated by the `RISC-V DV random instruction `_ generator and provided to the testbench via a raw binary file. +.. * Activity on external interfaces. + +.. Instructions are generated ahead of time, so the test has no control over them at run time. +.. All external interfaces have their stimulus generated at run time so can be controlled by the test. +.. It is the responsibility of the regression run environment to ensure generated instructions are matched with appropriate tests (e.g. ensuring an exception handler is present where interrupts are expected). + +.. Stimulus generation will use a coverage based approach. +.. Stimulus is developed based upon the :ref:`coverage-plan`. +.. Where coverage is not being hit stimulus will be added to hit it. + +.. TODO adapt it to CVE2 +.. Tests +.. ----- + +.. As with stimulus, test sequence development uses a coverage based approach. +.. Tests will be added such that all coverage in the :ref:`coverage-plan` can be hit. +.. Not all the details of specific tests will be documented here. +.. The test list (`dv/uvm/core_cve2/riscv_dv_extension/testlist.yaml `_), provides an exhaustive list of all tests along with a brief description of what the test does. + +.. A test will execute a binary whilst running zero or more sequences that provide stimulus to external interfaces of ``cve2_top``. +.. As the memory interfaces are all driven by Ibex, with any testbench generated activity in response to a request from Ibex, they do not require explicit sequences run by the test. +.. Instead the test can configure the randomisation of memory delays as it wishes. +.. Memory errors can be configured to always occur in statically defined areas of the memory map or a sequence can be used to inject them via the memory interface agent. + +.. The following sequences are available for tests to use. +.. Each sequence is derived from a base sequence which provides controls to repeat the sequence at fixed or random internals, forever or after a random number of repeats. +.. Full details can be found in `dv/uvm/core_cve2/tests/core_cve2_seq_lib.sv `_. + +.. * ``irq_raise_seq`` - Raises one or more interrupts. +.. The testbench binary can write to a special memory location to acknowledge the interrupt and cause it to drop. +.. Alternatively the testbench can drop it after a given amount of time. +.. * ``debug_seq`` - Raises the external debug request. +.. The testbench binary can write to a special memory location to acknowledge the request and cause it to drop. +.. Alternatively the testbench can drop it after a given amount of time. +.. * ``mem_error_seq`` - Injects a memory error in either the instruction side or data side, so the next access results in an error response. +.. * ``reset_seq`` - Resets the core. diff --git a/doc/03_reference/verification.rst b/doc/03_reference/verification.rst index 6cd2a74d3d..2793db6f8b 100644 --- a/doc/03_reference/verification.rst +++ b/doc/03_reference/verification.rst @@ -5,261 +5,10 @@ Verification This section needs to be split into a HOWTO-style user/developer guide, and reference information on the testbench structure. -Ibex Core +CVE2 Core --------- Overview ^^^^^^^^ -This is a SV/UVM testbench for verification of the Ibex core, located in `dv/uvm/core_cve2`. -At a high level, this testbench uses the open source `RISCV-DV random instruction generator -`_ to generate compiled instruction binaries, loads them into a -simple memory model, stimulates the Ibex core to run this program in memory, and then compares the -core trace log against a golden model ISS trace log to check for correctness of execution. - -Testbench Architecture -^^^^^^^^^^^^^^^^^^^^^^ - -As previously mentioned, this testbench has been constructed based on its usage of the RISCV-DV -random instruction generator developed by Google. -A block diagram of the testbench is below. - -.. figure:: images/tb.svg - :alt: Testbench Architecture - - Architecture of the UVM testbench for Ibex core - -Memory Interface Agents -""""""""""""""""""""""" - -The code can be found in the `dv/uvm/core_cve2/common/cve2_mem_intf_agent -`_ directory. -Two of these agents are instantiated within the testbench, one for the instruction fetch interface, -and the second for the LSU interface. -These agents run slave sequences that wait for memory requests from the core, and then grant the -requests for instructions or for data. - -Interrupt Interface Agent -""""""""""""""""""""""""" - -The code can be found in the -`dv/uvm/core_cve2/common/irq_agent `_ directory. -This agent is used to drive stimulus onto the Ibex core's interrupt pins randomly during test -execution. - -Memory Model -"""""""""""" - -The code is vendored from OpenTitan and can be found in the -`vendor/lowrisc_ip/dv/sv/mem_model `_ -directory. -The testbench instantiates a single instance of this memory model that it loads the compiled -assembly test program into at the beginning of each test. -This acts as a unified instruction/data memory that serves all requests from both of the -memory interface agents. - -Test and Sequence Library -""""""""""""""""""""""""" - -The code can be found in the -`dv/uvm/core_cve2/tests `_ directory. -The tests here are the main sources of external stimulus generation and checking for this testbench, -as the memory interface slave sequences simply serve the core's memory requests. -The tests here are all extended from ``core_cve2_base_test``, and coordinate the entire flow for a -single test, from loading the compiled assembly binary program into the testbench memory model, to -checking the Ibex core status during the test and dealing with test timeouts. -The sequences here are used to drive interrupt and debug stimulus into the core. - -Testplan -"""""""" - -The goal of this bench is to fully verify the Ibex core with 100% -coverage. This includes testing all RV32IMCB instructions, privileged -spec compliance, exception and interrupt testing, Debug Mode operation etc. -The complete test list can be found in the file `dv/uvm/core_cve2/riscv_dv_extension/testlist.yaml -`_. -For details on coverage see the :ref:`coverage-plan`. - -Please note that verification is still a work in progress. - -Getting Started -^^^^^^^^^^^^^^^ - -Prerequisites & Environment Setup -""""""""""""""""""""""""""""""""" - -In order to run the co-simulation flow, you'll need: - -- A SystemVerilog simulator that supports UVM. - - The flow is currently tested with VCS. - -- The Spike RISC-V instruction set simulator - - Spike must be built with the ``--enable-commitlog`` and ``--enable-misaligned`` options. - ``--enable-commitlog`` is needed to produce log output to track the instructions that were executed. - ``--enable-misaligned`` tells Spike to simulate a core that handles misaligned accesses in hardware (rather than jumping to a trap handler). - - Ibex supports v.1.0.0 of the RISC-V Bit-Manipulation Extension together with the remaining sub-extensions of draft v.0.93 of the bitmanip spec. - lowRISC maintains a `lowRISC-specific branch of Spike `_ that matches the supported Bitmanip specification plus some custom CSRs. - This branch must also be used in order to to simulate the core with the Icache enabled. - - Note that Ibex used to support the commercial OVPsim simulator. - This is not currently possble because OVPsim doesn't support the co-simulation approach that we use. - -- A working RISC-V toolchain (to compile / assemble the generated programs before simulating them). - - Either download a `pre-built toolchain `_ (quicker) or download and build the `RISC-V GNU compiler toolchain `_. - For the latter, the Bitmanip patches have to be manually installed to enable support for the Bitmanip draft extension. - For further information, checkout the `Bitmanip Extension on GitHub `_ and `how we create the pre-built toolchains `_. - -Once these are installed, you need to set some environment variables -to tell the RISCV-DV code where to find them: - -:: - - export RISCV_TOOLCHAIN=/path/to/riscv - export RISCV_GCC="$RISCV_TOOLCHAIN/bin/riscv32-unknown-elf-gcc" - export RISCV_OBJCOPY="$RISCV_TOOLCHAIN/bin/riscv32-unknown-elf-objcopy" - export SPIKE_PATH=/path/to/spike/bin - -.. _LRSpike: https://github.com/lowRISC/riscv-isa-sim/tree/cve2_cosim -.. _riscv-toolchain-source: https://github.com/riscv/riscv-gnu-toolchain -.. _riscv-toolchain-releases: https://github.com/lowRISC/lowrisc-toolchains/releases -.. _bitmanip-patches: https://github.com/lowRISC/lowrisc-toolchains#how-to-generate-the-bitmanip-patches -.. _bitmanip: https://github.com/riscv/riscv-bitmanip - -End-to-end RTL/ISS co-simulation flow -""""""""""""""""""""""""""""""""""""" - -.. figure:: images/dv-flow.png - :alt: RTL/ISS co-simulation flow chart - - RTL/ISS co-simulation flow chart - -The last stage in this flow handles log comparisons to determine correctness of a given simulation. -To do this, both the trace log produced by the core and the trace log produced by the chosen golden -model ISS are parsed to collect information about all register writebacks that occur. -These two sets of register writeback data are then compared to verify that the core is writing the -correct data to the correct registers in the correct order. - -However, this checking model quickly falls apart once situations involving external stimulus (such -as interrupts and debug requests) start being tested, as while ISS models can simulate traps due to -exceptions, they cannot model traps due to external stimulus. -In order to provide support for these sorts of scenarios to verify if the core has entered the -proper interrupt handler, entered Debug Mode properly, updated any CSRs correctly, and so on, the -handshaking mechanism provided by the RISCV-DV instruction generator is heavily used, which -effectively allows the core to send status information to the testbench during program execution for -any analysis that is required to increase verification effectiveness. -This mechanism is explained in detail at https://github.com/google/riscv-dv/blob/master/HANDSHAKE.md. -As a sidenote, the signature address that this testbench uses for the handshaking is ``0x8ffffffc``. -Additionally, as is mentioned in the RISCV-DV documentation of this handshake, a small set of API -tasks are provided in `dv/uvm/core_cve2/tests/core_cve2_base_test.sv -`_ to enable easy -and efficient integration and usage of this mechanism in this test environment. -To see how this handshake is used during real simulations, look in -`dv/uvm/core_cve2/tests/core_cve2_test_lib.sv -`_. -As can be seen, this mechanism is extensively used to provide runtime verification for situations involving external debug -requests, interrupt assertions, and memory faults. -To add another layer of correctness checking to the checking already provided by the handshake -mechanism, a modified version of the trace log comparison is used, as comparing every register write -performed during the entire simulation will lead to an incorrect result since the ISS trace log will -not contain any execution information in the debug ROM or in any interrupt handler code. -As a result, only the final values contained in every register at the end of the test are compared -against each other, since any code executed in the debug ROM and trap handlers should not corrupt -register state in the rest of the program. - -The entirety of this flow is controlled by the Makefile found at -`dv/uvm/core_cve2/Makefile `_; here is a list of frequently used commands: - -.. code-block:: bash - - cd dv/uvm/core_cve2 - - # Run a full regression - make - - # Run a full regression, redirect the output directory - make OUT=xxx - - # Run a single test - make TEST=riscv_machine_mode_rand_test ITERATIONS=1 - - # Run a test with a specific seed, dump waveform - make TEST=riscv_machine_mode_rand_test ITERATIONS=1 SEED=123 WAVES=1 - - # Verbose logging - make ... VERBOSE=1 - - # Run multiple tests in parallel through LSF - make ... LSF_CMD="bsub -Is" - - # Get command reference of the simulation script - python3 sim.py --help - - # Generate the assembly tests only - make gen - - # Pass addtional options to the generator - make GEN_OPTS="xxxx" ... - - # Compile and run RTL simulation - make TEST=xxx compile,rtl_sim - - # Use a different ISS (default is spike) - make ... ISS=ovpsim - - # Run a full regression with coverage - make COV=1 - -Run with a different RTL simulator -"""""""""""""""""""""""""""""""""" - -You can add any compile/runtime options in `dv/uvm/core_cve2/yaml/simulator.yaml -`_. - -.. code-block:: bash - - # Use the new RTL simulator to run - make ... SIMULATOR=xxx - - -Instruction Cache ------------------ - -Overview -^^^^^^^^ - -Due to the complexity of the instruction cache, a separate testbench is used to -ensure that full verification and coverage closure is performed on this module. -This testbench is located at `dv/uvm/icache/dv -`_. - -As Icache verification is being carried out as part of the OpenTitan open-source -project, the testbench derives from the `dv_lib UVM class library -`_, which is a set of extended UVM -classes that provides basic UVM testbench functionality and components. - -This DV environment will be compiled and simulated using the `dvsim simulation tool -`_. -The master ``.hjson`` file that controls simulation with ``dvsim`` can be found -at `dv/uvm/icache/dv/cve2_icache_sim_cfg.hjson -`_. -The associated testplan ``.hjson`` file is located at `dv/uvm/icache/data/cve2_icache_testplan.hjson -`_. -As this testbench is still in its infancy, it is currently only able to be compiled, as no tests or -sequences are implemented, nor are there any entries in the testplan file. -To build the testbench locally using the VCS simulator, run the following command from the root of -the Ibex repository: - -.. code-block:: bash - - ./vendor/lowrisc_ip/util/dvsim/dvsim.py dv/uvm/icache/dv/cve2_icache_sim_cfg.hjson --build-only - --skip-ral --purge --sr sim_out - -Specify the intended output directory using either the ``--sr`` or ``-scratch-root`` option. -The ``--skip-ral`` option is mandatory for building/simulating the Icache testbench, as it does not -have any CSRs, excluding this option will lead to build errors. -``--purge`` directs the tool to ``rm -rf`` the output directory before running the tool, this can be -removed if not desired. +The SV/UVM testbench and verification environment for the CVE2 core is still under development. It is available under the `dev branch `_ of the `cv32e20-dv project `_, the specific code for the `CORE-V-VERIF `_ environment. \ No newline at end of file diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index e585e1a12d..b0c3c68978 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -1,3 +1,21 @@ .no-scrollbar-table td { white-space: normal !important; } + + +table.docutils.align-default { + width: 100%; + /* table-layout: fixed; */ +} + +/* table.docutils.align-default td, +table.docutils.align-default th { + word-wrap: break-word; + white-space: normal; +} */ + +table.docutils.align-default td:last-child, +table.docutils.align-default th:last-child { + word-wrap: break-word; + white-space: normal; +} diff --git a/doc/conf.py b/doc/conf.py index e8126d4052..48ac7b007a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# Copyright (c) 2020, 2023 OpenHW Group +# Copyright (c) 2020, 2023 OpenHW Foundation # # Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -38,8 +38,8 @@ # -- Project information ----------------------------------------------------- project = 'CV32E20 Documentation' -copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-2022 lowRISC, 2022-2023 OpenHW Group' -author = 'OpenHW Group' +copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-2022 lowRISC, 2022-2025 OpenHW Foundation' +author = 'OpenHW Foundation' # The short X.Y version version = u'0.1' @@ -165,7 +165,7 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'CV32E20_Documentation.tex', u'CV32E20 Documentation', - u'OpenHW Group', 'manual'), + u'OpenHW Foundation', 'manual'), ] diff --git a/doc/index.rst b/doc/index.rst index a540d4dd5a..8b81307136 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,8 +1,8 @@ CV32E20: An embedded 32-bit RISC-V CPU core =========================================== -CV32E20 is a production-quality open source 32-bit RISC-V CPU core written in SystemVerilog. -The CPU core is based on the Ibex core, but simplified and verified under the OpenHW Group. +CV32E20 is a specific configuration of the CVE2 and is a production-quality open source 32-bit RISC-V CPU core written in SystemVerilog. +The CVE2 is based on the lowRISC Ibex core, but simplified and (re) verified by the OpenHW Foundation. You are now reading the CV32E20 documentation. The documentation is split into multiple parts. @@ -10,13 +10,13 @@ The documentation is split into multiple parts. The :doc:`Technical Specification <01_specification/index>` contains the technical specification of CV32E20. It defines the supported features in the form of requirements. -The remaining parts of documentation are inherited from the Ibex project. They are kept for reference and will be reworked in the future. +The remaining parts of documentation are inherited from the CVE2 project. They are kept for reference and will be reworked in the future. -The :doc:`User Guide <02_user/index>` provides all necessary information to use Ibex. -It is aimed at hardware developers integrating Ibex into a design, and software developers writing software running on Ibex. +The :doc:`User Guide <02_user/index>` provides all necessary information to use CVE2. +It is aimed at hardware developers integrating CVE2 into a design, and software developers writing software running on CVE2. The :doc:`Reference Guide <03_reference/index>` provides background information. -It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand Ibex in depth. +It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand CVE2 in depth. .. toctree:: :maxdepth: 3 diff --git a/scripts/sec/sec.sh b/scripts/sec/sec.sh index 9c2ce8d4e4..7126df4fb5 100755 --- a/scripts/sec/sec.sh +++ b/scripts/sec/sec.sh @@ -1,6 +1,6 @@ #!/bin/bash -# Copyright 2023 OpenHW Group +# Copyright 2023-2025 OpenHW Foundation # # Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/scripts/sec/yosys/sec.eqy b/scripts/sec/yosys/sec.eqy index 102ea0f60a..e9346d3c78 100644 --- a/scripts/sec/yosys/sec.eqy +++ b/scripts/sec/yosys/sec.eqy @@ -1,4 +1,4 @@ -# Copyright 2025 OpenHW Group +# Copyright 2025 OpenHW Foundation # # Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# To be ran as part of `./sec.sh -t yosys` from `scripts/sec` +# To be run as part of `./sec.sh -t yosys` from `scripts/sec` [gold] plugin -i slang