Update esl_epfl_x_heep to esl-epfl/x-heep@086884b

Update code from upstream repository https://github.com/esl- epfl/x-heep.git to revision 086884bed017d7778d1c6309533fdf0505a220e2 * Improved the comments on the eXtendingHEEP readme (esl- epfl/x-heep#360) (JuanSapriza) * Modified the way of realizing if an app is external or not (JuanSapriza) * add script to simulate all apps (esl-epfl/x-heep#341) (JuanSapriza) * [app] fix APPs on flash_exec (esl-epfl/x-heep#357) (Davide Schiavone) * adding attributes and mux pad parameters in mcu-gen (esl- epfl/x-heep#349) (Davide Schiavone) * change signal names in power manager to reflex polarity (esl- epfl/x-heep#352) (Simone Machetti) * fix power gating core app (esl-epfl/x-heep#355) (Davide Schiavone) * add cv32e40px (esl-epfl/x-heep#353) (Davide Schiavone) * moved fpnew in its own directory (esl-epfl/x-heep#351) (Davide Schiavone) * update cv32e40p divider (esl-epfl/x-heep#350) (Davide Schiavone) * fix external pad gen (esl-epfl/x-heep#346) (Davide Schiavone) * fix mcu-gen (esl-epfl/x-heep#345) (Davide Schiavone) * update GPIO driver (esl-epfl/x-heep#246) (Hossein Taji) * fix interleaved bus (esl-epfl/x-heep#340) (Daniel Vázquez) * fix esl-epfl/x-heep#338 (esl-epfl/x-heep#339) (Davide Schiavone) * Initialized variables to 0 inside functions. Removed printf comments (esl-epfl/x-heep#334) (JuanSapriza) * made the dma_is_ready() function non-optimizable at all. (esl- epfl/x-heep#333) (JuanSapriza) * fix SPI apps (esl-epfl/x-heep#327) (Davide Schiavone) * Include x-heep.h to all apps that need it (esl-epfl/x-heep#329) (JuanSapriza) * Added soc_ctrl-reg_top warning to waiver (esl-epfl/x-heep#326) (JuanSapriza) * fix several applications (esl-epfl/x-heep#325) (Davide Schiavone) * Tries to use cmake3. If that is not available, go ahead with cmake (esl-epfl/x-heep#323) (JuanSapriza) * Improve the timing of cv32e40x by removing the debug triggers (esl- epfl/x-heep#324) (David Mallasén Quintana) * refactoring of examples (esl-epfl/x-heep#322) (JuanSapriza) * expose internal master ports to external devices (esl- epfl/x-heep#268) (Michele Caon) * Interrupt ID to the intr handlers of the PLIC (esl-epfl/x-heep#315) (JuanSapriza) * add ports to DMA to write to addresses coming from port2 of DMA (esl-epfl/x-heep#320) (Davide Schiavone) * DMA HAL - clean PR (esl-epfl/x-heep#317) (JuanSapriza) * Cleaning up flags (esl-epfl/x-heep#316) (Davide Schiavone) * Add support for externally defined external pads in `Makefile` (esl- epfl/x-heep#312) (Michele Caon) * Linker load flash refactor fill memory (esl-epfl/x-heep#294) (jmiranda) * add i2s peripheral (esl-epfl/x-heep#203) (Tim Frey) * Add example ADC schematic (esl-epfl/x-heep#309) (Cyril) * Update `cv32e40x` version to `0.9.0` (esl-epfl/x-heep#308) (Michele Caon) * integration of an AMS peripheral example (esl-epfl/x-heep#270) (Cyril) * Update FuseSoC remote (esl-epfl/x-heep#307) (Michele Caon) * fix USE_SPI_FLASH for FPGA (esl-epfl/x-heep#301) (Davide Schiavone) * add ifdef peripheral included (esl-epfl/x-heep#288) (Davide Schiavone) * Added command in CI to include all peripherals before building. (esl-epfl/x-heep#293) (JuanSapriza) * fix esl-epfl/x-heep#291 (esl-epfl/x-heep#292) (Davide Schiavone) * fix example_power_gating_core app (esl-epfl/x-heep#286) (Simone Machetti) * fix esl-epfl/x-heep#266 and esl-epfl/x-heep#289 (esl- epfl/x-heep#290) (Davide Schiavone) * Added compilation warning. (esl-epfl/x-heep#287) (Simone Machetti) * fix Linux FEMU (esl-epfl/x-heep#285) (Simone Machetti) * added logo (esl-epfl/x-heep#283) (Simone Machetti) * update cv32e40p (esl-epfl/x-heep#269) (Davide Schiavone) * Add makefile variable for compiler prefix (esl-epfl/x-heep#278) (David Mallasén Quintana) * CI to verify that apps can be built on every push/PR (esl- epfl/x-heep#239) (JuanSapriza) * App fix + sh compilation script (esl-epfl/x-heep#267) (jmiranda) * update common cells (esl-epfl/x-heep#262) (Davide Schiavone) * crt logic update + CMake backend modifications (esl-epfl/x-heep#264) (jmiranda) * External peripheral app bug fix and refactor (esl-epfl/x-heep#259) (Stefano Albini) * Update CMakebackend (esl-epfl/x-heep#258) (jmiranda) * rv_plic HAL refactor (esl-epfl/x-heep#240) (Stefano Albini) * Add LICENSE (davide schiavone) * Add F-HEEP to the eXtendingHEEP list (esl-epfl/x-heep#257) (David Mallasén Quintana) * add fast interrupt enable register (esl-epfl/x-heep#256) (Tim Frey) * improved interrupt integration (esl-epfl/x-heep#255) (Tim Frey) * Peripherals structs _reserved fields renaming (esl-epfl/x-heep#254) (Stefano Albini) * adding bitfield_read/write functions (esl-epfl/x-heep#253) (Hossein Taji) * add interleaved bus (esl-epfl/x-heep#237) (Daniel Vázquez) * fix parameters when there are no external domains (esl- epfl/x-heep#247) (Davide Schiavone) * Corrected two comments and removed the FIC part in the power gating example. (esl-epfl/x-heep#248) (JuanSapriza) * make example external periph shorter (esl-epfl/x-heep#232) (Davide Schiavone) * Minor modification on Readme (esl-epfl/x-heep#245) (jmiranda) * Fixing APPs and Compilation issues + FreeRTOS HEAP mem (esl- epfl/x-heep#238) (jmiranda) * updating fast intr ctrl based on structure (esl-epfl/x-heep#235) (Hossein Taji) * [hw] adding peripheral inclusion/exclusion configuration (esl- epfl/x-heep#244) (Davide Schiavone) * add PDM2PCM peripheral (esl-epfl/x-heep#192) (grinningmosfet) * Peripherals struct multireg and address mismatch fix (esl- epfl/x-heep#234) (Stefano Albini) * fix for VCS (esl-epfl/x-heep#229) (Cyril) * Build external sources with external drivers (esl-epfl/x-heep#227) (JuanSapriza) * add verilator run app command (esl-epfl/x-heep#228) (Tim Frey) * add tc_clk_xor2 (esl-epfl/x-heep#225) (Tim Frey) * fix venv / conda envs (esl-epfl/x-heep#221) (Davide Schiavone) * update common cells (esl-epfl/x-heep#223) (Davide Schiavone) Signed-off-by: Juan Sapriza <juan.sapriza@epfl.ch>
JuanSapriza · Aug 10, 2023 · 07362b9 · 07362b9
1 parent e8b4f5f
commit 07362b9
Show file tree

