github-mirrors/cva6
1
0
Fork 0
mirror of https://github.com/openhwgroup/cva6.git synced 2025-04-22 13:17:41 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Individual files for each chapter of CVA6 User Manual (#1076)

Browse source
This commit is contained in:
Mike Thompson 2023-02-22 03:22:20 -05:00 • committed by GitHub
parent f46c5b1acc
commit 44817bda22
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 528 additions and 567 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/01_cva6_user/CSR_Cache_Control.rst Normal file
View file

@ -0,0 +1,25 @@
..
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_csr_cache_control:
CSR cache control
=================
Which cache controls are available to the user, what they do, how to use them.
Typical usage can also be mentioned.

24
docs/01_cva6_user/CSR_Performance_Counters.rst Normal file
View file

@ -0,0 +1,24 @@
..
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_csr_performance_counters:
CSR performance counters control
================================
Focus on the way to use the performance counters.

26
docs/01_cva6_user/CV32A6_Control_Status_Registers.rst Normal file
View file

@ -0,0 +1,26 @@
..
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
^^^^^^^
.. _cv32a6_control_status_registers:
CV32A6 Control and Status Registers
===================================
URGENT NEED FOR VERIFICATION. TSS will lead.
The CSR table generated by JADE (standalone file transferred from the design document).
Jean-Roch will ask Tamas if he can provide TSS with an evaluation license to maintain the file for step 1.

25
docs/01_cva6_user/CV64A6_Control_Status_Registers.rst Normal file
View file

@ -0,0 +1,25 @@
..
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
^^^^^^^
.. _cv64a6_control_status_registers:
CV64A6 Control and Status Registers
===================================
CSR table (CV64A6)
The CSR table generated by JADE (standalone file. Does it already exist?).

242
docs/01_cva6_user/CVA6_user_guide.rst
View file

@ -26,245 +26,3 @@ 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

157
docs/01_cva6_user/CVA6_user_guide.txt
View file

@ -1,157 +0,0 @@
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 ----------

36
docs/01_cva6_user/CVX_Interface_Coprocessor.rst Normal file
View file

@ -0,0 +1,36 @@
..
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_cvx_interface_coprocessor:
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

25
docs/01_cva6_user/Compiler_Command_Lines.rst Normal file
View file

@ -0,0 +1,25 @@
..
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_compiler_command_lines:
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.

53
docs/01_cva6_user/Core_Integration.rst Normal file
View file

@ -0,0 +1,53 @@
..
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_core_integration:
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

25
docs/01_cva6_user/Custom_Instructions.rst Normal file
View file

@ -0,0 +1,25 @@
..
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_custom_instructions:
Custom RISC-V instructions
==========================
Desired for step2 verification.
This is mostly for FENCE.T.

63
docs/01_cva6_user/Introduction.rst Normal file
View file

@ -0,0 +1,63 @@
..
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_introduction:
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.

24
docs/01_cva6_user/PMA.rst Normal file
View file

@ -0,0 +1,24 @@
..
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_pma:
PMA
===
Gap for step1 verification. Reuse DVplan from CV32E40S? Mike will reach out to some people who could help.

25
docs/01_cva6_user/PMP.rst Normal file
View file

@ -0,0 +1,25 @@
..
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_pmp:
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)

67
docs/01_cva6_user/Parameters_Configuration.rst Normal file
View file

@ -0,0 +1,67 @@
..
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_parameters_configuration:
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.

43
docs/01_cva6_user/Programmer_View.rst Normal file
View file

@ -0,0 +1,43 @@
..
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_programmers_view:
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.

26
docs/01_cva6_user/RISCV_Instructions.rst Normal file
View file

@ -0,0 +1,26 @@
..
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_riscv_instructions:
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?

25
docs/01_cva6_user/Traps_Interrupts_Exceptions.rst Normal file
View file

@ -0,0 +1,25 @@
..
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_traps_interrupts_exceptions:
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.

16
docs/01_cva6_user/index.rst
View file

@ -19,10 +19,24 @@
CVA6 User Manual
================
Editor: **Jerome Quevremont**
`jerome.quevremont@thalesgroup.com <mailto:jerome.quevremont@thalesgroup.com?subject=CVA6%20User%20Manual>`__
.. toctree::
:maxdepth: 2
:caption: Contents:
CVA6_user_guide
Introduction
Programmer_View
Custom_Instructions
PMA
PMP
Traps_Interrupts_Exceptions
Compiler_Command_Lines
RISCV_Instructions
CV32A6_Control_Status_Registers
CV64A6_Control_Status_Registers
CSR_Cache_Control
CSR_Performance_Counters
Parameters_Configuration
Core_Integration
CVX_Interface_Coprocessor

1
docs/02_cva6_requirements/cva6_requirements_specification.rst
View file

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

165
docs/03_cva6_design/cva6_testharness.md
View file

@ -1,165 +0,0 @@
# 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"`.

2
docs/04_cv32a6_design/source/cv32a6_csr.rst
View file

@ -17,7 +17,7 @@ This keeps the footprint of the core as low as possible and avoid any overhead t
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
indicated in **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