Integrate CV32A6 Design Document and break out CVA6 APU (#1072)

docs/01_cva6_user/CVA6_user_guide.rst

@@ -0,0 +1,270 @@
+..
+   Copyright (c) 2023 OpenHW Group
+   Copyright (c) 2023 Thales DIS design services SAS
+
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+
+.. Level 1
+   =======
+
+   Level 2
+   -------
+
+   Level 3
+   ~~~~~~~
+
+   Level 4
+   ^^^^^^^
+
+.. _cva6_user_guide:
+
+OpenHW Group CVA6 User Manual
+=============================
+This is a template for the CVA6 user guide.
+
+Changelog
+---------
+We start filling in the Changelog after the first “official” release of the user manual, at the end of step 2.
+
+.. future file beak
+
+Introduction
+============
+
+License
+-------
+Copyright 2022 OpenHW Group and Thales
+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.
+
+Work In Progress
+----------------
+The current limitation of documentation on CVA6 is well understood.
+Rather than regretting this; the reader is encouraged to contribute to it to make CVA6 an even better core.
+This document is a work in progress and the team currently drafting it focuses on its use for the “step 1” verification of the project.
+
+Target Audience
+---------------
+The CVA6 user manual targets:
+* SW programmers
+* HW designers who integrate CVA6 into a SoC/ASIC/FPGA
+* Architects who design a coprocessor for the CV-X-IF interface and who need to create SW to use it
+* HW designers who synthetize/place&route/verify a design that embeds CVA6
+* Verification engineers involved in the OpenHW Group’s CVA6 project who use this manual as a reference.
+
+The user guide does not target people who dig into CVA6 design. No internal mechanisms are described here, except if the user has some sort of control on it; there is a separate design specification for this purpose.
+
+CVA6 Overview
+--------------
+Jérôme will write it (mainly reusing the requirements specification).
+CVA6 is an application core…
+Scope of the IP…
+We target all versions of the core
+
+Compliance to Standards and Specifications
+------------------------------------------
+Reuse the references from the requirement specification (Jérôme can do it).
+CVA6 is a RISC-V processor core. It is compatible with the following specifications:
+(Insert there the list of RISC-V, AMBA, CV-X-IF, TRI… specifications.
+
+.. future file beak
+
+Programmer’s View
+=================
+In each section, we must make clear when a feature is variable upon parameters
+
+RISC-V Extensions
+-----------------
+Need for step1 verification.
+As CVA6 implements specified RISC-V extensions, this will be a short section, where we mention which extensions are always present or optional.
+
+RISC-V Privileges
+-----------------
+Need for step1 verification.
+We identify the supported RISC-V privileges
+
+RISC-V Virtual Memory
+---------------------
+Need for step1 verification (MMU by 10xEngineers).
+We identify the supported RISC-V virtual memories
+
+Memory Alignment
+----------------
+CVA6 does not support non-aligned memory accesses.
+
+.. future file beak
+
+Custom RISC-V instructions
+==========================
+Desired for step2 verification.
+This is mostly for FENCE.T.
+
+.. future file beak
+
+PMA
+===
+Gap for step1 verification. Reuse DVplan from CV32E40S? Mike will reach out to some people who could help.
+
+.. future file beak
+
+PMP
+===
+Gap for step1 verification. Reuse DVplan from CV32E40S? Mike will reach out to some people who could help.
+Refer to RISC-V specs and focus on the parameters (regions, granularity)
+
+.. future file beak
+
+Traps, Interrupts, Exceptions
+=============================
+Gap for step1 verification. Reuse DVplan from E4? Jean-Roch will check with André. Mike will reach out to some people who could help.
+We expect this section to be 1 page.
+
+.. future file beak
+
+Compiler command lines
+======================
+Add GCC and LLVM command lines, compiler versions, options that work well with CVA6.
+Going further to fine tune the compiler options for performance, benchmarking, code density is not the scope here and would call for a white paper.
+
+.. future file beak
+
+RISC-V Instructions
+===================
+URGENT NEED FOR VERIFICATION. TSS will lead.
+Jean-Roch suggests to reuse https://github.com/openhwgroup/cva6/blob/master/docs/03_cv32a6_design/source/cv32a6_isa.rst.
+Do we want to have this level of details in the user doc?
+
+.. future file beak
+
+Control and Status Registers (CV32A6)
+=====================================
+URGENT NEED FOR VERIFICATION. TSS will lead.
+The CSR table generated by JADE (standalone file transferred from the design document).
+Jea-Roch will ask Tamas if he can provide TSS with an evaluation license to maintain the file for step 1.
+
+.. future file beak
+
+Control and Status Registers (CV64A6)
+=====================================
+CSR table (CV64A6)
+The CSR table generated by JADE (standalone file. Does it already exist?).
+
+.. future file beak
+
+CSR cache control
+=================
+Which cache controls are available to the user, what they do, how to use them.
+Typical usage can also be mentioned.
+
+.. future file beak
+
+CSR performance counters control
+================================
+Focus on the way to use the performance counters.
+
+.. future file beak
+
+Parameters and Configuration
+============================
+
+Parameters
+----------
+We start with a table of parameters as they have an impact on almost all subsequent sections.
+Suggestion to use the SystemVerilog names of the parameters (instead of another convention) as a reference. We need to make a link between parameters and their impact on the supported extensions.
+Jean-Roch said he has something.
+
+Configurations
+--------------
+A configuration is a fixed set of parameters.
+We list the parameters of the configuration for which verification activities have started.
+Give step 1 configuration (Jean-Roch?)
+
+Interfaces
+----------
+List of interface signals
+As in the RTL files.
+
+AXI Interface
+~~~~~~~~~~~~~
+Need for step1 verification. Already written by MU Electronics.
+Focus on the features used by the CVA6 and refer to ARM documentation for the AXI specification (e.g. do not draw the standard chronogram).
+Features:
+* See requirement specification
+* Atomic transactions
+* “USER” bus width extension
+* Transaction ordering
+
+Debug Interface
+~~~~~~~~~~~~~~~
+Desired for step1 verification, but we can likely reuse an E4 DVplan.
+Remember: the debug module (DTM) is not in the scope, so we focus on the debug interrupt.
+How to use the interface (HW/SW). We can refer to RISC-V specifications.
+If the section is too heavy, promote it to a separate chapter.
+
+Interrupt Interface
+~~~~~~~~~~~~~~~~~~~
+Desired for step1 verification, but we can likely reuse an E4 DVplan.
+How to use the interface (HW/SW). We can refer to RISC-V specifications.
+If the section is too heavy, promote it to a separate chapter.
+
+TRI Interface
+~~~~~~~~~~~~~
+Refer to OpenPiton documents.
+
+.. future file beak
+
+Core Integration
+================
+
+RTL Integration
+---------------
+How to integrate CVA6 into a core complex/SoC
+Instantiation template
+As in https://docs.openhwgroup.org/projects/cv32e40p-user-manual/integration.html#instantiation-template
+Specific constructs
+Do we have specific constructs that we should mention for the implementation team:
+* Non-reset signals, if any
+* Internally controlled asynchronous reset (“SW reset”), if any
+* Multi-cycle paths
+* Clock gating
+
+ASIC Specific Guidelines
+------------------------
+
+Suggested content:
+~~~~~~~~~~~~~~~~~~
+* How to handle the RAM cells for DFT.
+* Typical critical paths in ASIC and suggestions for optimizations (e.g. suggestions for places where to apply regioning/partitioning…)
+* We can also have typical command lines / settings for various ASIC tools
+
+FPGA specific guidelines
+------------------------
+Desired for step1 (we expect prototyping at this stage).
+
+Suggested content:
+~~~~~~~~~~~~~~~~~~
+* Typical critical paths in FPGA and suggestions for optimizations
+* We can also have typical command lines / settings for various FPGA tools
+
+.. future file beak
+
+CV-X-IF Interface and Coprocessor
+=================================
+
+CV-X-IF interface specification
+-------------------------------
+Need to step1 verification. TSS/Guillaume will do.
+Refer to the CV-X-IF specification, mention the 3 supported protocol interfaces, identify the CVA6 specific features.
+
+How to use CV-X-IF with CVA6
+----------------------------
+We don’t commit yet to write this section. We expect the audience to be power users.
+Use CVA6 without CV-X-IF interface
+Use CVA6 with CV-X-IF interface
+How to design a coprocessor for the CV-X-IF interface
+How to program a CV-X-IF coprocessor
+

docs/01_cva6_user/CVA6_user_guide.txt

@@ -0,0 +1,157 @@
+OpenHW Group CVA6 User Manual
+This is a template for the CVA6 user guide.
+We start in Google Docs for easier interaction. When we have an agreed upon template, we’ll convert it into several reST files targetting ReadTheDocs.
+Blue highlights: source of the section.
+
+
+---------- next file ----------
+Changelog
+We start filling in the Changelog after the first “official” release of the user manual, at the end of step 2.
+---------- next file ----------
+Introduction
+License
+Copyright 2022 OpenHW Group and Thales
+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.
+Work in progress
+The current limitation of documentation on CVA6 is well understood. Rather than regretting this; the reader is encouraged to contribute to it to make CVA6 an even better core.
+This document is a work in progress and the team currently drafting it focuses on its use for the “step 1” verification of the project.
+Targetted audience
+The CVA6 user manual targets:
+* SW programmers
+* HW designers who integrate CVA6 into a SoC/ASIC/FPGA
+* Architects who design a coprocessor for the CV-X-IF interface and who need to create SW to use it
+* HW designers who synthetize/place&route/verify a design that embeds CVA6
+* Verification engineers involved in the OpenHW Group’s CVA6 project who use this manual as a reference.
+The user guide does not target people who dig into CVA6 design. No internal mechanisms are described here, except if the user has some sort of control on it; there is a separate design specification for this purpose.
+CVA6 overview
+Jérôme will write it (mainly reusing the requirements specification).
+CVA6 is an application core…
+Scope of the IP…
+We target all versions of the core
+Compliance to standards and specifications
+Reuse the references from the requirement specification (Jérôme can do it).
+CVA6 is a RISC-V processor core. It is compatible with the following specifications:
+(Insert there the list of RISC-V, AMBA, CV-X-IF, TRI… specifications.
+---------- next file ----------
+Programmer’s view
+In each section, we must make clear when a feature is variable upon parameters
+RISC-V extensions
+Need for step1 verification.
+As CVA6 implements specified RISC-V extensions, this will be a short section, where we mention which extensions are always present or optional.
+RISC-V privileges
+Need for step1 verification.
+We identify the supported RISC-V privileges
+RISC-V virtual memory
+Need for step1 verification (MMU by 10xEngineers).
+We identify the supported RISC-V virtual memories
+Memory alignment
+CVA6 does not support non-aligned memory accesses.
+---------- next file ----------
+Custom RISC-V instructions
+Desired for step2 verification.
+This is mostly for FENCE.T.
+---------- next file ----------
+PMA
+Gap for step1 verification. Reuse DVplan from CV32E40S? Mike will reach out to some people who could help.
+---------- next file ----------
+PMP
+Gap for step1 verification. Reuse DVplan from CV32E40S? Mike will reach out to some people who could help.
+Refer to RISC-V specs and focus on the parameters (regions, granularity)
+---------- next file ----------
+Traps, interrupts, exceptions
+Gap for step1 verification. Reuse DVplan from E4? Jean-Roch will check with André. Mike will reach out to some people who could help.
+We expect this section to be 1 page.
+---------- next file ----------
+Compiler command lines
+Add GCC and LLVM command lines, compiler versions, options that work well with CVA6.
+Going further to fine tune the compiler options for performance, benchmarking, code density is not the scope here and would call for a white paper.
+---------- next file ----------
+RISC-V Instructions
+URGENT NEED FOR VERIFICATION. TSS will lead.
+Jean-Roch suggests to reuse https://github.com/openhwgroup/cva6/blob/master/docs/03_cv32a6_design/source/cv32a6_isa.rst. Do we want to have this level of details in the user doc?
+---------- next file ----------
+CSR
+---------- next file ----------
+CSR table (CV32A6)
+URGENT NEED FOR VERIFICATION. TSS will lead.
+The CSR table generated by JADE (standalone file transferred from the design document).
+Jea-Roch will ask Tamas if he can provide TSS with an evaluation license to maintain the file for step 1.
+---------- next file ----------
+CSR table (CV64A6)
+The CSR table generated by JADE (standalone file. Does it already exist?).
+---------- next file ----------
+CSR cache control
+Which cache controls are available to the user, what they do, how to use them.
+Typical usage can also be mentioned.
+CSR performance counters control
+Focus on the way to use the performance counters.
+---------- next file ----------
+Parameters and configuration
+Parameters
+We start with a table of parameters as they have an impact on almost all subsequent sections.
+Suggestion to use the SystemVerilog names of the parameters (instead of another convention) as a reference. We need to make a link between parameters and their impact on the supported extensions.
+Jean-Roch said he has something.
+---------- next file ----------
+Configurations
+A configuration is a fixed set of parameters.
+We list the parameters of the configuration for which verification activities have started.
+Give step 1 configuration (Jean-Roch?)
+---------- next file ----------
+Interfaces
+List of interface signals
+As in the RTL files.
+AXI interface
+Need for step1 verification. Already written by MU Electronics.
+Focus on the features used by the CVA6 and refer to ARM documentation for the AXI specification (e.g. do not draw the standard chronogram).
+Features:
+* See requirement specification
+* Atomic transactions
+* “USER” bus width extension
+* Transaction ordering
+Debug interface
+Desired for step1 verification, but we can likely reuse an E4 DVplan.
+Remember: the debug module (DTM) is not in the scope, so we focus on the debug interrupt.
+How to use the interface (HW/SW). We can refer to RISC-V specifications.
+If the section is too heavy, promote it to a separate chapter.
+Interrupt interface
+Desired for step1 verification, but we can likely reuse an E4 DVplan.
+How to use the interface (HW/SW). We can refer to RISC-V specifications.
+If the section is too heavy, promote it to a separate chapter.
+TRI interface
+Refer to OpenPiton documents.
+---------- next file ----------
+Core integration
+RTL level
+How to integrate CVA6 into a core complex/SoC
+Instantiation template
+As in https://docs.openhwgroup.org/projects/cv32e40p-user-manual/integration.html#instantiation-template
+Specific constructs
+Do we have specific constructs that we should mention for the implementation team:
+* Non-reset signals, if any
+* Internally controlled asynchronous reset (“SW reset”), if any
+* Multi-cycle paths
+* Clock gating
+ASIC specific guidelines
+Suggested content:
+* How to handle the RAM cells for DFT.
+* Typical critical paths in ASIC and suggestions for optimizations (e.g. suggestions for places where to apply regioning/partitioning…)
+* We can also have typical command lines / settings for various ASIC tools
+FPGA specific guidelines
+Desired for step1 (we expect prototyping at this stage).
+Suggested content:
+* Typical critical paths in FPGA and suggestions for optimizations
+* We can also have typical command lines / settings for various FPGA tools
+---------- next file ----------
+CV-X-IF interface and coprocessor
+CV-X-IF interface specification
+Need to step1 verification. TSS/Guillaume will do.
+Refer to the CV-X-IF specification, mention the 3 supported protocol interfaces, identify the CVA6 specific features.
+How to use CV-X-IF with CVA6
+We don’t commit yet to write this section. We expect the audience to be power users.
+Use CVA6 without CV-X-IF interface
+Use CVA6 with CV-X-IF interface
+How to design a coprocessor for the CV-X-IF interface
+How to program a CV-X-IF coprocessor
+---------- next file ----------

docs/01_cva6_user/index.rst

@@ -1,7 +1,8 @@
 ..
-   Copyright (c) 2022 OpenHW Group
+   Copyright (c) 2023 OpenHW Group
+   Copyright (c) 2023 Thales DIS design services SAS
 
-   Licensed under the Solderpad Hardware Licence, Version 2.0 (the "License");
+   Licensed under the Solderpad Hardware Licence, Version 2.1 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
@@ -13,36 +14,15 @@
    See the License for the specific language governing permissions and
    limitations under the License.
 
-   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.0
+   SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
 
-OpenHW Group CVA6 User Manual
-================================
-Editor: **Florian Zaruba**
-`florian@openhwgroup.org <mailto:florian@openhwgroup.org?subject=CVA6%20User%20Manual>`__
+CVA6 User Manual
+================
+Editor: **Jerome Quevremont**
+`jerome.quevremont@thalesgroup.com <mailto:jerome.quevremont@thalesgroup.com?subject=CVA6%20User%20Manual>`__
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   intro
-   pcgen_stage
-   if_stage
-   id_stage
-   issue_stage
-   ex_stage
-   commit_stage
-   cva6_soc
-   cva6_testharness
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-Documentation
--------------
-
-The documentation is re-generated on pushes to master.
-When contributing to the project please consider the [contribution guide](https://github.com/openhwgroup/cva6/blob/master/CONTRIBUTING.md).
+   CVA6_user_guide

docs/02_cva6_requirements/cva6_requirements_specification.rst

@@ -1,6 +1,8 @@
 ===============================
 CVA6 Requirement Specification
 ===============================
+Editor: **Jerome Quevremont**
+`jerome.quevremont@thalesgroup.com <mailto:jerome.quevremont@thalesgroup.com?subject=CVA6%20User%20Manual>`__
 
 Revision 1.0.1
 

docs/03_cva6_design/index.rst

@@ -0,0 +1,46 @@
+..
+   Copyright (c) 2022 OpenHW Group
+
+   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
+
+CVA6 Design Document
+====================
+Editor: **Florian Zaruba**
+`florian@openhwgroup.org <mailto:florian@openhwgroup.org?subject=CVA6%20Design%20Document>`__
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   intro
+   pcgen_stage
+   if_stage
+   id_stage
+   issue_stage
+   ex_stage
+   commit_stage
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Documentation
+-------------
+
+The documentation is re-generated on pushes to master.
+When contributing to the project please consider the [contribution guide](https://github.com/openhwgroup/cva6/blob/master/CONTRIBUTING.md).

docs/04_cv32a6_design/source/cv32a6_csr.rst

@@ -11,6 +11,36 @@
 CV32A6_CSR programmers view
 ###########################
 
+CV32A6 does not implement all control and status registers specified in the RISC-V privileged specifications,
+but is limited to the registers that were needed for a 32-bit application core.
+This keeps the footprint of the core as low as possible and avoid any overhead that we do not explicitly need.
+
+The **Parameter** column identifies those CSRs that are dependent on the value
+of specific compile/synthesis parameters. If these parameters are not set as
+indicated in :numref:`Control and Status Register Map` then the associated CSR is not implemented.  If the
+parameter column is empty then the associated CSR is always implemented.
+
+The **Privilege** column indicates the access mode of a CSR.  The first letter
+indicates the lowest privilege level required to access the CSR.  Attempts to
+access a CSR with a higher privilege level than the core is currently running
+in will throw an illegal instruction exception.  This is largely a moot point
+for the CV32E40P as it only supports machine and debug modes.  The remaining
+letters indicate the read and/or write behavior of the CSR when accessed by
+the indicated or higher privilge level:
+
+* **RW**: CSR is **read-write**.  That is, CSR instructions (e.g. csrrw) may
+  write any value and that value will be returned on a subsequent read (unless
+  a side-effect causes the core to change the CSR value).
+
+* **RO**: CSR is **read-only**.  Writes by CSR instructions raise an illegal
+  instruction exception.
+
+Writes of a non-supported value to **WLRL** bitfields of a **RW** CSR do not result in an illegal
+instruction exception. The exact bitfield access types, e.g. **WLRL** or **WARL**, can be found in the RISC-V
+privileged specification.
+
+Reads or writes to a CSR that is not implemented will result in an illegal instruction exception.
+
 .. tip::
   This section was auto-generated by **Register Manager** from `Jade Design Automation <https://jade-da.com/>`_. |logo|
 

docs/04_cv32a6_design/source/index.rst

@@ -17,6 +17,8 @@
 
 CV32A6 Design Document
 ======================
+Editor: **Jean Roch Coulon**
+`jean-roch.coulon@thalesgroup.com <mailto:jean-roch.coulon@thalesgroup.com?subject=CV32A6%20Design%20Document>`__
 
 .. toctree::
    :maxdepth: 3

docs/05_cva6_apu/cva6_apu.rst

@@ -1,5 +1,5 @@
-CVA6 System on Chip (SoC)
-=========================
+CVA6 APU
+========
 
 Memory Map
 ----------

docs/05_cva6_apu/cva6_testharness.md

@@ -0,0 +1,165 @@
+# CVA6 Testharness
+
+`ariane_testharness` is the module where all the masters and slaves have been connected with the axi crossbar.There are two masters and ten slaves in this module.Their names and interfaces have been mentioned in the table below.
+
+| Slaves      | Interfaces  | Masters     | Interfaces  |  
+| ----------- | ----------- | ----------- | ----------- |
+| DRAM        | master[0]   | ariane      | slave[0]    |
+| GPIO        | master[1]   | debug       | slave[1]    |
+| Ethernet    | master[2]   |             |             |
+| SPI         | master[3]   |             |             |
+| Timer       | master[4]   |             |             |
+| UART        | master[5]   |             |             |
+| PLIC        | master[6]   |             |             |
+| CLINT       | master[7]   |             |             |
+| ROM         | master[8]   |             |             |
+| Debug       | master[9]   |             |             |
+
+
+ The following block diagram shows the connections of the slaves and masters in the `ariane_testharness` module.
+
+![ariane_testharness](_static/test_harness.png "ariane_testharness")
+
+## Ariane
+
+The `ariane` core is instantiated as `i_ariane` in `ariane_testharness` module. It is acting as a master in `ariane_testharness`.  
+The following is the diagram of the `ariane` module along with its inputs/outputs ports.
+
+![ariane](_static/ariane.png "ariane")
+
+`ipi`, `irq` and `time_irq` are being sent to this module from the `ariane_testharness` module.  
+The  AXI request and response signals that are being passed from the `ariane_testharness` to `ariane` module are the following:
+
+> `.axi_req_o           ( axi_ariane_req      ),`  
+`.axi_resp_i           ( axi_ariane_resp     )`
+
+In the `ariane_testharness` module, `axi_ariane_req` and `axi_ariane_resp` structs are being linked with the `slave[0]` (AXI_BUS interface) in a way that the information of `axi_ariane_req` is being passed to the `slave[0]` and the information from the `slave[0]` is being passed to the `axi_ariane_resp` struct. The following compiler directives are being used for this purpose.
+
+> `AXI_ASSIGN_FROM_REQ(slave[0], axi_ariane_req)`
+ `AXI_ASSIGN_TO_RESP(axi_ariane_resp, slave[0])`
+
+`Rvfi_o` is the output of `ariane` and it will go into the `rvfi_tracer` module.
+
+## Debug
+
+### Master
+
+`axi_adapter` is acting as a master for the debug module.  
+The following is the diagram of the `axi_adapter` module along with its signals.
+
+![axi_adapter](_static/axi_adapter.png "axi_adapter")
+
+The AXI request and response that signals are being passed from the test_harness module are the following:  
+
+> `.axi_req_o             ( dm_axi_m_req              )`  
+`.axi_resp_i            ( dm_axi_m_resp             )`
+
+`Slave[1]` is the interface of AXI_BUS and it actually acts as a master for axi_protocol.  
+
+The `dm_axi_m_req` and `dm_axi_m_resp` are being linked with the slave[1] AXI_BUS interface in this way that the requests signals of the `dm_axi_m_req` are being passed to the `slave[1]` and the response signals from the  `slave[1]` are being passed to the `dm_axi_m_resp` struct.
+
+> `AXI_ASSIGN_FROM_REQ(slave[1], dm_axi_m_req)`
+ `AXI_ASSIGN_TO_RESP(dm_axi_m_resp, slave[1])`
+
+### Slave
+
+This is the memory of debug and `axi2mem` converter is used whenever a read or write request is made to memory by the master.  
+`axi2mem` module simply waits for the ar_valid or aw_valid of the master (actual slave) interface and then passes the req_o, we_o, addr_o, be_o, user_o signals and data_o to the memory and will receive the data_i and user_i from the memory.
+
+![axi2mem](_static/axi2mem.png "axi2mem")
+
+The memory is has been instantiated in the `dm_top` module and the hierarchy is as follows:
+
+![dm_top_&_dm_mem](_static/dm_top_slave.png "dm_top_&_dm_mem")
+
+## CLINT
+
+Clint is a slave in this SoC. The signals of the `clint` module are as follows:
+
+![clint](_static/clint.png "clint")
+
+`ipi_o` (inter-processing interrupt) and `timer_irq_o` (timer_interrupt request) are generated from the `clint` module and are the inputs of the ariane core.  
+This module interacts with the axi bus interface through the following assignments:
+
+> `AXI_ASSIGN_TO_REQ(axi_clint_req, master[ariane_soc::CLINT])`
+
+This compiler directive is used to transfer the request signals of the master via the interface mentioned as `master[ariane_soc::CLINT]` to the struct `axi_clint_req`.
+
+> `AXI_ASSIGN_FROM_RESP(master[ariane_soc::CLINT], axi_clint_resp)`
+
+This compiler directive is used to assign the response of the slave (in this case `clint` module) from the  
+`Axi_clint_resp` struct to the interface `master[ariane_soc::CLINT]`.
+
+## Bootrom
+
+`axi2mem` module is used to communicate with `bootrom` module. The signals of this memory have been shown in the diagram below:
+
+![bootrom](_static/bootrom.png "bootrom")
+
+Bootrom is pre-initialized with `ROM_SIZE = 186`.
+
+## SRAM
+
+The complete sequence through which a request to SRAM is transferred is as follows:
+
+![sequence](_static/dram.png)
+
+`dram` and `dram_delayed` are two AXI_BUS interfaces.
+The slave modport of AXI_BUS interface for `Master[DRAM]` has been linked with `axi_riscv_atomics` module and the request of the master has been passed to `dram` interface (another instantiation of interface of AXI_BUS). All this is for the exclusive accesses and no burst is supported in this exclusive access.  
+`dram` and `dram_delayed` interfaces have also been passed to `axi_delayer_intf` module as a slave modport and master modport of the AXI_BUS interface, respectively. The `axi_delayer_intf` module is used to introduce the delay.  
+`dram_delayed` is also passed to the `axi2mem` module as a slave modport of AXI_BUS interface. `axi2mem` module with `dram_delayed` as an AXI_Bus interface will interact with SRAM.  
+SRAM is a word addressable memory with the signals as follows:
+
+![sram](_static/sram.png "sram")
+
+## GPIO
+
+GPIO is not implemented, error slave has been added in place of it.
+
+## UART
+
+There are two signals for the `apb_uart` module in the `ariane_testharness`, namely `tx` and `rx` for transmitting and receiving the data.  
+`axi2apb_64_32`, module has been used to convert the axi protocol five channel signals to a single channel apb signals. The `axi2apb_64_32` module has been used between AXI_BUS and `apb_uart module`.  
+The signals of the `apb_uart` module have been shown in the diagram below:
+
+![apb_uart](_static/apb_uart.png "apb_uart")
+
+Only the signals related to the test_harness have been shown in the above diagram.
+
+## PLIC
+
+PLIC is a slave in this SoC. The hiearchy through which the request is propagated to the plic_top module is as follows:
+
+![plic_hierarchy](_static/plic.png )
+
+`axi2apb_64_32` has been used to convert all the plic axi signals into apb signals.  
+apb_to_reg is used to assign the apb signals to the `reg_bus` interface which basically communicates with the `plic_top` module. In `apb_to_reg` module, the logical `AND` of `psel` and `penable` signals of apb makes the `valid` signal of `reg_bus` interface.  
+The signals of the `plic_top` have been shown below:
+
+![plic_top](_static/plic_top.png "plic_top")
+
+## Timer
+
+The `axi2apb_64_32` module has been used to convert all the timer axi signals into  timer apb signals.The diagram of the apb_timer is as follows.
+
+![apb_timer](_static/timer.png "apb_timer")
+
+The signals of apb protocol have been shown in the form of `apb_timer_req` and `apb_timer_resp` in the above diagram.
+
+## Ethernet
+
+Ethernet is a slave in this testharness.
+
+Ethernet support has not been added in the 'ariane_testharness' at this time. For any read or write request from the master to this module is returned with
+
+> `"ethernet.b_resp = axi_pkg::RESP_SLVERR"`
+
+where,
+> `"localparam RESP_SLVERR = 2'b10;" in axi_pkg`
+
+ which shows `"Slave error"`. It is used when the access has reached the slave successfully, but the slave wishes to return an error condition to the originating master."
+
+## SPI
+
+ SPI is a slave in this testharness.
+  Support of the of SPI protocol is present in the SoC, but at this time it is turned off, as the `.spi_clk_o ( )`,`.spi_mosi  ( )`,`.spi_miso  ( )` ,and `.spi_ss    ( )` signals of SPI have been left open in the `ariane_testharness` module. Any read or write request from the master to this module is returned with `"Slave error"`.

docs/05_cva6_apu/index.rst

@@ -0,0 +1,29 @@
+..
+   Copyright (c) 2023 OpenHW Group
+   Copyright (c) 2023 Thales DIS design services SAS
+
+   Licensed under the Solderpad Hardware Licence, Version 2.1 (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.1
+
+CVA6 APU
+========
+Editor: **Florian Zaruba**
+`florian@openhwgroup.org <mailto:florian@openhwgroup.org?subject=CVA6%20User%20Manual>`__
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   cva6_apu
+   cva6_testharness

docs/index.rst

@@ -54,14 +54,20 @@ One of the key attributes of this document is to specify the feature set of spec
 This document focuses on _what_ the CVA6 does, without detailed consideration of _how_ a specific requirement is implemented.
 The target audience of this document is current and existing members of the OpenHW Group who wish to participate in the definition of future cores based on the CVA6.
 
-The :doc:`CV32A6 Design Specification <03_cv32a6_design/source/index>` describes in detail the **CV32A6**, the first production quality 32-bit application processor derived from the CVA6.
+The :doc:`CVA6 Design Document <03_cva6_design/index>` describes in detail the **CVA6**, the code base that can be used to compile/synthesize a specific core instance (e.g. cv32a6).
+
+The :doc:`CV32A6 Design Document <04_cv32a6_design/source/index>` describes in detail the **CV32A6**, a specific core based on the CVA6 and the first production quality 32-bit application processor derived from the CVA6.
 The primary audience for this documentation are design and verification engineers working to bring the CV32A6 to TRL-5.
 
+The :doc:`CVA6 APU <05_cva6_apu/index>` describes an Application Processor Unit built around the CVA6.
+
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    01_cva6_user/index.rst
    02_cva6_requirements/cva6_requirements_specification.rst
-   03_cv32a6_design/source/index.rst
+   03_cva6_design/index.rst
+   04_cv32a6_design/source/index.rst
+   05_cva6_apu/index.rst