diff --git a/docs/01_cva6_user/CSR_Cache_Control.rst b/docs/01_cva6_user/CSR_Cache_Control.rst new file mode 100644 index 000000000..451619864 --- /dev/null +++ b/docs/01_cva6_user/CSR_Cache_Control.rst @@ -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. + diff --git a/docs/01_cva6_user/CSR_Performance_Counters.rst b/docs/01_cva6_user/CSR_Performance_Counters.rst new file mode 100644 index 000000000..1798c9a2b --- /dev/null +++ b/docs/01_cva6_user/CSR_Performance_Counters.rst @@ -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. + diff --git a/docs/01_cva6_user/CV32A6_Control_Status_Registers.rst b/docs/01_cva6_user/CV32A6_Control_Status_Registers.rst new file mode 100644 index 000000000..a7224b258 --- /dev/null +++ b/docs/01_cva6_user/CV32A6_Control_Status_Registers.rst @@ -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. + diff --git a/docs/01_cva6_user/CV64A6_Control_Status_Registers.rst b/docs/01_cva6_user/CV64A6_Control_Status_Registers.rst new file mode 100644 index 000000000..c427fd4f1 --- /dev/null +++ b/docs/01_cva6_user/CV64A6_Control_Status_Registers.rst @@ -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?). + diff --git a/docs/01_cva6_user/CVA6_user_guide.rst b/docs/01_cva6_user/CVA6_user_guide.rst index 85f608770..b4700643c 100644 --- a/docs/01_cva6_user/CVA6_user_guide.rst +++ b/docs/01_cva6_user/CVA6_user_guide.rst @@ -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 - diff --git a/docs/01_cva6_user/CVA6_user_guide.txt b/docs/01_cva6_user/CVA6_user_guide.txt deleted file mode 100644 index 0868e6a0b..000000000 --- a/docs/01_cva6_user/CVA6_user_guide.txt +++ /dev/null @@ -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 ---------- \ No newline at end of file diff --git a/docs/01_cva6_user/CVX_Interface_Coprocessor.rst b/docs/01_cva6_user/CVX_Interface_Coprocessor.rst new file mode 100644 index 000000000..25fb716f5 --- /dev/null +++ b/docs/01_cva6_user/CVX_Interface_Coprocessor.rst @@ -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 + diff --git a/docs/01_cva6_user/Compiler_Command_Lines.rst b/docs/01_cva6_user/Compiler_Command_Lines.rst new file mode 100644 index 000000000..46ab2dcb6 --- /dev/null +++ b/docs/01_cva6_user/Compiler_Command_Lines.rst @@ -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. + diff --git a/docs/01_cva6_user/Core_Integration.rst b/docs/01_cva6_user/Core_Integration.rst new file mode 100644 index 000000000..c22920c07 --- /dev/null +++ b/docs/01_cva6_user/Core_Integration.rst @@ -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 + diff --git a/docs/01_cva6_user/Custom_Instructions.rst b/docs/01_cva6_user/Custom_Instructions.rst new file mode 100644 index 000000000..d06de1d9e --- /dev/null +++ b/docs/01_cva6_user/Custom_Instructions.rst @@ -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. + diff --git a/docs/01_cva6_user/Introduction.rst b/docs/01_cva6_user/Introduction.rst new file mode 100644 index 000000000..58aa4310a --- /dev/null +++ b/docs/01_cva6_user/Introduction.rst @@ -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. + diff --git a/docs/01_cva6_user/PMA.rst b/docs/01_cva6_user/PMA.rst new file mode 100644 index 000000000..54bbb7a4d --- /dev/null +++ b/docs/01_cva6_user/PMA.rst @@ -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. + diff --git a/docs/01_cva6_user/PMP.rst b/docs/01_cva6_user/PMP.rst new file mode 100644 index 000000000..4daa45bcb --- /dev/null +++ b/docs/01_cva6_user/PMP.rst @@ -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) + diff --git a/docs/01_cva6_user/Parameters_Configuration.rst b/docs/01_cva6_user/Parameters_Configuration.rst new file mode 100644 index 000000000..e40fa6c07 --- /dev/null +++ b/docs/01_cva6_user/Parameters_Configuration.rst @@ -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. + diff --git a/docs/01_cva6_user/Programmer_View.rst b/docs/01_cva6_user/Programmer_View.rst new file mode 100644 index 000000000..d0e8ba2e4 --- /dev/null +++ b/docs/01_cva6_user/Programmer_View.rst @@ -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. + diff --git a/docs/01_cva6_user/RISCV_Instructions.rst b/docs/01_cva6_user/RISCV_Instructions.rst new file mode 100644 index 000000000..96c1b37b7 --- /dev/null +++ b/docs/01_cva6_user/RISCV_Instructions.rst @@ -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? + diff --git a/docs/01_cva6_user/Traps_Interrupts_Exceptions.rst b/docs/01_cva6_user/Traps_Interrupts_Exceptions.rst new file mode 100644 index 000000000..52b0a3028 --- /dev/null +++ b/docs/01_cva6_user/Traps_Interrupts_Exceptions.rst @@ -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. + diff --git a/docs/01_cva6_user/index.rst b/docs/01_cva6_user/index.rst index d0b7ef17a..74bd03f6c 100644 --- a/docs/01_cva6_user/index.rst +++ b/docs/01_cva6_user/index.rst @@ -19,10 +19,24 @@ CVA6 User Manual ================ Editor: **Jerome Quevremont** -`jerome.quevremont@thalesgroup.com `__ .. 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 diff --git a/docs/02_cva6_requirements/cva6_requirements_specification.rst b/docs/02_cva6_requirements/cva6_requirements_specification.rst index 3f31c5ad8..7a36e6efa 100644 --- a/docs/02_cva6_requirements/cva6_requirements_specification.rst +++ b/docs/02_cva6_requirements/cva6_requirements_specification.rst @@ -2,7 +2,6 @@ CVA6 Requirement Specification =============================== Editor: **Jerome Quevremont** -`jerome.quevremont@thalesgroup.com `__ Revision 1.0.1 diff --git a/docs/03_cva6_design/cva6_testharness.md b/docs/03_cva6_design/cva6_testharness.md deleted file mode 100644 index 2009bf055..000000000 --- a/docs/03_cva6_design/cva6_testharness.md +++ /dev/null @@ -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"`. diff --git a/docs/04_cv32a6_design/source/cv32a6_csr.rst b/docs/04_cv32a6_design/source/cv32a6_csr.rst index f746de039..390baedfa 100644 --- a/docs/04_cv32a6_design/source/cv32a6_csr.rst +++ b/docs/04_cv32a6_design/source/cv32a6_csr.rst @@ -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