Merge branch 'esl-epfl:main' into update_cve2

Makefile

@@ -6,6 +6,7 @@ MAKE                       = make
 
 # Get the absolute path
 mkfile_path := $(shell dirname "$(realpath $(firstword $(MAKEFILE_LIST)))")
+$(info $$You are executing from: $(mkfile_path))
 
 # Include the self-documenting tool
 FILE=$(mkfile_path)/Makefile
@@ -49,14 +50,17 @@ COMPILER_PREFIX ?= riscv32-unknown-
 ARCH     ?= rv32imc
 
 # Path relative from the location of sw/Makefile from which to fetch source files. The directory of that file is the default value.
-SOURCE 	 ?= "."
+SOURCE 	 ?= $(".")
 
 # Simulation engines options are verilator (default) and questasim
 SIMULATOR ?= verilator
 
 # Timeout for simulation, default 120
 TIMEOUT ?= 120
 
+# Export variables to sub-makefiles
+export
+
 ## @section Conda
 conda: environment.yml
 	conda env create -f environment.yml
@@ -175,7 +179,7 @@ run-helloworld: mcu-gen verilator-sim
 ## Uses verilator to simulate the HW model and run the FW
 ## UART Dumping in uart0.log to show recollected results
 run-blinkyfreertos: mcu-gen verilator-sim
-	$(MAKE) -C sw PROJECT=blinky_freertos TARGET=$(TARGET) LINKER=$(LINKER) COMPILER=$(COMPILER) COMPILER_PREFIX=$(COMPILER_PREFIX) ARCH=$(ARCH);
+	$(MAKE) -C sw PROJECT=example_freertos_blinky TARGET=$(TARGET) LINKER=$(LINKER) COMPILER=$(COMPILER) COMPILER_PREFIX=$(COMPILER_PREFIX) ARCH=$(ARCH);
 	cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator; \
 	./Vtestharness +firmware=../../../sw/build/main.hex; \
 	cat uart0.log; \

README.md

@@ -153,7 +153,7 @@ sudo apt-get install -y gtkwave
 
 We use version v0.0-1824-ga3b5bedf
 
