Designdoc (#1713)

* rename csr files

* Revisit the design specification skeleton

docs/01_cva6_user/Traps_Interrupts_Exceptions.rst

@@ -27,13 +27,13 @@ On one hand, interrupts are occuring independently of the instructions
 On the other hand, an instruction may raise exceptions synchronously.
 
 Raising Traps
-=============
+-------------
 When a trap is raised, the behaviour of the CVA6 core depends on
 several CSRs and some CSRs are modified. The CSR description is available
 in :doc:`CV32A6_Control_Status_Registers`.
 
 Configuration CSRs
-------------------
+~~~~~~~~~~~~~~~~~~
 CSRs having an effect on the core behaviour when a trap occurs are:
 
 * ``mstatus`` and ``sstatus``: several fields control the core behaviour like interrupt enable (``MIE``, ``SIE``)
@@ -42,7 +42,7 @@ CSRs having an effect on the core behaviour when a trap occurs are:
 * ``mideleg``: specifies which interrupts can be handled by a lower privileged mode (S-mode)
 
 Modified CSRs
--------------
+~~~~~~~~~~~~~
 CSRs (or fields) updated by the core when a trap occurs are:
 
 * ``mstatus`` or ``sstatus``: several fields are updated like previous privilege mode (``MPP``, ``SPP``), previous interrupt enabled (``MPIE``, SPIE``)
@@ -51,7 +51,7 @@ CSRs (or fields) updated by the core when a trap occurs are:
 * ``mtval`` or ``stval``: updated with exception specific information like the faulting virtual address
 
 Supported exceptions
---------------------
+~~~~~~~~~~~~~~~~~~~~
 The following exceptions are supported by the CVA6:
 
 * instruction address misaligned
@@ -103,23 +103,23 @@ The following exceptions are supported by the CVA6:
 Note: all exceptions are supported except the ones linked to the hypervisor extension
 
 Trap return
-===========
+-----------
 Trap handler ends with trap return instruction (``MRET``, ``SRET``). The behaviour of the CVA6 core depends on several CSRs.
 
 Configuration CSRs
-------------------
+~~~~~~~~~~~~~~~~~~
 CSRs having an effect on the core behaviour when returning from a trap are:
 
 * ``mstatus``: several fields control the core behaviour like previous privilege mode (``MPP``, ``SPP``), previous interrupt enabled (``MPIE``, ``SPIE``)
 
 Modified CSRs
--------------
+~~~~~~~~~~~~~
 CSRs (or fields) updated by the core when returning from a trap are:
 
 * ``mstatus``: several fields are updated like interrupt enable (``MIE``, ``SIE``), modify privilege (``MPRV``)
 
 Interrupts
-==========
+----------
 * external interrupt: ``irq_i`` signal
 * software interrupt (inter-processor interrupt): ``ipi_i`` signal
 * timer interrupt: ``time_irq_i`` signal
@@ -130,5 +130,5 @@ These signals are level sensitive. It means the interrupt is raised until it is
 The exception code field (``mcause`` CSR) depends on the interrupt source.
 
 Wait for Interrupt
-==================
+------------------
 * CVA6 implementation: ``WFI`` stalls the core. The instruction is not available in U-mode (raise illegal instruction exception). Such exception is also raised when ``TW=1`` in ``mstatus``.

docs/04_cv32a6_design/source/embedded_AXI.rst

@@ -0,0 +1,10 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+.. include:: ../../01_cva6_user/AXI_Interface.rst

docs/04_cv32a6_design/source/embedded_CSRs.rst

@@ -0,0 +1,19 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+
+CSR
+===
+
+.. toctree::
+   :hidden:
+
+   embedded_csr_list
+   embedded_csr
+

docs/04_cv32a6_design/source/embedded_CVXIF.rst

@@ -0,0 +1,11 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+
+.. include:: ../../01_cva6_user/CVX_Interface_Coprocessor.rst

docs/04_cv32a6_design/source/embedded_architecture.rst

@@ -0,0 +1,38 @@
+..
+   Copyright 2022 Thales DIS design services SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+.. _EMBEDDED_ARCHITECTURE:
+
+
+Architecture and Modules
+========================
+
+The CV32A6 v0.1.0 subsystem is composed of 8 modules.
+
+.. figure:: ../images/subsystems.png
+   :name: CV32A6 v0.1.0 modules
+   :align: center
+   :alt:
+
+   CV32A6 v0.1.0 modules
+
+Connections between modules are illustrated in the following block diagram. FRONTEND, DECODE, ISSUE, EXECUTE, COMMIT and CONTROLLER are part of the pipeline. And CACHES implements the instruction and data caches and CSRFILE contains registers.
+
+.. figure:: ../images/CVA6_subsystems.png
+   :name: CVA6 subsystem
+   :align: center
+   :alt:
+
+   CV32A6 v0.1.0 pipeline and modules
+
+.. toctree::
+   :hidden:
+
+   cv32a6_frontend
+   cv32a6_execute

docs/04_cv32a6_design/source/embedded_csr.rst

@@ -0,0 +1 @@
+.. include:: ../../csr-from-ip-xact/embedded/embedded_csr.rst

docs/04_cv32a6_design/source/embedded_csr_list.rst

@@ -0,0 +1,11 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+
+.. include:: ../../csr-from-ip-xact/embedded/embedded_csr_list.rst

docs/04_cv32a6_design/source/embedded_functionality.rst

@@ -0,0 +1,23 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+.. _EMBEDDED_FUNCTIONALITY:
+
+
+Functionality
+=============
+
+.. toctree::
+   :hidden:
+
+   embedded_instructions
+   embedded_traps
+   embedded_CSRs
+   embedded_AXI
+   embedded_CVXIF

docs/04_cv32a6_design/source/embedded_instructions.rst

@@ -0,0 +1,11 @@
+..
+   Copyright 2023 Thales DIS France SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+
+.. include:: ../../01_cva6_user/RISCV_Instructions.rst

docs/04_cv32a6_design/source/embedded_intro.rst

@@ -0,0 +1,96 @@
+..
+   Copyright 2022 Thales DIS design services SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+.. _EMBEDDED_INTRO:
+
+
+Introduction
+=============
+
+The OpenHW Group uses `semantic versioning <https://semver.org/>`_ to describe the release status of its IP.
+This document describes the embedded configuration version of CVA6.
+This intends to be the first formal release of CVA6.
+
+CVA6 is a 6-stage in-order and single issue processor core which implements the RISC-V instruction set.
+CVA6 can be configured as a 32- or 64-bit core (RV32 or RV64), called CV32A6 or CV64A6.
+
+The objective of this document is to provide enough information to allow the RTL modification (by designers) and the RTL verification (by verificators).
+This document is not dedicated to CVA6 users looking for information to develop software like instructions or registers.
+
+The CVA6 architecture is illustrated in the following figure.
+
+.. figure:: ../images/ariane_overview.drawio.png
+   :name: CVA6 Architecute
+   :align: center
+   :alt:
+
+   CVA6 Architecture
+
+
+License
+-------
+
+| Copyright 2022 Thales
+| 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.
+
+
+Standards Compliance
+--------------------
+
+To ease the reading, the reference to these specifications can be implicit in the requirements below. For the sake of precision, the requirements identify the versions of RISC-V extensions from these specifications.
+
+* **[CVA6req]** “CVA6 requirement specification”, https://github.com/openhwgroup/cva6/blob/master/docs/specifications/cva6_requirement_specification.rst, HASH#767c465.
+* **[RVunpriv]** “The RISC-V Instruction Set Manual, Volume I: User-Level 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, Krste Asanović and John Hauser, RISC-V Foundation, December 4, 2021.
+* **[RVdbg]** “RISC-V External Debug Support, Document Version 0.13.2”, Editors Tim Newsome and Megan Wachs, RISC-V Foundation, March 22, 2019.
+* **[RVcompat]** “RISC-V Architectural Compatibility Test Framework”, https://github.com/riscv-non-isa/riscv-arch-test.
+* **[AXI]** AXI Specification, https://developer.arm.com/documentation/ihi0022/hc.
+* **[CV-X-IF]** Placeholder for the CV-X-IF coprocessor interface currently prepared at OpenHW Group; current version in https://docs.openhwgroup.org/projects/openhw-group-core-v-xif/.
+* **[OpenPiton]** “OpenPiton Microarchitecture Specification”, Princeton University, https://parallel.princeton.edu/openpiton/docs/micro_arch.pdf.
+
+CV32A6 is a standards-compliant 32-bit processor fully compliant with RISC-V specifications: [RVunpriv], [RVpriv] and [RVdbg] and passes [RVcompat] compatibility tests, as requested by [GEN-10] in [CVA6req].
+
+
+Documentation framework
+-----------------------
+
+The framework of this document is inspired by the Common Criteria. The Common Criteria for Information Technology Security Evaluation (referred to as Common Criteria or CC) is an international standard (ISO/IEC 15408) for computer security certification.
+
+Description of the framework:
+
+* Processor is split into module corresponding to the main modules of the design
+* Modules can contain several modules
+* Each module is described in a chapter, which contains the following subchapters: *Description*, *Functionalities*, *Architecture and Modules* and *Registers* (if any)
+* The subchapter *Description* describes the main features of the submodule, the interconnections between the current module and the others and the inputs/outputs interface.
+* The subchapter *Functionality* lists in details the module functionalities. Please avoid using the RTL signal names to explain the functionalities.
+* The subchapter *Architecture and Modules* provides a drawing to present the module hierarchy, then the functionalities covered by the module
+* The subchapter *Registers* specifies the module registers if any
+
+
+Contributors
+------------
+
+| Jean-Roch Coulon - Thales
+| Ayoub Jalali
+  (`[email protected] <mailto:[email protected]>`__)
+| Alae Eddine Ezzejjari
+  (`[email protected] <mailto:[email protected]>`__)
+
+[TO BE COMPLETED]
+

docs/04_cv32a6_design/source/embedded_overview.rst

@@ -0,0 +1,21 @@
+..
+   Copyright 2022 Thales DIS design services SAS
+   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   You may obtain a copy of the License at https://solderpad.org/licenses/
+
+   Original Author: Jean-Roch COULON - Thales
+
+.. _EMBEDDED_OVERVIEW:
+
+
+Overview
+========
+
+[TO BE COMPLETED]
+
+The CV32A6 v0.1.0 core is fully synthesizable. It has been designed mainly for ASIC designs, but FPGA synthesis is supported as well.
+
+For ASIC synthesis, the whole design is completely synchronous and uses positive-edge triggered flip-flops. The core occupies an area of about 80 kGE. The clock frequency can be more than 1GHz depending of technology.
+