From 5c5aaae1f0d8cf56c2f0893354c054fd2f4dae94 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Wed, 5 Jul 2023 17:15:38 +0200 Subject: [PATCH 01/13] Adding Jinja2 with version restriction to requirements - Jinja2 is required by sphinx - Version 3.1 and later are incompatible with the specified sphinx version - see https://github.com/sphinx-doc/sphinx/issues/10291 - explicitly requiring this older version of Jinja2 solves this - could be removed when moving to newer sphinx version --- doc/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index 66859e6e04..627cef7466 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -5,3 +5,4 @@ sphinx~=3.0 sphinx_rtd_theme sphinxcontrib-wavedrom wavedrom>=1.9.0rc1 +Jinja2<3.1 From fed1a877bc34692a26616d1888b31bd5b3fc7ccd Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 10:36:25 +0200 Subject: [PATCH 02/13] Adding initial version of CV32E20 specification --- doc/00_specification/index.rst | 863 +++++++++++++++++++++++++++++++++ doc/index.rst | 19 +- 2 files changed, 875 insertions(+), 7 deletions(-) create mode 100644 doc/00_specification/index.rst diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst new file mode 100644 index 0000000000..a72041e927 --- /dev/null +++ b/doc/00_specification/index.rst @@ -0,0 +1,863 @@ +===================== +CV32E20 Specification +===================== + +Revision 0.1 + +License +======= + +Copyright 2022-2023 OpenHW Group + +Copyright 2018-2022 lowRISC Revision 8d044a3d + +Copyright 2017-2018, ETH Zurich and University of Bologna + +Copyright 2018 ETH Zürich and University of Bologna + +SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 + +Licensed under the Solderpad Hardware License v 2.1 (the “License”); you +may not use this file except in compliance with the License, or, at your +option, the Apache License version 2.0. You may obtain a copy of the +License at https://solderpad.org/licenses/SHL-2.1/. + +Unless required by applicable law or agreed to in writing, any work +distributed under the License is distributed on an “AS IS” BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Introduction +============ + +The OpenHW Group CV32E20, or simply E20, is a RISC-V processor core that +is targeted for the ultra-low-end of the 32-bit microcontroller (MCU) +application space. Likely uses include any “constrained compute socket” +or as the processor element in embedded 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 RTL code is written in +SystemVerilog and maintained by the OpenHW Group. + +This specification is organized as requirements that apply to the “Scope +of the IP”. The Revision 0.1 of this requirements document is intended +to specify the “Version 1” E20 design – there are already plans for +subsequent enhancements that will be included in a Version 2 (and +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 +Work Group (TWG), as well as any subsequent change requests. + +The specification is complemented by a 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. + +Scope +===== + +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 +(designs under test) - one covering the processor core itself, and a +“\ **coreplex**\ ” covering the processor “core complex” which adds +debug capabilities, an interrupt controller and system bus protocol +wrappers to the E20 core. + +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 + +As displayed in this core block diagram, the E20 is a 2-stage pipelined +implementation featuring a 32-bit Harvard memory architecture for +independent instruction fetch and data load/store interfaces. The first +pipeline stage is the instruction fetch (IF), while the second stage is +the Instruction Decode and Execute (ID/EX). + +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 + + - Support for both RV32I (32 x 32b GPRs) and RV32E (16 x 32b GPRs) + + - Support for ISA extensions: C (compressed) and M (multiply & + divide) + + - Support for basic set of Configuration & Status Registers (CSRs) + +- Dual 32-bit Harvard memory interfaces + + - Supported core protocol is OBI_1_v1.2 (Open Bus Interface) + definition + +At the coreplex design level, the following functions are added to the +processor core: + +- Debug module including the DTM + +- Interrupt module + +- System bus wrappers to convert from OBI to the AMBA-AHB (Advanced + Microcontroller Bus Architecture, Advanced High-performance Bus) + protocol + +In addition to these main configurations, multiple fine grain parameters +are available. + +Unless otherwise stated, optional features are controlled by +SystemVerilog parameters. If not selected, each optional feature is not +present in the netlist after synthesis. The reader’s attention is drawn +to the difference between an optional feature (“...\ *shall* support as +an option...”) versus a desired goal (“...\ *should* support...”, +“...\ *should* reduce latency...”). + +The following topics are beyond the scope of this specification: + +- Software (SW layers), such as compilers, assemblers and OSes + (although these could be part of the OpenHW Group CV32E20 project) + +- Software emulation of RISC-V optional extensions (feasible but the + scope of the IP is the core and coreplex hardware) + +- Other features included in the testbench (main memory, firmware, + interconnect…), the coverage of which are not measured + +Golden configurations +--------------------- + +It is not possible to verify all 2\ :sup:`n` combinations of design +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 | FPGA | RV32EMC | ++----------------------------+-----------------+----------------------+ +| cv32e2_imc_fpga | FPGA | RV32IMC | ++----------------------------+-----------------+----------------------+ +| cv32e2_emc_asic | ASIC | RV32EMC | ++----------------------------+-----------------+----------------------+ +| cv32e2_imc_asic | ASIC | RV32IMC | ++----------------------------+-----------------+----------------------+ + +References +========== + +Applicable specifications +------------------------- + +To ease the reading, the reference to these specifications is implicit +in the requirements below. For the sake of precision, the requirements +identify the versions of RISC-V extensions from these specifications. + +[RVuser] “The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA, +Document Version 20191213”, Editors Andrew Waterman and Krste Asanović, +RISC-V Foundation, December 13, 2019. + +[RVpriv] “The RISC-V Instruction Set Manual, Volume II: Privileged +Architecture, Document Version 20211203”, Editors Andrew Waterman and +Krste Asanović, RISC-V Foundation, December 4, 2021. + +[RVdbg-RATIFIED] “RISC-V External Debug Support, Document Version +0.13.2”, Editors Tim Newsome and Megan Wachs, RISC-V Foundation, March +22, 2019. + +[RVdbg-STABLE] “RISC-V External Debug Support, Document Version +1.0.0-STABLE”, Editors Ernie Edgar and Tim Newsome, RISC-V Foundation, +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* + +[AMBA] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), +https://developer.arm.com/documentation/ihi0033/latest. + +[RVsmclic] “Smclic” Core-Local Interrupt Controller (CLIC) RISC-V +Privileged Architecture Extension, version 0.9-draft, 3/15/2022, +*https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.pdf.* + +Other documents +=============== + +[FPGAreset] Ken Chapman, “Get Smart About Reset: Think Local, Not +Global”, Xilinx WP272 white paper, +*https://docs.xilinx.com/v/u/en-US/wp272*. + +CV32E20 core functional requirements +==================================== + +General requirement +------------------- + ++--------+--------------------------------------------------------------+ +| GEN-10 | CV32E20 shall be **fully compliant with RISC-V | +| | specifications** by implementing all mandatory features for | +| | the selected extensions. | ++--------+--------------------------------------------------------------+ + +As the RISC-V specification leaves ample space for options, this section +specifies these options. + +RISC-V standard instructions +---------------------------- + +To ease tracing for verification, the extensions are split into +independent requirements. + ++--------+---------------------------------------------------------------+ +| ISA-10 | CV32E20 shall support **RV32I** base instruction set, version | +| | 2.1 (ratified). | ++--------+---------------------------------------------------------------+ +| ISA-20 | CV32E20 shall support **RV32E** base instruction set, version | +| | 1.9 (draft). | ++--------+---------------------------------------------------------------+ +| ISA-30 | CV32E20 shall support the **M** extension (integer multiply & | +| | divide), version 2.0 (ratified). | ++--------+---------------------------------------------------------------+ +| ISA-40 | CV32E20 shall support the **C** extension (compressed | +| | instructions), version 2.0 (ratified). | ++--------+---------------------------------------------------------------+ +| ISA-50 | CV32E20 shall support the **Zicsr** extension (CSR | +| | instructions), version 2.0 (ratified). | ++--------+---------------------------------------------------------------+ +| ISA-60 | CV32E20 shall support the **Zifencei** extension, version 2.0 | +| | (ratified). | ++--------+---------------------------------------------------------------+ + +Operating modes (Privilege Levels) +---------------------------------- + ++--------+--------------------------------------------------------------+ +| PVL-10 | CV32E20 shall support only little-endian memory | +| | organizations. | ++--------+--------------------------------------------------------------+ +| PVL-20 | CV32E20 shall support **machine** and **unprivileged** | +| | privilege modes. | ++--------+--------------------------------------------------------------+ +| PVL-30 | CV32E20 shall export the CPU’s operating mode as an address | +| | phase attribute output signals on the Harvard memory | +| | interfaces (instruction fetch, data load/store) with machine | +| | mode defined as 1’b1 and user mode as 1’b0. | ++--------+--------------------------------------------------------------+ +| PVL-40 | CV32E20 shall support the **bare** (addressing) mode, that | +| | is, no support for address translation or protection. | ++--------+--------------------------------------------------------------+ + +Control and Status Registers (CSRs) +----------------------------------- + ++--------+--------------------------------------------------------------+ +| CSR-10 | CV32E20 shall implement all mandatory CSRs of Debug, Machine | +| | and User modes as per specifications in [RVpriv]. | ++--------+--------------------------------------------------------------+ + +In keeping with the CV32E20’s smallest size and power core targets, the +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 // unprivileged mode cycle, lower 32b | +| | | +| | 0xc02 instret // unprivileged mode instret, lower 32b | +| | | +| | 0xc80 cycleh // unprivileged mode cycle, upper 32b | +| | | +| | 0xc82 instreth // unprivileged 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 +--------------------------------- + +For the performance monitor counters, the default CSR configuration for +the CV32E20 core implements the two 64-bit cycle and +inst(ructions)ret(ired) counters along with the 32-bit mcountinhibit +register. + +The 64-bit counters are accessed using CSRR instructions separately +reading the upper and lower 32-bit values. A 4-instruction loop can be +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 // unprivileged mode cycle, lower 32b | +| | | +| | 0xc02 instret // unprivileged mode instret, lower 32b | +| | | +| | 0xc80 cycleh // unprivileged mode cycle, upper 32b | +| | | +| | 0xc82 instreth // unprivileged 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). | +| | | +| | **NOTE: The Ibex documentation is incorrect/confusing about | +| | the optional presence of mpmcounter{11,12}. This | +| | specification assumes the Ibex documentation is simply | +| | incorrect for these 2 counters.** | +| | | +| | 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 | ++--------+---------------------------------------------------------------+ +| NOTE | It should be mentioned that the event associated with | +| | mphm{event,counter}11 has a different definition for the E20 | +| | core versus Ibex. This counter no longer tracks multiply | +| | cycles, but rather, the cycles when the core is quiescent in | +| | the ‘wait for interrupt’ state. | ++--------+---------------------------------------------------------------+ + +Additional details on the CSRs are available in the user manual. + +Interface requirements +====================== + +CV32E20 core memory bus +----------------------- + ++--------+-------------------------------------------------------------+ +| MEM-10 | CV32E20 core shall support a Harvard memory interface with | +| | two 32-bit OBI interfaces, one for instruction fetch and a | +| | second for data loads & stores. Each bus includes a 32-bit | +| | byte address and dual 32-bit buses for read and write data. | +| | Data references support 8-bit byte, 16-bit halfword and | +| | 32-bit word elements. | ++--------+-------------------------------------------------------------+ + +CV32E20 coreplex memory bus +--------------------------- + ++--------+-------------------------------------------------------------+ +| MEM-20 | The CV32E20 coreplex shall support a Harvard memory | +| | interface with two 32-bit AMBA-AHB5 interfaces, one for | +| | instruction fetch and a second for data loads & stores. | +| | Each bus includes a 32-bit byte address and dual 32-bit | +| | buses for read and write data. Data references support | +| | 8-bit byte, 16-bit halfword and 32-bit word elements. | ++--------+-------------------------------------------------------------+ +| MEM-21 | The CV32E20 coreplex also shall support a 32-bit AMBA-AHB5 | +| | interface from the debug module to allow real-time debug | +| | access to system memory. | ++--------+-------------------------------------------------------------+ +| MEM-30 | The CV32E20 coreplex shall support unaligned (also known as | +| | *misaligned*) data accesses for the E20 core by generating | +| | 2 bus cycles to complete the memory reference. This | +| | capability requires individual byte strobes be supported in | +| | the attached data memory. | +| | | +| | If this capability cannot be supported, the coreplex shall | +| | support an optional hardware configuration where all | +| | unaligned data accesses are decomposed into combinations of | +| | 8- and 16-bit transfers. This means the ‘worst-case’ data | +| | unalignment may require 3 bus cycles (byte, halfword, byte) | +| | to complete. | ++--------+-------------------------------------------------------------+ +| MEM-40 | The CV32E20 coreplex shall generate only SINGLE AHB | +| | transactions, that is, no BURST transactions are generated | +| | by the E20 core. | ++--------+-------------------------------------------------------------+ +| MEM-50 | The CV32E20 coreplex AHB5 bus protocol shall support the | +| | following design interface parameters: | +| | | +| | ADDR_WIDTH 32 | +| | | +| | DATA_WIDTH 32 | +| | | +| | HBURST_WIDTH 4 | +| | | +| | HPROT_WIDTH 4 | +| | | +| | HMASTER_WIDTH 0 | ++--------+-------------------------------------------------------------+ +| MEM-60 | The CV32E20 coreplex AHB5 bus protocol shall not support | +| | signaling associated with exclusive accesses – this implies | +| | the HEXCL and HEXOKAY control signals are not used. | ++--------+-------------------------------------------------------------+ +| MEM-70 | The CV32E20 coreplex AHB5 bus protocol shall encode the | +| | operating mode of every access using the {HNONSECURE, | +| | HPROT[1]} bus attribute signals defined as: | +| | | +| | if E20 core mode = user, then {HNONSECURE, HPROT[1]} = | +| | 2’b10 | +| | | +| | if E20 core mode = supervisor, then {HNONSECURE, HPROT[1]} | +| | = 2’b11 | +| | | +| | if E20 core mode = machine, then {HNONSECURE, HPROT[1]} = | +| | 2’b01 | ++--------+-------------------------------------------------------------+ +| MEM-80 | The CV32E20 coreplex AHB5 bus protocol shall implement a | +| | 4-bit HPROT[*] bus attribute control where HPROT[3:2] is | +| | hardwired to 2’b00. | ++--------+-------------------------------------------------------------+ + +Debug +----- + ++---------+------------------------------------------------------------+ +| DBG-10 | CV32E20 shall implement the features outlined in Chapter 4 | +| | of [RVdbg]. | ++---------+------------------------------------------------------------+ + +In addition, there can be an external debug module, not in the scope of +the IP. + +Interrupts +---------- + ++---------+------------------------------------------------------------+ +| IRQ-10 | CV32E20 shall implement interrupt handling registers as | +| | per the RISC-V privilege specification and interface with | +| | a CLIC implementation. | ++---------+------------------------------------------------------------+ + +Coprocessor interface +--------------------- + ++--------+-------------------------------------------------------------+ +| XIF-10 | For *subsequent* core implementations, CV32E20 shall | +| | support the coprocessor interface compliant with [CV-X-IF] | +| | to extend the supported instructions. The goal is a set of | +| | compatible interfaces between the CORE-V cores, for | +| | example, CV32E40{P,S,X}, CV32E20, … | +| | | +| | The initial version of CV32E20 shall not support the | +| | CV-X-IF coprocessor interface. | ++--------+-------------------------------------------------------------+ + +PPA targets +=========== + +These PPA targets will be updated when physical design monitoring is +integrated in the continuous integration flow. + ++--------+-------------------------------------------------------------+ +| PPA-10 | CV32E20 should be resource optimized for both ASIC and FPGA | +| | targets. | +| | | +| | In general, the relative priority of the PPA metrics is | +| | Power > Area > Performance. The project needs to determine | +| | how much to measure and minimize power dissipation - | +| | core/coreplex area provides a general proxy for power with | +| | numerous caveats. | ++--------+-------------------------------------------------------------+ +| PPA-20 | CV32E20 should deliver more than x.y CoreMark/MHz | +| | performance when targeting RV32IMC for maximum performance, | +| | for example, GCC -O3 compiler options and attached to zero | +| | wait-state instruction and data memories. | +| | | +| | This performance metric should be defined across multiple | +| | configuration variables like RV32{I,E}MC, compilers | +| | {GCC,LLVM} and compiler options {-O3, -Os/-Oz}. The core's | +| | operating environment is defined with attached zero | +| | wait-state instruction and data memories. | ++--------+-------------------------------------------------------------+ +| PPA-30 | CV32E20 should operate at more than ? MHz in the | +| | CV32E20\_?\_fpga configuration on Kintex 7 FPGA technology. | +| | | +| | Metric details to be supplied later. | ++--------+-------------------------------------------------------------+ +| PPA-50 | CV32E20 should operate at more than ? MHz in the | +| | CV32E20\_? configuration on 16-nm FFT technology in the | +| | worst-case frequency corner with the fastest threshold | +| | voltage. | +| | | +| | Metric details to be supplied later. | ++--------+-------------------------------------------------------------+ + +Physical design rules +--------------------- + +As different teams have different design rules and flows, and to ease +the integration in FPGA and ASIC design flows: + ++---------+------------------------------------------------------------+ +| PDR-10 | CV32E20 should have a configurable global reset signal: | +| | synchronous/asynchronous, active high/low. | +| | | +| | For asynchronous resets, the assertion edge is treated as | +| | an asynchronous event; the negation edge is treated as a | +| | *synchronous* event. | ++---------+------------------------------------------------------------+ +| PDR-20 | CV32E20 shall be a “super-synchronous” design with a | +| | single clock input and all sequential elements operating | +| | on the pos-edge of the clock. | ++---------+------------------------------------------------------------+ +| PDR-40 | CV32E20 should not include multi-cycle paths. | ++---------+------------------------------------------------------------+ +| PDR-50 | CV32E20 should not include technology-dependent blocks. | +| | | +| | If technology-dependent blocks are used, e.g., to improve | +| | PPA on certain targets, the equivalent | +| | technology-independent block should be available. A design | +| | parameter can be used to select between the | +| | implementations. | ++---------+------------------------------------------------------------+ +| PDR-20 | For certain FPGA targets, CV32E20 may remove the reset in | +| | the RTL code. | +| | | +| | See [FPGAreset] for background information on this | +| | requirement. | ++---------+------------------------------------------------------------+ + +List of abbreviations +===================== + ++------+---------------------------------------------------------------+ +| AHB | Advanced High-performance Bus | ++======+===============================================================+ +| ALU | Arithmetic/Logic Unit | ++------+---------------------------------------------------------------+ +| AMBA | Arm's Advanced Microcontroller Bus Architecture | ++------+---------------------------------------------------------------+ +| ASIC | Application-Specific Integrated Circuit | ++------+---------------------------------------------------------------+ +| AXI | Advanced eXtensible Interface | ++------+---------------------------------------------------------------+ +| CLIC | Core-Local Interrupt Controller | ++------+---------------------------------------------------------------+ +| C | SiFive Core-Local Interruptor | +| LINT | | ++------+---------------------------------------------------------------+ +| core | Core Complex | +| plex | | ++------+---------------------------------------------------------------+ +| CSR | Control and Status Register | ++------+---------------------------------------------------------------+ +| CV- | Core-V Coprocessor (X) Interface | +| X-IF | | ++------+---------------------------------------------------------------+ +| DTM | Debug Transport Module | ++------+---------------------------------------------------------------+ +| DUT | Device Under Test | ++------+---------------------------------------------------------------+ +| FPGA | Field Programmable Gate Array | ++------+---------------------------------------------------------------+ +| GP | CPU General-Purpose Register(s) | +| R(s) | | ++------+---------------------------------------------------------------+ +| I | Pipeline stage: Instruction Decode & Execute | +| D/EX | | ++------+---------------------------------------------------------------+ +| IF | Pipeline stage: Instruction Fetch | ++------+---------------------------------------------------------------+ +| IP | Intellectual Property | ++------+---------------------------------------------------------------+ +| ISA | Instruction Set Architecture | ++------+---------------------------------------------------------------+ +| LSU | CPU Load/Store Unit | ++------+---------------------------------------------------------------+ +| MCU | Microcontroller | ++------+---------------------------------------------------------------+ +| MHz | Megahertz | ++------+---------------------------------------------------------------+ +| MULT | CPU Multiplier | ++------+---------------------------------------------------------------+ +| OBI | Open Bus Interface protocol | ++------+---------------------------------------------------------------+ +| OSes | Operating Systems | ++------+---------------------------------------------------------------+ +| PF | Open Hardware Group Project Freeze | ++------+---------------------------------------------------------------+ +| PLIC | Platform-Level Interrupt Controller | ++------+---------------------------------------------------------------+ +| RI | 5th generation of UC Berkeley reduced instruction set | +| SC-V | computing, | +| | | +| | pronounced as "risk-five" | ++------+---------------------------------------------------------------+ +| RTL | Register-Transfer Language | ++------+---------------------------------------------------------------+ +| SoC | System on a Chip | ++------+---------------------------------------------------------------+ +| TWG | Technical Working Group | ++------+---------------------------------------------------------------+ diff --git a/doc/index.rst b/doc/index.rst index 2ac828f741..5391c55439 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,12 +1,16 @@ -Ibex: An embedded 32 bit RISC-V CPU core -======================================== +CV32E20: An embedded 32-bit RISC-V CPU core +=========================================== -Ibex 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. -Ibex is being extensively verified and has seen multiple tape-outs. +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. -You are now reading the Ibex documentation. -The documentation is split into four parts. +You are now reading the CV32E20 documentation. +The documentation is split into multiple parts. + +The :doc:`Technical Specification <00_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 :doc:`Overview documentation <01_overview/index>` looks at Ibex from high up. It answers questions like what are the high-level properties of Ibex, which standards is Ibex following, and where is it typically used. @@ -24,6 +28,7 @@ Since Ibex is open source, every user of Ibex is encouraged to learn how to adap :maxdepth: 2 :hidden: + 00_specification/index.rst 01_overview/index.rst 02_user/index.rst 03_reference/index.rst From 2ad7982ba15338c8cfe80d4762597a4fcef48cc7 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 11:26:54 +0200 Subject: [PATCH 03/13] Cleaning up references. Proper citations in place --- doc/00_specification/index.rst | 50 +++++++++++++++++----------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index a72041e927..f6fdd32064 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -123,7 +123,7 @@ are available. Unless otherwise stated, optional features are controlled by SystemVerilog parameters. If not selected, each optional feature is not -present in the netlist after synthesis. The reader’s attention is drawn +present in the netlist after synthesis. The reader's attention is drawn to the difference between an optional feature (“...\ *shall* support as an option...”) versus a desired goal (“...\ *should* support...”, “...\ *should* reduce latency...”). @@ -169,38 +169,38 @@ To ease the reading, the reference to these specifications is implicit in the requirements below. For the sake of precision, the requirements identify the versions of RISC-V extensions from these specifications. -[RVuser] “The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA, -Document Version 20191213”, Editors Andrew Waterman and Krste Asanović, -RISC-V Foundation, December 13, 2019. +.. [RVunpriv] “The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA, + Document Version 20191213”, Editors Andrew Waterman and Krste Asanović, + RISC-V Foundation, December 2019. -[RVpriv] “The RISC-V Instruction Set Manual, Volume II: Privileged -Architecture, Document Version 20211203”, Editors Andrew Waterman and -Krste Asanović, RISC-V Foundation, December 4, 2021. +.. [RVpriv] “The RISC-V Instruction Set Manual, Volume II: Privileged + Architecture, Document Version 20211203”, Editors Andrew Waterman, + Krste Asanović, and John Hauser, RISC-V International, December 2021. -[RVdbg-RATIFIED] “RISC-V External Debug Support, Document Version -0.13.2”, Editors Tim Newsome and Megan Wachs, RISC-V Foundation, March -22, 2019. +.. [RVdbg-RATIFIED] “RISC-V External Debug Support, Document Version + 0.13.2”, Editors Tim Newsome and Megan Wachs, RISC-V Foundation, March + 22, 2019. -[RVdbg-STABLE] “RISC-V External Debug Support, Document Version -1.0.0-STABLE”, Editors Ernie Edgar and Tim Newsome, RISC-V Foundation, -April 7, 2022. +.. [RVdbg-STABLE] “RISC-V External Debug Support, Document Version + 1.0.0-STABLE”, Editors Ernie Edgar and Tim Newsome, RISC-V Foundation, + 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* +.. [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 -[AMBA] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), -https://developer.arm.com/documentation/ihi0033/latest. +.. [AMBA] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), + https://developer.arm.com/documentation/ihi0033/latest -[RVsmclic] “Smclic” Core-Local Interrupt Controller (CLIC) RISC-V -Privileged Architecture Extension, version 0.9-draft, 3/15/2022, -*https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.pdf.* +.. [RVsmclic] “Smclic” Core-Local Interrupt Controller (CLIC) RISC-V + Privileged Architecture Extension, version 0.9-draft, 3/15/2022, + https://github.com/riscv/riscv-fast-interrupt/blob/master/clic.pdf Other documents =============== -[FPGAreset] Ken Chapman, “Get Smart About Reset: Think Local, Not +.. [FPGAreset] Ken Chapman, “Get Smart About Reset: Think Local, Not Global”, Xilinx WP272 white paper, -*https://docs.xilinx.com/v/u/en-US/wp272*. +https://docs.xilinx.com/v/u/en-US/wp272 CV32E20 core functional requirements ==================================== @@ -267,7 +267,7 @@ Control and Status Registers (CSRs) +--------+--------------------------------------------------------------+ | CSR-10 | CV32E20 shall implement all mandatory CSRs of Debug, Machine | -| | and User modes as per specifications in [RVpriv]. | +| | and User modes as per specifications in [RVpriv]_. | +--------+--------------------------------------------------------------+ In keeping with the CV32E20’s smallest size and power core targets, the @@ -277,7 +277,7 @@ 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 | +| | per specifications in [RVpriv]_. Optional registers are | | | *highlighted*. The registers are listed based on ascending | | | CSR number. | | | | @@ -430,7 +430,7 @@ 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]: | +| | counterparts mcycleh and minstreth) as per [RVpriv]_: | | | | | | CSR Number PM Counter Description | | | | From 91f500106fbc00a80bb6faf542183bbead28c3e2 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 13:33:52 +0200 Subject: [PATCH 04/13] Adding some cross references to specifications --- doc/00_specification/index.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index f6fdd32064..20218839a0 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -55,7 +55,7 @@ placeholders for these enhancements after the initial project freeze The requirement list is to be approved by the OpenHW Group Technical Work Group (TWG), as well as any subsequent change requests. -The specification is complemented by a user’s guide. +The specification is complemented by a user's guide. *A list of abbreviations is available at the end of this document.* @@ -114,9 +114,9 @@ processor core: - Interrupt module -- System bus wrappers to convert from OBI to the AMBA-AHB (Advanced - Microcontroller Bus Architecture, Advanced High-performance Bus) - protocol +- System bus wrappers to convert from OBI [OPENHW-OBI]_ to the + AMBA-AHB (Advanced Microcontroller Bus Architecture, Advanced + High-performance Bus) protocol [AMBA-AHB]_ In addition to these main configurations, multiple fine grain parameters are available. @@ -188,7 +188,7 @@ identify the versions of RISC-V extensions from these specifications. .. [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 -.. [AMBA] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), +.. [AMBA-AHB] “AMBA® AHB Protocol Specification”, ARM IHI 0033C (ID090921), https://developer.arm.com/documentation/ihi0033/latest .. [RVsmclic] “Smclic” Core-Local Interrupt Controller (CLIC) RISC-V @@ -221,7 +221,8 @@ RISC-V standard instructions ---------------------------- To ease tracing for verification, the extensions are split into -independent requirements. +independent requirements. All bases and extensions are specified in +[RVunpriv]_. +--------+---------------------------------------------------------------+ | ISA-10 | CV32E20 shall support **RV32I** base instruction set, version | @@ -253,10 +254,10 @@ Operating modes (Privilege Levels) | PVL-20 | CV32E20 shall support **machine** and **unprivileged** | | | privilege modes. | +--------+--------------------------------------------------------------+ -| PVL-30 | CV32E20 shall export the CPU’s operating mode as an address | +| PVL-30 | CV32E20 shall export the CPU's operating mode as an address | | | phase attribute output signals on the Harvard memory | | | interfaces (instruction fetch, data load/store) with machine | -| | mode defined as 1’b1 and user mode as 1’b0. | +| | mode defined as 1'b1 and user mode as 1'b0. | +--------+--------------------------------------------------------------+ | PVL-40 | CV32E20 shall support the **bare** (addressing) mode, that | | | is, no support for address translation or protection. | @@ -270,7 +271,7 @@ Control and Status Registers (CSRs) | | and User modes as per specifications in [RVpriv]_. | +--------+--------------------------------------------------------------+ -In keeping with the CV32E20’s smallest size and power core targets, the +In keeping with the CV32E20's smallest size and power core targets, the implemented set of CSRs is intentionally minimized. The implemented set of CSRs includes the following registers: @@ -593,7 +594,7 @@ lower order 32-bit register. | | mphm{event,counter}11 has a different definition for the E20 | | | core versus Ibex. This counter no longer tracks multiply | | | cycles, but rather, the cycles when the core is quiescent in | -| | the ‘wait for interrupt’ state. | +| | the ‘wait for interrupt' state. | +--------+---------------------------------------------------------------+ Additional details on the CSRs are available in the user manual. @@ -637,7 +638,7 @@ CV32E20 coreplex memory bus | | If this capability cannot be supported, the coreplex shall | | | support an optional hardware configuration where all | | | unaligned data accesses are decomposed into combinations of | -| | 8- and 16-bit transfers. This means the ‘worst-case’ data | +| | 8- and 16-bit transfers. This means the ‘worst-case' data | | | unalignment may require 3 bus cycles (byte, halfword, byte) | | | to complete. | +--------+-------------------------------------------------------------+ @@ -667,17 +668,17 @@ CV32E20 coreplex memory bus | | HPROT[1]} bus attribute signals defined as: | | | | | | if E20 core mode = user, then {HNONSECURE, HPROT[1]} = | -| | 2’b10 | +| | 2'b10 | | | | | | if E20 core mode = supervisor, then {HNONSECURE, HPROT[1]} | -| | = 2’b11 | +| | = 2'b11 | | | | | | if E20 core mode = machine, then {HNONSECURE, HPROT[1]} = | -| | 2’b01 | +| | 2'b01 | +--------+-------------------------------------------------------------+ | MEM-80 | The CV32E20 coreplex AHB5 bus protocol shall implement a | | | 4-bit HPROT[*] bus attribute control where HPROT[3:2] is | -| | hardwired to 2’b00. | +| | hardwired to 2'b00. | +--------+-------------------------------------------------------------+ Debug From 2b47c3007bc050bb08757dfed2b5d784b824e6ba Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 13:55:07 +0200 Subject: [PATCH 05/13] Updating interrupt requirements - changing requirement to CLINT in favor of CLIC - adding requirement for NMI --- doc/00_specification/index.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 20218839a0..38efaa6599 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -199,8 +199,7 @@ Other documents =============== .. [FPGAreset] Ken Chapman, “Get Smart About Reset: Think Local, Not -Global”, Xilinx WP272 white paper, -https://docs.xilinx.com/v/u/en-US/wp272 +Global”, Xilinx WP272 white paper, https://docs.xilinx.com/v/u/en-US/wp272 CV32E20 core functional requirements ==================================== @@ -695,10 +694,19 @@ the IP. Interrupts ---------- +CLINT is the default interrupt controller in [RVpriv]_. It is limited to +32 custom IRQs for RV32. A CLIC [RVsmclic]_ supports up to 4.064 IRQs, +but is not yet ratified at the time of specification. + +---------+------------------------------------------------------------+ | IRQ-10 | CV32E20 shall implement interrupt handling registers as | | | per the RISC-V privilege specification and interface with | -| | a CLIC implementation. | +| | a CLINT implementation. | ++---------+------------------------------------------------------------+ +| IRQ-20 | CV32E20 shall implement one Non-Maskable Interrupt (NMI), | +| | which is triggered from an external signal. The | +| | corresponding excpection code is 31, and mcause will be | +| | set to 0x8000001F. | +---------+------------------------------------------------------------+ Coprocessor interface From f2fb7c4ad7f14a0e90cfde51aaa937d3310cb4bd Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 14:53:14 +0200 Subject: [PATCH 06/13] Fixing reference for FPGA reset --- doc/00_specification/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 38efaa6599..895ac40cb0 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -199,7 +199,7 @@ Other documents =============== .. [FPGAreset] Ken Chapman, “Get Smart About Reset: Think Local, Not -Global”, Xilinx WP272 white paper, https://docs.xilinx.com/v/u/en-US/wp272 + Global”, Xilinx WP272 white paper, https://docs.xilinx.com/v/u/en-US/wp272 CV32E20 core functional requirements ==================================== @@ -794,7 +794,7 @@ the integration in FPGA and ASIC design flows: | PDR-20 | For certain FPGA targets, CV32E20 may remove the reset in | | | the RTL code. | | | | -| | See [FPGAreset] for background information on this | +| | See [FPGAreset]_ for background information on this | | | requirement. | +---------+------------------------------------------------------------+ From 2dd4cc16a9e0021d3c0a1f511be003a0b3f3b07c Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 15:13:33 +0200 Subject: [PATCH 07/13] Adding readme file to document setup for Sphinx doc generation --- doc/Readme.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 doc/Readme.md diff --git a/doc/Readme.md b/doc/Readme.md new file mode 100644 index 0000000000..75c2fd0c64 --- /dev/null +++ b/doc/Readme.md @@ -0,0 +1,45 @@ +# CVE2 Documentation + +The documentation of CVE2 is written in reStructuredText and compiled to HTML using Sphinx. For more information, check https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html. + +## Prerequisites + +To build the documentation, certain prequisites need to be fulfilled. This section outlines the necessary steps on Linux. Tested on Ubuntu 20.04. + +Sphinx is based on Python and requires at least version 3.8. Additionally, `make` is required and can be installed through build-essential. + +```bash +sudo apt update +sudo apt install python3 +sudo apt install build-essential +``` + +Please verify your Python version using + +```bash +python3 --version +``` + +The recommended way of installing Sphinx is via `pip` using + +```bash +pip install -U sphinx +``` + +Sphinx requires certain packages to build this documentation. These are summarized in `doc/requirements.txt`. They can automatically be installed using + +```bash +cd doc +pip install -r requirements.txt +``` + +## Building the documentation + +To build the documentation, switch to the `doc` folder if not already done. Build is invoked via the `make` command. Typically, an HTML should be build. + +```bash +cd doc +make html +``` + +Simply type only `make` to view other available targets. From 7298224aa9f3b9d07b6f467ebbc2c61a38f27c5a Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 16:34:36 +0200 Subject: [PATCH 08/13] Updating glossary to use the built-in features of sphinx --- doc/00_specification/index.rst | 200 ++++++++++++++++++--------------- 1 file changed, 111 insertions(+), 89 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 895ac40cb0..5d15346af9 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -31,29 +31,29 @@ limitations under the License. Introduction ============ -The OpenHW Group CV32E20, or simply E20, is a RISC-V processor core that -is targeted for the ultra-low-end of the 32-bit microcontroller (MCU) +The OpenHW Group 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 SoC subsystems. +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 RTL code is written in +Core-V-Verification methodologies. The source :term:`RTL` code is written in SystemVerilog and maintained by the OpenHW Group. This specification is organized as requirements that apply to the “Scope -of the IP”. The Revision 0.1 of this requirements document is intended -to specify the “Version 1” E20 design – there are already plans for +of the :term:`IP`”. The Revision 0.1 of this requirements document is intended +to specify the “Version 1” E20 design - there are already plans for subsequent enhancements that will be included in a Version 2 (and 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 -Work Group (TWG), as well as any subsequent change requests. +Work Group (:term:`TWG`), as well as any subsequent change requests. The specification is complemented by a user's guide. @@ -72,7 +72,7 @@ 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 (designs under test) - one covering the processor core itself, and a -“\ **coreplex**\ ” covering the processor “core complex” which adds +“\ **:term:`coreplex`**\ ” covering the processor “core complex” which adds debug capabilities, an interrupt controller and system bus protocol wrappers to the E20 core. @@ -86,8 +86,8 @@ diagram of the E20 core is shown below: As displayed in this core block diagram, the E20 is a 2-stage pipelined implementation featuring a 32-bit Harvard memory architecture for independent instruction fetch and data load/store interfaces. The first -pipeline stage is the instruction fetch (IF), while the second stage is -the Instruction Decode and Execute (ID/EX). +pipeline stage is the instruction fetch (:term:`IF`), while the second stage is +the Instruction Decode and Execute (:term:`ID/EX`). As displayed in the above figure, the IP comprises: @@ -97,7 +97,7 @@ As displayed in the above figure, the IP comprises: - Support for both RV32I (32 x 32b GPRs) and RV32E (16 x 32b GPRs) - - Support for ISA extensions: C (compressed) and M (multiply & + - Support for :term:`ISA` extensions: C (compressed) and M (multiply & divide) - Support for basic set of Configuration & Status Registers (CSRs) @@ -110,12 +110,12 @@ As displayed in the above figure, the IP comprises: At the coreplex design level, the following functions are added to the processor core: -- Debug module including the DTM +- Debug module including the :term:`DTM` - Interrupt module - System bus wrappers to convert from OBI [OPENHW-OBI]_ to the - AMBA-AHB (Advanced Microcontroller Bus Architecture, Advanced + :term:`AMBA`-:term:`AHB` (Advanced Microcontroller Bus Architecture, Advanced High-performance Bus) protocol [AMBA-AHB]_ In addition to these main configurations, multiple fine grain parameters @@ -130,7 +130,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 OSes +- Software (SW layers), such as compilers, assemblers and :term:`OSes` (although these could be part of the OpenHW Group CV32E20 project) - Software emulation of RISC-V optional extensions (feasible but the @@ -150,11 +150,11 @@ parameters for each golden configuration are detailed in the user guide. +----------------------------+-----------------+----------------------+ | Configuration | Target | RV32{E,I} ISA | +----------------------------+-----------------+----------------------+ -| cv32e2_emc_fpga | FPGA | RV32EMC | +| cv32e2_emc_fpga | :term:`FPGA` | RV32EMC | +----------------------------+-----------------+----------------------+ | cv32e2_imc_fpga | FPGA | RV32IMC | +----------------------------+-----------------+----------------------+ -| cv32e2_emc_asic | ASIC | RV32EMC | +| cv32e2_emc_asic | :term:`ASIC` | RV32EMC | +----------------------------+-----------------+----------------------+ | cv32e2_imc_asic | ASIC | RV32IMC | +----------------------------+-----------------+----------------------+ @@ -659,7 +659,7 @@ CV32E20 coreplex memory bus | | HMASTER_WIDTH 0 | +--------+-------------------------------------------------------------+ | MEM-60 | The CV32E20 coreplex AHB5 bus protocol shall not support | -| | signaling associated with exclusive accesses – this implies | +| | signaling associated with exclusive accesses - this implies | | | the HEXCL and HEXOKAY control signals are not used. | +--------+-------------------------------------------------------------+ | MEM-70 | The CV32E20 coreplex AHB5 bus protocol shall encode the | @@ -695,13 +695,13 @@ Interrupts ---------- CLINT is the default interrupt controller in [RVpriv]_. It is limited to -32 custom IRQs for RV32. A CLIC [RVsmclic]_ supports up to 4.064 IRQs, +32 custom IRQs for RV32. A :term:`CLIC` [RVsmclic]_ supports up to 4.064 IRQs, but is not yet ratified at the time of specification. +---------+------------------------------------------------------------+ | IRQ-10 | CV32E20 shall implement interrupt handling registers as | | | per the RISC-V privilege specification and interface with | -| | a CLINT implementation. | +| | a :term:`CLINT` implementation. | +---------+------------------------------------------------------------+ | IRQ-20 | CV32E20 shall implement one Non-Maskable Interrupt (NMI), | | | which is triggered from an external signal. The | @@ -791,7 +791,7 @@ the integration in FPGA and ASIC design flows: | | parameter can be used to select between the | | | implementations. | +---------+------------------------------------------------------------+ -| PDR-20 | For certain FPGA targets, CV32E20 may remove the reset in | +| PDR-60 | For certain FPGA targets, CV32E20 may remove the reset in | | | the RTL code. | | | | | | See [FPGAreset]_ for background information on this | @@ -801,72 +801,94 @@ the integration in FPGA and ASIC design flows: List of abbreviations ===================== -+------+---------------------------------------------------------------+ -| AHB | Advanced High-performance Bus | -+======+===============================================================+ -| ALU | Arithmetic/Logic Unit | -+------+---------------------------------------------------------------+ -| AMBA | Arm's Advanced Microcontroller Bus Architecture | -+------+---------------------------------------------------------------+ -| ASIC | Application-Specific Integrated Circuit | -+------+---------------------------------------------------------------+ -| AXI | Advanced eXtensible Interface | -+------+---------------------------------------------------------------+ -| CLIC | Core-Local Interrupt Controller | -+------+---------------------------------------------------------------+ -| C | SiFive Core-Local Interruptor | -| LINT | | -+------+---------------------------------------------------------------+ -| core | Core Complex | -| plex | | -+------+---------------------------------------------------------------+ -| CSR | Control and Status Register | -+------+---------------------------------------------------------------+ -| CV- | Core-V Coprocessor (X) Interface | -| X-IF | | -+------+---------------------------------------------------------------+ -| DTM | Debug Transport Module | -+------+---------------------------------------------------------------+ -| DUT | Device Under Test | -+------+---------------------------------------------------------------+ -| FPGA | Field Programmable Gate Array | -+------+---------------------------------------------------------------+ -| GP | CPU General-Purpose Register(s) | -| R(s) | | -+------+---------------------------------------------------------------+ -| I | Pipeline stage: Instruction Decode & Execute | -| D/EX | | -+------+---------------------------------------------------------------+ -| IF | Pipeline stage: Instruction Fetch | -+------+---------------------------------------------------------------+ -| IP | Intellectual Property | -+------+---------------------------------------------------------------+ -| ISA | Instruction Set Architecture | -+------+---------------------------------------------------------------+ -| LSU | CPU Load/Store Unit | -+------+---------------------------------------------------------------+ -| MCU | Microcontroller | -+------+---------------------------------------------------------------+ -| MHz | Megahertz | -+------+---------------------------------------------------------------+ -| MULT | CPU Multiplier | -+------+---------------------------------------------------------------+ -| OBI | Open Bus Interface protocol | -+------+---------------------------------------------------------------+ -| OSes | Operating Systems | -+------+---------------------------------------------------------------+ -| PF | Open Hardware Group Project Freeze | -+------+---------------------------------------------------------------+ -| PLIC | Platform-Level Interrupt Controller | -+------+---------------------------------------------------------------+ -| RI | 5th generation of UC Berkeley reduced instruction set | -| SC-V | computing, | -| | | -| | pronounced as "risk-five" | -+------+---------------------------------------------------------------+ -| RTL | Register-Transfer Language | -+------+---------------------------------------------------------------+ -| SoC | System on a Chip | -+------+---------------------------------------------------------------+ -| TWG | Technical Working Group | -+------+---------------------------------------------------------------+ +.. glossary:: + + AHB + Advanced High-performance Bus + + ALU + Arithmetic/Logic Unit + + AMBA + Arm(R)'s Advanced Microcontroller Bus Architecture + + ASIC + Application-Specific Integrated Circuit + + AXI + Advanced eXtensible Interface + + CLIC + Core-Local Interrupt Controller + + CLINT + RISC-V Privileged Specification Interrupt Controller + + coreplex + Core Complex + + CSR + Control and Status Register + + CV-X-IF + Core-V Coprocessor (X) Interface + + DTM + Debug Transport Module + + DUT + Device Under Test + + FPGA + Field Programmable Gate Array + + GPR(s) + CPU General-Purpose Register(s) + + ID/EX + Pipeline stage: Instruction Decode & Execute + + IF + Pipeline stage: Instruction Fetch + + IP + Intellectual Property + + ISA + Instruction Set Architecture + + LSU + CPU Load/Store Unit + + MCU + Microcontroller + + MHz + Megahertz + + MULT + CPU Multiplier + + OBI + Open Bus Interface protocol + + OSes + Operating Systems + + PF + Open Hardware Group Project Freeze + + PLIC + Platform-Level Interrupt Controller + + RISC-V + 5th generation of UC Berkeley reduced instruction set computing, pronounced as "risk-five" + + RTL + Register-Transfer Language + + SoC + System on a Chip + + TWG + Technical Working Group From eea756235b62d5d38455abdd9f63876512446323 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Tue, 15 Aug 2023 17:33:07 +0200 Subject: [PATCH 09/13] Added RNMI requirement --- doc/00_specification/index.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 5d15346af9..45fc67ccde 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -45,7 +45,7 @@ Core-V-Verification methodologies. The source :term:`RTL` code is written in SystemVerilog and maintained by the OpenHW Group. 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 +of the :term:`IP`". The Revision 0.1 of this requirements document is intended to specify the “Version 1” E20 design - there are already plans for subsequent enhancements that will be included in a Version 2 (and possibly beyond) design releases. Subsequent revision numbers are @@ -72,7 +72,7 @@ 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 (designs under test) - one covering the processor core itself, and a -“\ **:term:`coreplex`**\ ” covering the processor “core complex” which adds +:term:`coreplex` covering the processor "core complex" which adds debug capabilities, an interrupt controller and system bus protocol wrappers to the E20 core. @@ -124,9 +124,9 @@ are available. Unless otherwise stated, optional features are controlled by SystemVerilog parameters. If not selected, each optional feature is not present in the netlist after synthesis. The reader's attention is drawn -to the difference between an optional feature (“...\ *shall* support as -an option...”) versus a desired goal (“...\ *should* support...”, -“...\ *should* reduce latency...”). +to the difference between an optional feature ("...\ *shall* support as +an option...") versus a desired goal ("...\ *should* support...", +"...\ *should* reduce latency..."). The following topics are beyond the scope of this specification: @@ -705,9 +705,14 @@ but is not yet ratified at the time of specification. +---------+------------------------------------------------------------+ | IRQ-20 | CV32E20 shall implement one Non-Maskable Interrupt (NMI), | | | which is triggered from an external signal. The | -| | corresponding excpection code is 31, and mcause will be | -| | set to 0x8000001F. | +| | corresponding excpection code is 32. | +---------+------------------------------------------------------------+ +| IRQ-30 | The NMI implemented by CV32E20 shall be resumable. | ++---------+------------------------------------------------------------+ + +It should be noted that Ibex 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. Coprocessor interface --------------------- From 83ed15eb273d0e8773e416f451bc527ed1a6aa01 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Wed, 16 Aug 2023 09:13:15 +0200 Subject: [PATCH 10/13] Replacing the config.py with one from CV32E40P to adjust style from lowRISC to OpenHW Group --- doc/00_specification/index.rst | 2 - doc/_static/css/custom.css | 3 + doc/_static/theme_overrides.css | 18 ---- doc/conf.py | 176 +++++++++++++++++++++----------- 4 files changed, 121 insertions(+), 78 deletions(-) create mode 100644 doc/_static/css/custom.css delete mode 100644 doc/_static/theme_overrides.css diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 45fc67ccde..3b10d25406 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -2,8 +2,6 @@ CV32E20 Specification ===================== -Revision 0.1 - License ======= diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css new file mode 100644 index 0000000000..e585e1a12d --- /dev/null +++ b/doc/_static/css/custom.css @@ -0,0 +1,3 @@ +.no-scrollbar-table td { + white-space: normal !important; +} diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css deleted file mode 100644 index 828f0d34aa..0000000000 --- a/doc/_static/theme_overrides.css +++ /dev/null @@ -1,18 +0,0 @@ -/* override table width restrictions */ -@media screen and (min-width: 767px) { - - .wy-table-responsive table td { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - } -} - -.wy-nav-content { - max-width: 1000px !important; -} - diff --git a/doc/conf.py b/doc/conf.py index b4e8541a8f..372304570d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,34 +1,53 @@ -# Copyright lowRISC contributors. -# Licensed under the Apache License, Version 2.0, see LICENSE for details. -# SPDX-License-Identifier: Apache-2.0 +# -*- coding: utf-8 -*- # -# Sphinx configuration file for the Ibex documentation +# Copyright (c) 2020, 2023 OpenHW Group # -# All configuration values have a default; values that are commented out -# serve to show the default. +# Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://solderpad.org/licenses/ +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0 +# +############################################################################### +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) -# Source top directory -topsrcdir = os.path.join(os.path.dirname(__file__), '..') -old_sys_path = sys.path -try: - sys.path.append(os.path.join(topsrcdir, 'util')) - import check_tool_requirements as ctr -finally: - sys.path = old_sys_path +# -- Project information ----------------------------------------------------- +project = 'CV32E20 Documentation' +copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-2022 lowRISC, 2022-2023 OpenHW Group' +author = 'OpenHW Group' + +# The short X.Y version +version = u'0.1' +# The full version, including alpha/beta/rc tags +release = u'0.1' -numfig=True -numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s'} -# -- General configuration ------------------------------------------------ +# -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # @@ -38,6 +57,8 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.autodoc', + 'sphinx_github_changelog', 'sphinxcontrib.wavedrom', 'sphinx.ext.todo', ] @@ -47,7 +68,7 @@ render_using_wavedrompy = True # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['ytemplates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -58,21 +79,6 @@ # The master toctree document. master_doc = 'index' -# General information about the project. -project = 'Ibex Documentation' -copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-present lowRISC' -author = 'lowRISC contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '' -# The full version, including alpha/beta/rc tags. -from setuptools_scm import get_version -release = get_version(root=topsrcdir) - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -82,43 +88,60 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv'] +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +# Numbering +numfig=True +numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'Listing %s'} -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # +#html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -html_theme_options = { - 'style_nav_header_background': '#E53651' -} - -html_logo = 'images/logo.svg' +html_theme_options = {'style_nav_header_background': '#DDDDDD'} +html_logo = '../images/openhw-landscape.svg' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['ystatic'] +# Set html_static_path to null on the advice of RTDs: html_static_path = ['_static'] +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + html_css_files = [ - 'theme_overrides.css', # Fix wide tables in RTD theme + 'css/custom.css', ] -# -- Options for LaTeX output --------------------------------------------- +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'CORE-V_CV32E20_Documentation' + + +# -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). @@ -142,39 +165,76 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'ibex.tex', u'Ibex Documentation', - u'lowRISC', 'manual'), + (master_doc, 'CV32E20_Documentation.tex', u'CV32E20 Documentation', + u'OpenHW Group', 'manual'), ] -latex_logo = '' -# -- Options for manual page output --------------------------------------- +# -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'ibex', u'Ibex Documentation', + (master_doc, 'CV32E20_Documentation.tex', u'CORE-V-Docs Documentation', [author], 1) ] -# -- Options for Texinfo output ------------------------------------------- +# -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'ibex', u'Ibex Documentation', - author, 'ibex', 'Ibex RV32 CPU core', + (master_doc, 'CV32E20_Documentation.tex', u'CORE-V-Docs Documentation', + author, 'Documentation', 'Documentation for CV32E20 CORE-V processor core.', 'Miscellaneous'), ] + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + # -- Tool version numbers ------------------------------------------------- # Add minimum versions of required tools as variables for use inside the # documentation. +import os +import sys + +# Source top directory +topsrcdir = os.path.join(os.path.dirname(__file__), '..') + +old_sys_path = sys.path +try: + sys.path.append(os.path.join(topsrcdir, 'util')) + import check_tool_requirements as ctr +finally: + sys.path = old_sys_path tool_reqs = ctr.read_tool_requirements() rst_epilog = "" for tool, req in tool_reqs.items(): rst_epilog += (".. |tool_requirements.{}| replace:: {}\n" - .format(tool, req.min_version)) + .format(tool, req.min_version)) \ No newline at end of file From 4ca636de74ad1a3cfa75ad05fe6eaa7e1d587797 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Wed, 16 Aug 2023 10:25:45 +0200 Subject: [PATCH 11/13] Using proper syntax for notes --- doc/00_specification/index.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 3b10d25406..2dd781ff82 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -459,11 +459,6 @@ lower order 32-bit register. | | monitoring capabilities in FPGA development targets (and/or | | | ASIC SoC targets). | | | | -| | **NOTE: The Ibex documentation is incorrect/confusing about | -| | the optional presence of mpmcounter{11,12}. This | -| | specification assumes the Ibex documentation is simply | -| | incorrect for these 2 counters.** | -| | | | | CSR Number PM Counter Description | | | | | | 0xb03 mhpmcounter3 // m-mode performance-monitoring counter 3 | @@ -587,12 +582,17 @@ lower order 32-bit register. | | | | | 0x32c mphmevent12 // 12, 0x0000_1000 | +--------+---------------------------------------------------------------+ -| NOTE | It should be mentioned that the event associated with | -| | mphm{event,counter}11 has a different definition for the E20 | -| | core versus Ibex. This counter no longer tracks multiply | -| | cycles, but rather, the cycles when the core is quiescent in | -| | the ‘wait for interrupt' state. | -+--------+---------------------------------------------------------------+ + +.. note:: + The Ibex documentation is incorrect/confusing about the optional + presence of mpmcounter{11,12}. This specification assumes the Ibex + documentation is simply incorrect for these 2 counters. + +.. note:: + It should be mentioned that the event associated with + mphm{event,counter}11 has a different definition for the E20 core versus + Ibex. This counter no longer tracks multiply cycles, but rather, the + cycles when the core is quiescent in the 'wait for interrupt' state. Additional details on the CSRs are available in the user manual. @@ -693,8 +693,8 @@ Interrupts ---------- CLINT is the default interrupt controller in [RVpriv]_. It is limited to -32 custom IRQs for RV32. A :term:`CLIC` [RVsmclic]_ supports up to 4.064 IRQs, -but is not yet ratified at the time of specification. +32 custom IRQs for RV32. A :term:`CLIC` [RVsmclic]_ supports up to 4.064 +IRQs, but is not yet ratified at the time of specification. +---------+------------------------------------------------------------+ | IRQ-10 | CV32E20 shall implement interrupt handling registers as | @@ -708,9 +708,10 @@ but is not yet ratified at the time of specification. | IRQ-30 | The NMI implemented by CV32E20 shall be resumable. | +---------+------------------------------------------------------------+ -It should be noted that Ibex 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. +.. note:: + It should be noted that Ibex 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. Coprocessor interface --------------------- From fa5ee584e30bd3f7e89c16ca53e4226dff89c551 Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Wed, 16 Aug 2023 10:57:02 +0200 Subject: [PATCH 12/13] Adding cross reference to list of abbreviations --- doc/00_specification/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/00_specification/index.rst b/doc/00_specification/index.rst index 2dd781ff82..36e38b6583 100644 --- a/doc/00_specification/index.rst +++ b/doc/00_specification/index.rst @@ -55,7 +55,7 @@ Work Group (:term:`TWG`), as well as any subsequent change requests. The specification is complemented by a user's guide. -*A list of abbreviations is available at the end of this document.* +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. @@ -802,7 +802,7 @@ the integration in FPGA and ASIC design flows: | | requirement. | +---------+------------------------------------------------------------+ -List of abbreviations +List of Abbreviations ===================== .. glossary:: From fdf0c8d04476c5e04628cc085f1f360743e1fa9e Mon Sep 17 00:00:00 2001 From: Christian Herber Date: Wed, 23 Aug 2023 09:29:14 +0200 Subject: [PATCH 13/13] Added rtd yaml config file --- .readthedocs.yaml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..00178f192c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,23 @@ +# Copyright 2023 OpenHW Group +# Solderpad Hardware License, Version 2.1, see LICENSE.md for details. +# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 + +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +build: + os: "ubuntu-20.04" + tools: + python: "3.9" + +# Build from the docs directory with Sphinx +sphinx: + configuration: doc/conf.py + +# Explicitly set the Python requirements +python: + install: + - requirements: doc/requirements.txt \ No newline at end of file