-See: [Install Verible](https://opentitan.org/guides/getting_started/index.html#step-6a-install-verible-optional)
+See: [Install Verible](https://opentitan.org/guides/getting_started/index.html#step-7a-install-verible-optional)
 
 To format your RTL code type:
 
@@ -514,9 +514,20 @@ to load the binaries with the HS2 cable over JTAG,
 or follow the [ExecuteFromFlash](./ExecuteFromFlash.md)
 guide if you have a FLASH attached to the FPGA.
 
-
 Do not forget that the `pynq-z2` board requires you to have the ethernet cable attached to the board while running.
 
+For example, if you want to run your application using flash_exec, do as follow:
+
+compile your application, e.g. `make app PROJECT=example_matfadd TARGET=pynq-z2 ARCH=rv32imfc LINKER=flash_exec`
+
+and then follow the [ExecuteFromFlash](./ExecuteFromFlash.md) to program the flash and set the boot buttons on the FPGA correctly.
+
+To look at the output of your printf, run in another terminal:
+
+`picocom -b 9600 -r -l --imap lfcrlf /dev/ttyUSB2`
+
+Please be sure to use the right `ttyUSB` number (you can discover it with `dmesg --time-format iso | grep FTDI` for example).
+
 
 ### Linux-FEMU (Linux Fpga EMUlation)
 
@@ -547,3 +558,12 @@ We are working on supporting OpenRoad and SkyWater 130nm PDK, please refer to th
 [OpenRoadFlow](./OpenRoadFlow.md) page. This is not ready yet, it has not been tested.
 
 This relies on a fork of [edalize](https://github.com/davideschiavone/edalize) that contains templates for Design Compiler and OpenRoad.
+
+## References
+
+1. [Schiavone, Pasquale Davide, et al. "X-HEEP: An Open-Source, Configurable and Extendible RISC-V Microcontroller." 
+Proceedings of the 20th ACM International Conference on Computing Frontiers. 2023.](https://dl.acm.org/doi/pdf/10.1145/3587135.3591431?casa_token=cAs3isVd0zkAAAAA:gmQBe3ip7X0Fz0hO8lSFbGN5-2fdu5vni1dxWWAIe9zCxQDW1PPerubUigOcl_an8HiZOhPuNrwzIw8)
+
+
+
+

docs/source/How_to/ExecuteFromFlash.md

@@ -19,6 +19,8 @@ These three modes are mainly controlled by the two inputs pins
 | 1			       | 1				              | SPI Flash Execution  |
 | 1			       | 0				              | SPI Flash Loading    |
 
+
+On the FPGA, such inputs are mapped to two switch buttons.
 Below, a description of the three modes is provided.
 
 ### JTAG Boot Procedure

docs/source/How_to/ExternalDevices.md

@@ -97,3 +97,55 @@ For example, launching the script [`memcopy_periph_gen.sh`](./../../../hw/ip_exa
 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.
+
+## External Interrupts
+
+X-HEEP includes several empty external interrupts slots that can be assigned both in HW and SW.
+
+Firstly, connect your external device's interrupt to one of the slots of the `external_interrupt_vector` of X-HEEP:
+
+```systemverilog
+
+logic [core_v_mini_mcu_pkg::NEXT_INT-1:0] ext_intr_vector;
+
+always_comb begin
+for (int i = 0; i < core_v_mini_mcu_pkg::NEXT_INT; i++) begin
+    ext_intr_vector[i] = 1'b0;    // All interrupt lines set to zero by default
+end
+ext_intr_vector[0] = my_device_int;  // Re-assign the interrupt lines used here
+end
+
+x_heep_system #(
+    . . .
+) x_heep_system_i (
+    .intr_vector_ext_i(ext_intr_vector),
+    . . .
+)
+
+```
+
+Then, when initializing the PLIC system in software, do not forget to assign the corresponding interrupt ID to your custom handler.
+
+```C
+#define MY_DEVICE_INTR EXT_INTR_0
+
+void handler_irq_my_device(uint32_t id) {
+    my_device_intr_flag = 1;
+    // Do whatever you need here
+}
+
+void main() {
+    plic_Init(); // Init the PLIC, this will clear all external interrupts assigned previously.
+    plic_irq_set_priority(MY_DEVICE_INTR, 1); // Set the priority of the external device's interrupt.
+    plic_irq_set_enabled(MY_DEVICE_INTR, kPlicToggleEnabled); // Enable the external device's interrupt.
+    plic_assign_external_irq_handler( MY_DEVICE_INTR, (void *) &handler_irq_my_device); // Assign a handler taht will be called when this interrupt is triggered.
+
+    // Enable global interrupt for machine-level interrupts
+    CSR_SET_BITS(CSR_REG_MSTATUS, 0x8);
+    // Set mie.MEIE bit to one to enable machine-level external interrupts
+    const uint32_t mask = 1 << 11;//IRQ_EXT_ENABLE_OFFSET;
+    CSR_SET_BITS(CSR_REG_MIE, mask);
+
+    . . .
+}
+```

hw/core-v-mini-mcu/ao_peripheral_subsystem.sv

@@ -118,7 +118,10 @@ module ao_peripheral_subsystem
 
     // EXTERNAL PERIPH
     output reg_req_t ext_peripheral_slave_req_o,
-    input  reg_rsp_t ext_peripheral_slave_resp_i
+    input  reg_rsp_t ext_peripheral_slave_resp_i,
+
+    input logic ext_dma_slot_tx_i,
+    input logic ext_dma_slot_rx_i
 );
 
   import core_v_mini_mcu_pkg::*;
@@ -364,13 +367,15 @@ module ao_peripheral_subsystem
       .intr_timer_expired_1_0_o(rv_timer_1_intr_o)
   );
 
-  parameter DMA_TRIGGER_SLOT_NUM = 5;
+  parameter DMA_TRIGGER_SLOT_NUM = 7;
   logic [DMA_TRIGGER_SLOT_NUM-1:0] dma_trigger_slots;
   assign dma_trigger_slots[0] = spi_rx_valid;
   assign dma_trigger_slots[1] = spi_tx_ready;
   assign dma_trigger_slots[2] = spi_flash_rx_valid;
   assign dma_trigger_slots[3] = spi_flash_tx_ready;
   assign dma_trigger_slots[4] = i2s_rx_valid_i;
+  assign dma_trigger_slots[5] = ext_dma_slot_tx_i;
+  assign dma_trigger_slots[6] = ext_dma_slot_rx_i;
 
   dma #(
       .reg_req_t (reg_pkg::reg_req_t),

hw/core-v-mini-mcu/core_v_mini_mcu.sv

@@ -315,7 +315,10 @@ module core_v_mini_mcu
     output logic [EXT_DOMAINS_RND-1:0] external_ram_banks_set_retentive_no,
     output logic [EXT_DOMAINS_RND-1:0] external_subsystem_clkgate_en_no,
 
-    output logic [31:0] exit_value_o
+    output logic [31:0] exit_value_o,
+
+    input logic ext_dma_slot_tx_i,
+    input logic ext_dma_slot_rx_i
 );
 
   import core_v_mini_mcu_pkg::*;
@@ -628,7 +631,9 @@ module core_v_mini_mcu
       .uart_intr_rx_parity_err_o(uart_intr_rx_parity_err),
       .i2s_rx_valid_i(i2s_rx_valid),
       .ext_peripheral_slave_req_o,
-      .ext_peripheral_slave_resp_i
+      .ext_peripheral_slave_resp_i,
+      .ext_dma_slot_tx_i,
+      .ext_dma_slot_rx_i
   );
 
   peripheral_subsystem peripheral_subsystem_i (

hw/core-v-mini-mcu/core_v_mini_mcu.sv.tpl

@@ -69,7 +69,10 @@ ${pad.core_v_mini_mcu_interface}
     output logic [EXT_DOMAINS_RND-1:0] external_ram_banks_set_retentive_no,
     output logic [EXT_DOMAINS_RND-1:0] external_subsystem_clkgate_en_no,
 
-    output logic [31:0] exit_value_o
+    output logic [31:0] exit_value_o,
+
+    input logic ext_dma_slot_tx_i,
+    input logic ext_dma_slot_rx_i
 );
 
   import core_v_mini_mcu_pkg::*;
@@ -380,7 +383,9 @@ ${pad.core_v_mini_mcu_interface}
       .uart_intr_rx_parity_err_o(uart_intr_rx_parity_err),
       .i2s_rx_valid_i(i2s_rx_valid),
       .ext_peripheral_slave_req_o,
-      .ext_peripheral_slave_resp_i
+      .ext_peripheral_slave_resp_i,
+      .ext_dma_slot_tx_i,
+      .ext_dma_slot_rx_i
   );
 
   peripheral_subsystem peripheral_subsystem_i (

hw/fpga/scripts/xilinx_generate_clk_wizard.tcl

@@ -5,7 +5,7 @@
 
 set design_name      xilinx_clk_wizard
 set in_clk_freq_MHz  125
-set out_clk_freq_MHz 20
+set out_clk_freq_MHz 15
 
 # Select board
 set_property -name "board_part_repo_paths" -value "[file normalize "../../../hw/fpga/board_files/"]" -objects [current_project]
@@ -25,7 +25,7 @@ set_property -dict [ list \
  CONFIG.CLKIN1_JITTER_PS {80.0} \
  CONFIG.CLKOUT1_JITTER {172.798} \
  CONFIG.CLKOUT1_PHASE_ERROR {96.948} \
- CONFIG.CLKOUT1_REQUESTED_OUT_FREQ {20} \
+ CONFIG.CLKOUT1_REQUESTED_OUT_FREQ {15} \
  CONFIG.MMCM_CLKFBOUT_MULT_F {8.000} \
  CONFIG.MMCM_CLKIN1_PERIOD {8.000} \
  CONFIG.MMCM_CLKOUT0_DIVIDE_F {50.000} \

hw/fpga/xilinx_core_v_mini_mcu_wrapper.sv

@@ -191,7 +191,9 @@ module xilinx_core_v_mini_mcu_wrapper
       .pdm2pcm_pdm_io,
       .i2s_sck_io(i2s_sck_io),
       .i2s_ws_io(i2s_ws_io),
-      .i2s_sd_io(i2s_sd_io)
+      .i2s_sd_io(i2s_sd_io),
+      .ext_dma_slot_tx_i('0),
+      .ext_dma_slot_rx_i('0)
   );
 
   assign exit_value_o = exit_value[0];

hw/ip_examples/iffifo/data/iffifo.hjson

@@ -0,0 +1,76 @@
+// Copyright EPFL contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+{ name: "iffifo"
+  clock_primary: "clk_i"
+  bus_interfaces: [
+    { protocol: "reg_iface", direction: "device" }
+  ],
+  regwidth: 32
+  registers: [
+
+    { name:     "FIFO_OUT"
+      desc:     "Data coming from the FIFO (Fifo Output/Software RX)"
+      swaccess: "ro"
+      hwaccess: "hrw" # required for RE signal
+      hwext: "true"   # required for RE signal
+      hwre: "true"    # Used to emulate a window behaviour
+      fields: [
+        { bits: "31:0" }
+      ]
+    }
+
+    { name:     "FIFO_IN"
+      desc:     "Data sent to the FIFO (Fifo Input/Software TX)"
+      hwaccess: "hro"
+      swaccess: "rw"  # required for QE signal
+      hwqe: "true"    # Used to emulate a window behaviour
+      fields: [
+        { bits: "31:0" }
+      ]
+    }
+
+    { name:     "STATUS"
+      desc:     "General purpose status register"
+      swaccess: "ro"
+      hwaccess: "hwo"
+      fields: [
+        { bits: "0", name: "EMPTY",   desc: "Asserted when FIFO empty." }
+        { bits: "1", name: "AVAILABLE", desc: "Asserted when data is available in FIFO." }
+        { bits: "2", name: "REACHED", desc: "Asserted when occupied data slots count greater than threshold." }
+        { bits: "3", name: "FULL",    desc: "Asserted when all FIFO slots are occupied." }
+      ]
+    }
+
+    { name:     "OCCUPANCY"
+      desc:     "Current number of occupied FIFO slots"
+      swaccess: "ro"
+      hwaccess: "hwo"
+      fields: [
+        { bits: "31:0" }
+      ]
+    }
+
+    { name:     "WATERMARK"
+      desc:     "FIFO occupancy at which the STATUS:REACHED bit is asserted"
+      swaccess: "rw"
+      hwaccess: "hro"
+      fields: [
+        { bits: "31:0" }
+      ]
+    }
+
+    { name:     "INTERRUPTS"
+      desc:     "Write any value to assert an interrupt. Write 0 or 1 to disable or enable an interrupt."
+      swaccess: "rw"
+      hwaccess: "hro"
+      hwqe: "true"    # Used to catch software writes
+      fields: [
+        { bits: "0", name: "REACHED",     desc: "Watermark reached interrupt" }
+      ]
+    }
+
+  ]
+}
+

hw/ip_examples/iffifo/iffifo.core

@@ -0,0 +1,26 @@
+CAPI=2:
+
+name: "example:ip:iffifo"
+description: "core-v-mini-mcu iffifo peripheral"
+
+# 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: Pierre Guillod <[email protected]>, EPFL, STI-SEL
+# Date: 18.10.2023
+
+filesets:
+  files_rtl:
+    depend:
+      - pulp-platform.org::common_cells
+    files:
+    - rtl/iffifo_reg_pkg.sv
+    - rtl/iffifo_reg_top.sv
+    - rtl/iffifo.sv
+    file_type: systemVerilogSource
+
+targets:
+  default:
+    filesets:
+    - files_rtl

hw/ip_examples/iffifo/iffifo.vlt

@@ -0,0 +1,15 @@
+// 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: Pierre Guillod <[email protected]>, EPFL, STI-SEL
+// Date: 18.10.2023
+
+`verilator_config
+
+lint_off -rule DECLFILENAME -file "*/iffifo/rtl/iffifo_reg_top.sv" -match "Filename 'iffifo_reg_top' does not match MODULE name: 'iffifo_reg_top_intf'*"
+lint_off -rule WIDTH -file "*/iffifo/rtl/iffifo_reg_top.sv" -match "Operator ASSIGNW expects 3 bits on the Assign RHS, but Assign RHS's SEL generates 32*"
+lint_off -rule UNUSED -file "*/iffifo/rtl/iffifo.sv" -match "Bits of signal are not used: 'reg2hw'[0]*"
+
+lint_off -rule UNUSED -file "*/iffifo/rtl/iffifo_window.sv" -match "Bits of signal are not used: 'rx_win_i'[67:64,31:0]"
+lint_off -rule WIDTH -file "*/iffifo/rtl/iffifo_*.sv" -match "Operator ASSIGNW expects*"

hw/ip_examples/iffifo/iffifo_gen.sh

@@ -0,0 +1,8 @@
+# Copyright EPFL contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+echo "Generating RTL"
+${PYTHON} ../../vendor/pulp_platform_register_interface/vendor/lowrisc_opentitan/util/regtool.py -r -t rtl data/iffifo.hjson
+echo "Generating SW"
+${PYTHON} ../../vendor/pulp_platform_register_interface/vendor/lowrisc_opentitan/util/regtool.py --cdefines -o ../../../sw/device/lib/drivers/iffifo/iffifo_regs.h data/iffifo.hjson