Hide file tree

Showing 438 changed files with 133,781 additions and 15,074 deletions.
diff --git a/hw/vendor/esl_epfl_x_heep.lock.hjson b/hw/vendor/esl_epfl_x_heep.lock.hjson
@@ -9,6 +9,6 @@
   upstream:
   {
     url: https://github.com/esl-epfl/x-heep.git
-    rev: 158a70c92b16a7ab207fe25eae6e131e461d631d
+    rev: 086884bed017d7778d1c6309533fdf0505a220e2
   }
 }
diff --git a/hw/vendor/esl_epfl_x_heep/.gitignore b/hw/vendor/esl_epfl_x_heep/.gitignore
@@ -18,10 +18,13 @@ linux_femu/rtl/linux_femu.sv
 .venv/
 
 # ignore the following hw automatically generated files
+environment.yml
 core-v-mini-mcu.upf
 tb/tb_util.svh
 hw/core-v-mini-mcu/include/core_v_mini_mcu_pkg.sv
 hw/core-v-mini-mcu/system_bus.sv
+hw/core-v-mini-mcu/system_xbar.sv
+hw/core-v-mini-mcu/memory_subsystem.sv
 hw/system/x_heep_system.sv
 hw/system/pad_ring.sv
 tb/tb_util.svh
@@ -46,3 +49,7 @@ sw/device/lib/drivers/**/*_structs.h
 
 # openroad
 flow/OpenROAD-flow-scripts
