Merge branch 'esl-epfl:main' into fix_gpio_hal

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

IDEs.md

@@ -0,0 +1,45 @@
+
+For FW development, `X-HEEP` can be used together with different Integrated Development Environments (IDEs) flavours. Up to now, full support is just provided by [Segger Embedded Studio (SES)](https://www.segger.com/products/development-tools/embedded-studio/editions/risc-v/). This readme guides you through all the needed steps to get SES working and debugging when prototyping `X-HEEP` into the pynq-z2 board.
+
+# Prerequisite
+
+## 1. SES installation. 
+The platform was only tested under Linux and version 7.32 of the Embedded Studio for RISC-V. Please, go to the Segger [download center](https://www.segger.com/downloads/embedded-studio/) to get that version. It is assumed that you have already installed the RISC-V compiler and openOCD. If the latter is not true, check the main [Readme](https://github.com/esl-epfl/x-heep) please.
+
+# Configuration
+
+After installing SES, you need to indicate to Segger your Toolchain directory (RISC-V Compiler) as well as your openOCD installation folder. Those need to be specified into `xheep.emProject` file. 
+
+For the RISC-V Compiler path, **line 71**:
+```
+build_toolchain_directory="/home/< user >/tools/riscv/bin"
+```
+Please, substitute that path to your current path where the RISC-V compiler was installed. Do not forget to target the `bin` folder inside the installation folder of the toolchain.
+
+For the openOCS path, **line 88**:
+```
+gdb_server_command_line="/home/< user >/tools/openocd/bin/openocd -f &quot;$(ProjectDir)/../../tb/core-v-mini-mcu-pynq-z2-esl-programmer.cfg&quot;"
+```
+Please, substitute that path to your current path where openOCD was installed. Do not forget to target the `openocd` file inside the `bin` installation folder of openocd.
+
+# Building
+
+Once the paths are set properly, you can open `xheep.emProject` with SES. That will launch SES with one solution already configured, `xheep_ses`, and one project into that solution `helloworld`. Note that this project has already everything configured to run the `helloworld` application of the main repo, i.e. all the source files are linked to the project as well as the `c user include directories` already set up. Moreover, this project is configured to be running (compile, linking, and debug) by using the on-chip linker `sw/linker/link.ld`. If you want to change any of these options, you will need to change the options of the project or the options of the solution. Note that the project is currently set-up to be working on the `Debug_External` configuration. Please, do not move to other configuration when building and/or debugging. Finally, to build the whole project just press `F7` or `Build > Build helloworld`.
+
+The output should be like this:
+
+<p align="left"><img src="ides/img/build_screenshot.png" width="450"></p>
+
+Note that on the right part, you have the memory usage based on the linker we have configured. If you do not see this, you can activate that view in `View > Memory Usage`.
+
+# Debugging
+
+Finally, after building (compile and linking), you can directly start debugging by pressing `F5` or also `Target > Connect GDB Server` and `Debug > Go`. You also have the possibility to activate the terminal to see directly into the SES window the printing characters. 
+
+The output should be something like this:
+
+<p align="left"><img src="ides/img/debug_screenshot.png" width="450"></p>
+
+Note that when debugging and setting breakpoints, please, go one-by-one (one breakpoint at a time). Several breakpoints support will be supported in the following releases.
+
+Further improvements and support will be provided and explain in following releases.

README.md

@@ -182,8 +182,13 @@ First, you have to generate the SystemVerilog package and C header file of the c
 make mcu-gen
 ```
 
-To change the default cpu type (i.e., cv32e20), the default bus type (i.e., onetoM),
-the default continuous memory size (i.e., 2 continuous banks) or the default interleaved memory size (i.e., 0 interleaved banks):
+By default, `X-HEEP` deploys the [cv32e20](https://github.com/openhwgroup/cve2) RISC-V CPU.
+Other supported CPUs are: the [cv32e40p](https://github.com/openhwgroup/cv32e40p), [cv32e40x](https://github.com/openhwgroup/cv32e40x), and the [cv32e40px](https://github.com/esl-epfl/cv32e40px).
+The default bus type of `X-HEEP` is a single-master-at-a-time architecture, (called `onetoM`), but the cross-bar architecture is also supported by setting
+the bus to `NtoM`. Also, the user can select the number of 32kB banks addressed in continuous mode and/or the interleaved mode.
+By default, `X-HEEP` is generated with 2 continuous banks and 0 interleaved banks.
+
+Below an example that changes the default configuration:
 
 ```
 make mcu-gen CPU=cv32e40p BUS=NtoM MEMORY_BANKS=12 MEMORY_BANKS_IL=4
@@ -238,10 +243,12 @@ Or, if you use the OpenHW Group [GCC](https://www.embecosm.com/resources/tool-ch
 make app COMPILER_PREFIX=riscv32-corev- ARCH=rv32imc_zicsr_zifencei_xcvhwlp1p0_xcvmem1p0_xcvmac1p0_xcvbi1p0_xcvalu1p0_xcvsimd1p0_xcvbitmanip1p0
 ```
 
-This will create the executable file to be loaded in your target system (ASIC, FPGA, Simulation).
+This will create the executable file to be loaded into your target system (ASIC, FPGA, Simulation).
 Remember that, `X-HEEP` is using CMake to compile and link. Thus, the generated files after having
 compiled and linked are under `sw\build`
 
+Alternatively, in case you are doing pure FW development and you are used to developing using Integrated Development Evironments (IDEs), please check [the IDE readme](./IDEs.md).
+
 ## FreeROTS based applications
 
 'X-HEEP' supports 'FreeRTOS' based applications. Please see `sw\applications\blinky_freertos`.
@@ -462,6 +469,8 @@ The success of the script is not required for merging of a PR.
 
 Follow the [Debug](./Debug.md) guide to debug core-v-mini-mcu.
 
+Alternatively, in case you are used to developing using Integrated Development Environments (IDEs), please check [the IDE readme](./IDEs.md).
+
 ## Execute From Flash
 
 Follow the [ExecuteFromFlash](./ExecuteFromFlash.md) guide to exxecute code directly from the FLASH with modelsim, FPGA, or ASIC.

core-v-mini-mcu.core

@@ -73,6 +73,7 @@ filesets:
   tb-utils:
     depend:
     - x-heep::tb-utils
+    - x-heep::tb-fpu-utils
 
   files_verilator_waiver:
     depend:
@@ -107,6 +108,7 @@ filesets:
     - hw/fpga/cv32e40p_xilinx_clock_gate.sv:  { file_type: systemVerilogSource }
     - hw/fpga/cv32e40x_xilinx_clock_gate.sv:  { file_type: systemVerilogSource }
     - hw/fpga/cve2_xilinx_clock_gate.sv:  { file_type: systemVerilogSource }
+    - hw/fpga/cv32e40px_xilinx_clock_gate.sv:  { file_type: systemVerilogSource }
     - hw/fpga/pad_cell_input_xilinx.sv:  { file_type: systemVerilogSource }
     - hw/fpga/pad_cell_output_xilinx.sv:  { file_type: systemVerilogSource }
     - hw/fpga/pad_cell_inout_xilinx.sv:  { file_type: systemVerilogSource }
@@ -230,6 +232,12 @@ parameters:
     description: |
       Enables testbench JTAG DIPs. Admitted values: 1|0.
     default: 0
+  X_EXT:
+    datatype: int
+    paramtype: vlogparam
+    description: |
+      Enables CORE-V-XIF interface for the CV32E40X and CV32E40PX cores. Admitted values: 1|0.
+    default: 0
   USE_EXTERNAL_DEVICE_EXAMPLE:
     datatype: int
     paramtype: vlogparam
@@ -324,6 +332,7 @@ targets:
     - COREV_PULP
     - FPU
     - JTAG_DPI
+    - X_EXT
     - USE_EXTERNAL_DEVICE_EXAMPLE
     - USE_UPF
     - REMOVE_OBI_FIFO
@@ -382,6 +391,7 @@ targets:
     parameters:
     - COREV_PULP
     - FPU
+    - X_EXT
     - SYNTHESIS=true
     - REMOVE_OBI_FIFO
     tools:
@@ -401,6 +411,7 @@ targets:
     parameters:
     - COREV_PULP
     - FPU
+    - X_EXT
     - SYNTHESIS=true
     - REMOVE_OBI_FIFO
     tools:
@@ -420,6 +431,7 @@ targets:
     parameters:
     - COREV_PULP
     - FPU
+    - X_EXT
     - SYNTHESIS=true
     - REMOVE_OBI_FIFO
     tools:
@@ -435,6 +447,7 @@ targets:
     parameters:
     - PRIM_DEFAULT_IMPL=prim_pkg::your_target_technology
     - COREV_PULP
+    - X_EXT
     - FPU
     - SYNTHESIS=true
     - REMOVE_OBI_FIFO
@@ -457,6 +470,7 @@ targets:
     parameters:
       - COREV_PULP
       - FPU
+      - X_EXT
       - SYNTHESIS=true
       - VERILATOR=true
       - REMOVE_OBI_FIFO

docs/Makefile

@@ -0,0 +1,18 @@
+# Copyright 2023 EPFL
+# Solderpad Hardware License, Version 2.1, see LICENSE.md for details.
+# SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1
+#
+# Author: ESL
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx-rtd-theme
+myst-parser

AnalogMixedSignal.md → docs/source/How_to/AnalogMixedSignal.md

@@ -1,4 +1,4 @@
-# Analog / Mixed-Signal Simulation of X-HEEP
+#  integrate Analog / Mixed-Signal simulations
 
 ## About