+
+# User-dependent configuration files
+.vscode
+private/
diff --git a/hw/vendor/esl_epfl_x_heep/AnalogMixedSignal.md b/hw/vendor/esl_epfl_x_heep/AnalogMixedSignal.md
@@ -0,0 +1,108 @@
+# Analog / Mixed-Signal Simulation of X-HEEP
+
+## About
+
+VCS offers the possibility to run AMS simulations by interfacing analog SPICE files with the rest of the digital RTL design. This is done through a special file located under `hw/ip_examples/ams/analog` named `control.init`.
+
+## The SPICE (.sp) file
+
+SPICE files can be created with the tool of your choice, however they must sometimes be edited manually afterwards to meet the following criteria:
+
+- The format should be HSPICE compatible
+
+- If not already done, one or more library inclusion lines:
+```
+.LIB /path/to/pdk/lib
+```
+must be added at the beginning of the file to include the necessary files from the PDK.
+
+- After the .LIB lines, power nets must be manually added in the file and made global. In most cases it should look like this:
+```
+v_vdd vdd 0 1.2
+v_gnd gnd 0 0
+.global vdd gnd
+```
+
+- Aside from the .LIB inclusions and the power nets, the file must only contain subcircuits.
+    - This means that lines describing temperature, parameters, options and so forth should be removed from the file
+    - This also means that there should be no top-level elements such as transistors, passive components etc at the top-level. The top-level must thus itself be a subcircuit, with IO pins corresponding to the names defined in the RTL part.
+
+- Keep in mind that all names in HSPICE netlists are treated as lowercase, thus make sure they will properly match with the RTL part.
+
+### Example procedure with Cadence Virtuoso
+
+- Design a schematic that should later be simulated, make sure the toplevel pins match the name of the pins in the RTL part of the peripheral
+- Create a toplevel symbol of the schematic you want to simulate
+- Run ADE L, select hspiceD in Setup -> Simulator
+- Select Simulation -> Netlist -> Create and save the SPICE output in a file
+- Open the SPICE file with a text editor, remove lines beginning with .TEMP & .OPTION (remember the file should only
+- Add the global power nets tat the beginning of the file:
+```
+v_vdd vdd 0 1.2
+v_gnd gnd 0 0
+.global vdd gnd
+```
+- Go to the bottom of the file, remove toplevel info (the circuit instance `xi` and the `.END`; there must be only subckts left
+- The SPICE file is now ready to be simulated. Place it in `hw/ip_examples/ams/analog` and create a `control.init` file (see next section)
+
+## The control.init file
+
+This file should at the very least look similar to this to be able to run a successful simulation:
+```
+choose xa ../../../hw/ip_examples/ams/analog/adc.sp;
+port_connect -cell ams_adc_1b ( vdd => vdd , gnd => gnd );
+port_dir -cell ams_adc_1b (input sel; output out);
+bus_format <%d>;
+```
+- The first line tells what analog simulator should VCS be using, and what SPICE file it should be simulating. In this case, by specifying `xa`, we tell it to use CustomSim, which reads SPICE files in the HSPICE format. Note that as this file will be ran from the VCS runtime directory, relative paths pointing to the .sp file should take this into account.
+- The second line specifies which RTL cell should be connected to the SPICE top-level subcircuit. VDD & GND must be connected as indicated.
+- The third line specifies the direction (input/output) of the ports which are connected from RTL to SPICE. This isn't always necessary to specify, but the simulation might fail without this line
+- The last line specifies the bus format used by the SPICE file, which is usually <%d> but can sometimes be [%d] or even (%d) depending on how your SPICE file was written.
+
+Additional lines and options can of course be specified: refer to the official Synopsys Mixed-Signal Simulation User Guide for complete instructions.
+
+## The example AMS peripheral and the interfacing of SPICE netlists within X-HEEP
+
+The example AMS peripheral used by simulations of X-HEEP is located in `hw/ip_examples/ams`. You should edit the port names so they match the top-level connectivity of the SPICE netlist.
+
+
+### The repository's example SPICE files
+
+<p align="center"><img src="block_diagrams/example_adc.svg" width="500"></p>
+
+An example `adc.sp` file can be found in `hw/ip_examples/ams/analog`. This is a 1-bit ADC with a threshold that is configured through the 2-bit wide SEL input: an input of 00, 01, 10 and 11 will provide a threshold of 20%, 40%, 60% and 80% of VDD (1.2V) respectively. The input signal of the ADC is a sine wave with a peak-to-peak amplitude of 1.2V directly placed inside the SPICE netlist.
+
+The SPICE netlist uses the [65nm_bulk PTM Bulk CMOS model](http://ptm.asu.edu/modelcard/2006/65nm_bulk.pm) obtained from [https://ptm.asu.edu](https://ptm.asu.edu/) (February 22, 2006 release) ; to be able to simulate this file with VCS/CustomSim, the model file should be placed in `hw/ip_examples/ams/analog/65nm_bulk.pm`.
+
+## Simulating with VCS-AMS and CustomSim
+
+The AMS simulation of X-HEEP can be ran by typing
+```
+make vcs-ams-sim
+```
+
+then going to the target system built folder
+
+```
+cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-vcs
+```
+
+and running the executable
+
+```
+./openhwgroup.org_systems_core-v-mini-mcu_0 +firmware=../../../sw/build/main.hex
+```
+
+However, due to the analog nature of the simulation, viewing the waveforms is very useful as well.
+
+### Viewing the waveforms with Verdi
+
+To run the simulation through Verdi, make sure to have the `VERDI_HOME` environmental variable  set then run
+```
+./openhwgroup.org_systems_core-v-mini-mcu_0 +firmware=../../../sw/build/main.hex -gui
+```
+
+It may be that you don't see the list signals: click on View -> Signal list. Then, select the desired signals and put the desired simulation time on the box just after the green arrow and click on the green arrow (run Simulation).
+
+In case you cannot add internal signals to the waveform, try to delete the sim-vcs build directory and rebuilding.
+
diff --git a/hw/vendor/esl_epfl_x_heep/Debug.md b/hw/vendor/esl_epfl_x_heep/Debug.md
@@ -40,10 +40,10 @@ The remote bitbang server is simplemented in the folder ./hw/vendor/pulp_platfor
 
 ### Verilator
 
-To simulate your application with Questasim using the remote_bitbang server, you need to compile you system adding the flag `use_jtag_dpi`:
+To simulate your application with Questasim using the remote_bitbang server, you need to compile you system adding the `JTAG DPI` functions:
 
 ```
-make verilator-sim FUSESOC_FLAGS="--flag use_jtag_dpi"
+make verilator-sim "FUSESOC_PARAM="--JTAG_DPI=1"
 ```
 
 then, go to your target system built folder
@@ -60,10 +60,10 @@ and type to run your compiled software:
 
 ### Questasim
 
-To simulate your application with Questasim using the remote_bitbang server, you need to compile you system adding the flag `use_jtag_dpi`:
+To simulate your application with Questasim using the remote_bitbang server, you need to compile you system adding the `JTAG DPI` functions:
 
 ```
-make questasim-sim FUSESOC_FLAGS="--flag=use_jtag_dpi"
+make questasim-sim "FUSESOC_PARAM="--JTAG_DPI=1"
 ```
 
 then, go to your target system built folder

diff --git a/hw/vendor/esl_epfl_x_heep/ExecuteFromFlash.md b/hw/vendor/esl_epfl_x_heep/ExecuteFromFlash.md
@@ -45,7 +45,7 @@ Then it loads the `boot_address` from a memory-mapped register that is set to
 0x180 at reset time, which is also the boot address specified in the entry point of the 
 linked scripts.
 If you want to simulate the actual JTAG procedure without pre-loading instead, 
-compile the RTL with the `use_jtag_dpi` flag and follow the `Debug.md` guide.
+compile the RTL with the `FUSESOC_PARAM="--JTAG_DPI=1"` flag and follow the `Debug.md` guide.
 
 ### SPI Flash Execution Boot Procedure
 
@@ -72,10 +72,6 @@ To use this mode, when targetting ASICs or FPGA bitstreams,
 make sure you have the `boot_sel_i` input (e.g., a switch) set to 1, 
 and the `execute_from_flash_i` set to 1 too.
 
-To simulate this procedure, you must compile the RTL 
-with the `use_external_device_example` flag to 
-tell fusesoc to compile the FLASH model.
-
 Note that the FLASH model is not compatible with **verilator**, 
 thus the simulation must be carried out with either **modelsim** or **vcs**.
 

diff --git a/hw/vendor/esl_epfl_x_heep/ExternalDevices.md b/hw/vendor/esl_epfl_x_heep/ExternalDevices.md
@@ -1,56 +1,68 @@
 ## Interface for external devices
 
-The top module core_v_mini_mcu (hw/core-v-mini-mcu/corecore_v_mini_mcu.sv) contains 3 external interfaces:
+The top module [`core_v_mini_mcu`](hw/core-v-mini-mcu/corecore_v_mini_mcu.sv) exposes several external interfaces:
 
-1. ext_xbar_master : N master ports connected to the system bus
+- `ext_xbar_master`: N ports to connect external masters to the internal system bus.
 
-2. ext_xbar_slave : 1 slave port connected to the system bus
+- Five external ports to connect internal masters (e.g., CPU instruction and data ports) to external slaves. Every internal master is exposed to the external subsystem:
+   1. `ext_core_instr`: CPU instruction interface.
+   2. `ext_core_data`: CPU data interface.
+   3. `ext_debug_master`: debug interface.
+   4. `ext_dma_read_ch0`: DMA read master, channel 0.
+   5. `ext_dma_write_ch0`: DMA write master, channel 0.
+   6. `ext_dma_addr_ch0`: DMA address (read) master, channel 0.
 
-3. ext_peripheral_slave : 1 peripheral slave port connected to the system bus (through the peripheral interface)
+- `ext_peripheral_slave`: 1 peripheral slave port connected to the system bus (through the peripheral interface).
 
-The number of master ports is set by testharness_pkg::EXT_XBAR_NMASTER.
-The slave port and peripheral slave port are fixed to one. Multiple slaves can be connected by adding an address decoding stage.
+The number of external master ports is set by the [`EXT_XBAR_NMASTER`](./tb/testharness_pkg.sv#L10) parameter from `testharness_pkg`.
+Multiple OBI slaves can be connected to the exposed internal masters using an external bus, as demonstrated in [`testharness.sv`](./tb/testharness.sv#L232). 
+
+> NOTE: the internal bus has no master port connected to the external subsystem. Therefore, an external master cannot send a request to an external slave through one of the exposed master ports. All the address decoding must be done by the external bus: the request must be forwarded to one of the `ext_xbar_master` ports only if the target address falls into the space where internal slaves are mapped. This can be achieved using a 1-to-2 crossbar for each external master as done [here](./tb/ext_bus.sv#L131).
+
+Finally, only one peripheral slave port is available to the external subsystem.
 
 ## External device example
 
 One example using the external ports is provided where:
 
 - hw/ip_examples/slow_sram is a memory slave device
 - hw/ip_examples/memcopy is a slave peripheral with a master port. It implements a simple memcopy feature (i.e., DMA).
+- hw/ip_examples/ams is an example AMS peripheral which can interface with SPICE netlists to run mixed-signal simulations (in this repository, the example analog peripheral is a 1-bit ADC)
+    - For more information, see [here](AnalogMixedSignal.md)
 
 ## Run the external device example
 
 To run the external device example, first compile the software example:
 
-```
-make app PROJECT=example_external_peripheral
+```bash
+make app PROJECT=example_external_dma
 ```
 
-By default, the external device example RTL code is disabled. Run fusesoc with the '--flag=use_external_device_example' option to enable it. This example is available for the sim and sim_opt targets.
+By default, the external device example RTL code is disabled. This example is available for the sim and sim_opt targets.
 
 For example, compile for Verilator with:
 
 ```
-make verilator-sim FUSESOC_FLAGS="--flag=use_external_device_example"
+make verilator-sim
 ```
 
 then, go to your target system built folder
 
-```
+```bash
 cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator
 ```
 
 and type to run your compiled software:
 
-```
+```bash
 ./Vtestharness +firmware=../../../sw/build/main.hex
 ```
 
 If you don't compile the platform with the correct fusesoc flag, the simulation will hang forever because the external peripheral is disabled and never replies.
 
-You can display the uart output with:
+You can display the UART output with:
 
-```
+```bash
 cat uart0.log
 ```
 
@@ -70,22 +82,18 @@ MEMCOPY SUCCESS
 
 1. Master(s): use the obi_pkg (import obi_pkg::\*;) to create your master_req output port (obi_req_t) and master_resp input port (obi_resp_t). Adjust the EXT_XBAR_NMASTER parameter accordingly.
 
-2. Slave(s): similar to adding a master but you have a slave_req input port (obi_req_t) and slave_resp output port (obi_resp_t). If multiple slaves are used, add a decoding stage for address dispatching.
+2. Slave(s): similar to adding a master but you have a slave_req input port (obi_req_t) and slave_resp output port (obi_resp_t). Remember to connect external masters with external slaves through an external bus. The same bus can be used to connect multiple external slaves to the internal `core_v_mini_mcu` masters.
 
 3. Peripheral slave(s): use the reg_pkg (import obi_pkg::\*;) to create your slave_periph_req input port (reg_req_t) and slave_resp output port (reg_rsp_t). If multiple peripheral slaves are used, add a decoding stage for addresses dispatching.
 
-To create and maintain a peripheral unit efficiently, use the reggen tool:
-
-1. Define the registers of your peripheral in a hjson file (read the documentation [here](https://docs.opentitan.org/doc/rm/register_tool/)).
-
-2. Launch the regtool.py script to generate SystemVerilog RTL code and a C header file.
+To create and maintain a peripheral unit efficiently, use the `reggen` tool:
 
-For example, launching the script hw/ip_examples/memcopy_periph/memcopy_periph_gen.sh generates 2 systemverilog files and 1 C header file:
+1. Define the registers of your peripheral in a `.hjson` file (read the documentation [here](https://docs.opentitan.org/doc/rm/register_tool/)).
 
-1. memcopy_periph_reg_top.sv
-2. memcopy_periph_reg_pkg.sv
-3. memcopy_periph_regs.h
+2. Launch the `regtool.py` script to generate SystemVerilog RTL code and a C header file.
 
-The memocopy_periph_reg_top.sv contains the register file module. It can be instantiated inside your peripheral RTL code (e.g., memcopy_periph.sv) and connected to the control logic of your peripheral.
+For example, launching the script [`memcopy_periph_gen.sh`](./hw/ip_examples/memcopy_periph/memcopy_periph_gen.sh) generates 2 SystemVerilog files and one C header file:
 
-The memcopy_periph_regs.h contains the address offset of the peripheral registers and can be used in a C application. See the example C code in sw/applications/example_external_peripheral folder.
+1. `memcopy_periph_reg_top.sv`: the register file module. It can be directly instantiated inside your peripheral RTL code (e.g., [`memcopy_periph.sv`](./hw/ip_examples/memcopy_periph/rtl/memcopy_periph.sv)) and connected to the peripheral device controller(s).
+2. `memcopy_periph_reg_pkg.sv`: SystemVerilog package containing the definitions used in the SystemVerilog module above.
+3. `memcopy_periph_regs.h`: C/C++ header file defining the address offset of the peripheral configuration registers. Take a look at the C code [here](./sw/applications/example_external_peripheral/memcopy_periph.c) for a usage example.