diff --git a/README.md b/README.md index c97054740..7d2a32734 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,22 @@ +
+

+ +`X-HEEP` (eXtendable Heterogeneous Energy-Efficient Platform) is a `RISC-V` microcontroller described in `SystemVerilog` +that can be configured to target small and tiny platforms as well as extended to support accelerators. +The cool thing about `X-HEEP` is that we provide a simple customizable MCU, so CPUs, common peripherals, memories, etc. +so that you can extend it with your own accelerator without modifying the MCU, but just instantiating it in your design. +By doing so, you inherit an IP capable of booting RTOS (such as `freeRTOS`) with the whole FW stack, including `HAL` drivers and `SDK`, +and you can focus on building your special HW supported by the microcontroller. + +`X-HEEP` supports simulation with Verilator, Questasim, etc. Morever, FW can be built and linked by using `CMake` either with gcc or with clang. It can be implemented on FPGA, and it supports implementation in Silicon, which is its main (but not only) target. See below for more details. + +The block diagram below shows the `X-HEEP` MCU + +

+ + +> :bookmark_tabs: Please refer to the documentation in [Read the Docs](https://x-heep.readthedocs.io/en/latest/index.html) + # Repository folder structure . @@ -23,22 +42,6 @@ ├── util └── README.md -
-

- -`X-HEEP` (eXtendable Heterogeneous Energy-Efficient Platform) is a `RISC-V` microcontroller described in `SystemVerilog` -that can be configured to target small and tiny platforms as well as extended to support accelerators. -The cool thing about `X-HEEP` is that we provide a simple customizable MCU, so CPUs, common peripherals, memories, etc. -so that you can extend it with your own accelerator without modifying the MCU, but just instantiating it in your design. -By doing so, you inherit an IP capable of booting RTOS (such as `freeRTOS`) with the whole FW stack, including `HAL` drivers and `SDK`, -and you can focus on building your special HW supported by the microcontroller. - -`X-HEEP` supports simulation with Verilator, Questasim, etc. Morever, FW can be built and linked by using `CMake` either with gcc or with clang. It can be implemented on FPGA, and it supports implementation in Silicon, which is its main (but not only) target. See below for more details. - -The block diagram below shows the `X-HEEP` MCU - -

- # Reference If you use X-HEEP in your academic work you can cite us: [X-HEEP Paper](https://arxiv.org/abs/2401.05548) @@ -52,618 +55,4 @@ If you use X-HEEP in your academic work you can cite us: [X-HEEP Paper](https:// archivePrefix={arXiv}, primaryClass={cs.AR} } -``` - -# Self-documented Makefile - -Note that under `util` folder, the file `generate-makefile-help` is employed to generate a self-documented helping output. In case of including any other target or command under the main `Makefile`, follow the same general and parameter descriptions as already provided for every target. Check the `help` output by doing `make` or `make help`. Moreover, **note that some of the parameters required for some of the targets are initiated with _default values_** - -# Prerequisite - -## 1. OS requirements - -To use `X-HEEP`, first make sure you have the following apt packages, or install them as: - -```bash -sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 libssl-dev libudev-dev libusb-1.0-0 lsb-release texinfo autoconf cmake flex bison libexpat-dev gawk tree xterm python3-venv python3-dev -``` - -In general, have a look at the [Install required software](https://opentitan.org/guides/getting_started/index.html) section of the OpenTitan documentation. - -It has been tested only on `Ubuntu 20`, and we know it does NOT WORK on `Ubuntu 22`. - -## 2. Python - -We rely on either (a) `miniconda`, or (b) `virtual environment` enviroment. - -Choose between `2.a` or `2.b` to setup your enviroment. - -### 2.a Miniconda - -Install [Miniconda](https://docs.conda.io/en/latest/miniconda.html#linux-installers) python 3.8 version as described in the link, -and create the Conda enviroment: - -```bash -make conda -``` - -You need to do it only the first time, then just activate the environment everytime you work with `X-HEEP` as - -```bash -conda activate core-v-mini-mcu -``` - -### 2.b Virtual Environment - -Install the python virtual environment just as: - -```bash -make venv -``` - -You need to do it only the first time, then just activate the environment everytime you work with `X-HEEP` as - -```bash -source .venv/bin/activate -``` - -## 3. Install the RISC-V Compiler: - -``` -git clone --branch 2022.01.17 --recursive https://github.com/riscv/riscv-gnu-toolchain -cd riscv-gnu-toolchain -./configure --prefix=/home/$USER/tools/riscv --with-abi=ilp32 --with-arch=rv32imc --with-cmodel=medlow -make -``` - -Then, set the `RISCV` env variable as: - -``` -export RISCV=/home/$USER/tools/riscv -``` - -Optionally you can also compile with clang/LLVM instead of gcc. For that you must install the clang compiler into the same `RISCV` path. The binaries of gcc and clang do not collide so you can have both residing in the same `RISCV` directory. For this you can set the `-DCMAKE_INSTALL_PREFIX` cmake variable to `$RISCV` when building LLVM. This can be accomplished by doing the following: - -``` -git clone https://github.com/llvm/llvm-project.git -cd llvm-project -git checkout llvmorg-14.0.0 -mkdir build && cd build -cmake -G "Unix Makefiles" -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$RISCV -DLLVM_TARGETS_TO_BUILD="RISCV" ../llvm -cmake --build . --target install -``` - -## 4. Install Verilator: - -``` -export VERILATOR_VERSION=4.210 - -git clone https://github.com/verilator/verilator.git -cd verilator -git checkout v$VERILATOR_VERSION - -autoconf -./configure --prefix=/home/$USER/tools/verilator/$VERILATOR_VERSION -make -make install -``` -Then, set the `PATH` env variable to as: - -``` -export PATH=/home/$USER/tools/verilator/$VERILATOR_VERSION/bin:$PATH -``` - -In general, have a look at the [Install Verilator](https://opentitan.org/guides/getting_started/setup_verilator.html) section of the OpenTitan documentation. - -If you want to see the vcd waveforms generated by the Verilator simulation, install GTKWAVE: - -``` -sudo apt install libcanberra-gtk-module libcanberra-gtk3-module -sudo apt-get install -y gtkwave -``` - -## Files are formatted with Verible - -We use version v0.0-1824-ga3b5bedf - -See: [Install Verible](https://opentitan.org/guides/getting_started/index.html#step-7a-install-verible-optional) - -To format your RTL code type: - -``` -make verible -``` - -## Docker alternative - -A docker image containing all the required software dependancies is available on [github-packages](https://github.com/orgs/esl-epfl/packages/container/package/x-heep-toolchain). - -It is only required to install [`docker`](https://docs.docker.com/get-docker/) and pull the image. - -```bash -docker pull ghcr.io/esl-epfl/x-heep-toolchain:latest -``` - -Assuming that X-HEEP has been cloned to `X-HEEP-DIR=\absolute\path\to\x-HEEP\folder`, it is possible to directly run the docker mounting `X-HEEP-DIR` to the path `\workspace\x-heep` in the docker. - -```bash -docker run -it -v ${X-HEEP-DIR}:/workspace/x-heep ghcr.io/esl-epfl/x-heep-toolchain -``` - -Take care to indicate the absolute path to the local clone of X-HEEP, otherwise `docker` will not be able to properly nount the local folder in the container. - -All the command listed in the README can be execute in the docker container, except for: -- Simulation with Questasim and VCS, synthesis with Design Compiler (licenses are required to use these tools, so they are not installed in the container) -- OpenRoad flow is not installed in the container, so it is not possible to run the related make commands - -## Compilation Flow and Package Manager - -We use [FuseSoC](https://github.com/olofk/fusesoc) for all the tools we use. - -The `fusesoc` commands are inside the Makefile. - -# Adding external IPs - -This repository relies on [Vendor](https://opentitan.org/book/util/doc/vendor.html) to add new IPs. The `vendor.py` script in the [`./util`](./util/) folder implements what is described above, while [this](./docs/source/How_to/ExternalDevices.md) file contains additional information on how to connect external devices to the system. - -# Compiling with Makefile - -You can compile the example applications and the platform using the Makefile. Type 'make help' or 'make' for more information. Moreover, please, check the different 'clean' commands to verify that you are using the corret one. - -## Generate core-v-mini-mcu package - -First, you have to generate the SystemVerilog package and C header file of the core-v-mini-mcu: - -``` -make mcu-gen -``` - -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 -``` - -The last command generates x-heep with the cv32e40p core, with a parallel bus, and 16 memory banks (12 continuous and 4 interleaved), -each 32KB, for a total memory of 512KB. - -If you are using `X-HEEP` just as a controller for your own system and you do not need any peripheral, you can use the `minimal` configuration file -when generating the MCU as: - -``` -make mcu-gen MCU_CFG=mcu_cfg_minimal.hjson -``` - -The `minimal` configuration is a work-in-progress, thus not all the APPs have been tested. - -## Compiling Software - -Don't forget to set the `RISCV` env variable to the compiler folder (without the `/bin` included). -To run 'hello world' application, just type 'make app'. - -``` -make app -``` - -To run any other application, please use the following command with appropiate parameters: - -``` -app PROJECT= TARGET=sim(default),systemc,pynq-z2,nexys-a7-100t,zcu104 LINKER=on_chip(default),flash_load,flash_exec COMPILER=gcc(default),clang COMPILER_PREFIX=riscv32-unknown-(default) ARCH=rv32imc(default), - -Params: -- PROJECT (ex: , hello_world(default)) -- TARGET (ex: sim(default),systemc,pynq-z2,nexys-a7-100t,zcu104) -- LINKER (ex: on_chip(default),flash_load,flash_exec) -- COMPILER (ex: gcc(default),clang) -- COMPILER_PREFIX (ex: riscv32-unknown-(default)) -- ARCH (ex: rv32imc(default),) -``` - -For instance, to run 'hello world' app for the pynq-z2 FPGA targets, just run: - -``` -make app TARGET=pynq-z2 -``` - -Or, if you use the OpenHW Group [GCC](https://www.embecosm.com/resources/tool-chain-downloads/#corev) compiler with CORE_PULP extensions, make sure to point the `RISCV` env variable to the OpenHW Group compiler, then just run: - -``` -make app COMPILER_PREFIX=riscv32-corev- ARCH=rv32imc_zicsr_zifencei_xcvhwlp_xcvmem_xcvmac_xcvbi_xcvalu_xcvsimd_xcvbitmanip -``` - -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`. - -After that, you can run the command to compile and link the FreeRTOS based application. Please also set 'LINKER' and 'TARGET' parameters if needed. - -``` -make app PROJECT=blinky_freertos -``` - -The main FreeRTOS configuration is allocated under `sw\freertos`, in `FreeRTOSConfig.h`. Please, change this file based on your application requirements. -Moreover, FreeRTOS is being fetch from 'https://github.com/FreeRTOS/FreeRTOS-Kernel.git' by CMake. Specifically, 'V10.5.1' is used. Finally, the fetch repository is located under `sw\build\_deps` after building. - -## Simulating - -This project supports simulation with Verilator, Synopsys VCS, Siemens Questasim and Cadence Xcelium. -It relies on `fusesoc` to handle multiple EDA tools and parameters. -For example, if you want to set the `FPU` and `COREV_PULP` parameters of the `cv32e40p` CPU, -you need to add next to your compilation command `FUSESOC_PARAM="--COREV_PULP=1 --FPU=1"` -Below the different EDA examples commands. - -### Compiling for Verilator (C++ testbench) - -To simulate your application with Verilator, first compile the HDL: - -``` -make verilator-sim -``` - -then, go to your target system built folder - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator -``` - -and type to run your compiled software: - -``` -./Vtestharness +firmware=../../../sw/build/main.hex -``` - -or to execute all these three steps type: - -``` -make run-helloworld -``` - -### Compiling for Verilator (SystemC testbench) - -To simulate your application with Verilator using `SystemC`, - -make sure you have `SystemC 2.3.3` installed, if not, find it [here](https://www.accellera.org/downloads/standards/systemc). - -Make sure to have the following env variables set: - -``` -export SYSTEMC_INCLUDE=/your_path_to_systemc/systemc/include/ -export SYSTEMC_LIBDIR=/your_path_to_systemc/systemc/lib-linux64/ -``` - -Compile the HDL: - -``` -make verilator-sim-sc -``` - -then, go to your target system built folder - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim_sc-verilator -``` - -and type to run your compiled software: - -``` -./Vtestharness +firmware=../../../sw/build/main.hex -``` - -If you want to know what is special about the SystemC testbench, have a look [here](./docs/source/How_to/SystemC.md) - -### Compiling for VCS - -To simulate your application with VCS, first compile the HDL: - -``` -make vcs-sim -``` - -then, go to your target system built folder - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-vcs -``` - -and type to run your compiled software: - -``` -./openhwgroup.org_systems_core-v-mini-mcu_0 +firmware=../../../sw/build/main.hex -``` - -Waveforms can be viewed with Verdi. Make sure you have the env variable `VERDI_HOME` set to your Verdi install folder, then run your compiled software as above, but with the `-gui` flag: - -``` -./openhwgroup.org_systems_core-v-mini-mcu_0 +firmware=../../../sw/build/main.hex -gui -``` - -An Analog / Mixed-Signal simulation of X-HEEP, combining both the RTL system verilog files for the digital part and a SPICE file connected through a `control.init` file for the analog / mixed-signal part, 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 same executable as for the digital simulation. Note that with Verdi you can view both the digital and the analog waveforms. - -Additional instructions on how to run an analog / mixed-signal simulation of X-HEEP can be found [here](./docs/source/How_to/AnalogMixedSignal.md). To try out the simulation, we provide an example SPICE netlist of an simple 1-bit ADC created by us and exported from [xschem](https://xschem.sourceforge.io/stefan/index.html) and which uses the PTM 65nm bulk CMOS model from [https://ptm.asu.edu](https://ptm.asu.edu/). - -### Compiling for Questasim - -To simulate your application with Questasim, first set the env variable `MODEL_TECH` to your Questasim bin folder, then compile the HDL: - -``` -make questasim-sim -``` - -then, go to your target system built folder - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-modelsim/ -``` - -and type to run your compiled software: - -``` -make run PLUSARGS="c firmware=../../../sw/build/main.hex" -``` - -You can also use vopt for HDL optimized compilation: - -``` -make questasim-sim-opt -``` - -then go to - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim_opt-modelsim/ -``` -and - -``` -make run RUN_OPT=1 PLUSARGS="c firmware=../../../sw/build/main.hex" -``` - -You can also compile with the UPF power domain description as: - -``` -make questasim-sim-opt-upf FUSESOC_PARAM="--USE_UPF" -``` - -and then execute software as: - -``` -make run RUN_OPT=1 RUN_UPF=1 PLUSARGS="c firmware=../../../sw/build/main.hex" -``` - -Questasim version must be >= Questasim 2020.4 - -### Compiling for Xcelium - -To simulate your application with Xcelium, first compile the HDL: - -``` -make xcelium-sim -``` - -then, go to your target system built folder - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-xcelium/ -``` - -and type to run your compiled software: - -``` -make run PLUSARGS="c firmware=../../../sw/build/main.hex" -``` - -### UART DPI - -To simulate the UART, we use the LowRISC OpenTitan [UART DPI](https://github.com/lowRISC/opentitan/tree/master/hw/dv/dpi/uartdpi). -Read how to interact with it in the Section "Running Software on a Verilator Simulation with Bazel" [here](https://opentitan.org/guides/getting_started/setup_verilator.html#running-software-on-a-verilator-simulation-with-bazel). -The output of the UART DPI module is printed in the `uart0.log` file in the simulation folder. - -For example, to see the "hello world!" output of the Verilator simulation: - -``` -cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator -./Vtestharness +firmware=../../../sw/build/main.hex -cat uart0.log -``` - -## Automatic testing - -X-HEEP includes two tools to perform automatic tests over your modifications. - -### Github CIs - -Upon push, tests are run on Github runners, these include: -* The generated `.sv` files pushed are equal to those generated in the runner (the code does not depend on the modification of generated files) -* Vendor is up to date (the code does not depend on the modification of vendorized files) -* All applications can be built successfully using both gcc and clang - -All test must be successful before PRs can be merged. - -### Simulation script - -Additionally, a `test_all.sh` script is provided. Apart from compiling all apps with both gcc and clang, it will simulate them and check the result. - -The available parameters are: -* COMPILER: `gcc` (default) or `clang` (can provide more than one) -* SIMULATOR: `verilator` (default), `questasim` or disable simulation with `nosim` (only one, the last provided is used). -* LINKER: `on_chip`(default), `flash_load` or `flash_exec` (can provide more than one) -* TIMEOUT: Integer number of seconds (default 120) - -#### Usage - -##### Comands -You can use two different commands to compile or simulate all the existing APPs: -``` -make app-compile-all -``` -``` -make app-simulate-all -``` -Note that both commands allow the previous parameters to specify compiling or simulation options. E.g.: -``` -make app-simulate-all LINKER=on_chip SIMULATOR=questasim COMPILER=clang TIMEOUT=150 -``` - -##### Manually -You can also **SOURCE** the script as -```bash -. util/test_all.sh on_chip questasim clang 150 -``` - -*Pay special attention to the first period in the command!* -You will be killing simulations that take too long, if you **EXECUTE** (`./test_all.sh`) this action kills the script. - -For both usages (commands or manual), the order of the arguments is irrelevant. - -> Note: Be sure to commit all your changes before running the script! - -* Applications that fail being built with gcc will not be simulated (skipped). -* Some applications are skipped by default for not being suitable for simulation. -* If a simulation takes too long (>timeout), it is killed. - -* Upon starting, the script will modify the `mcu_cfg.hjson` file to include all peripherals (so the largest number of apps can be run), re-generates the mcu and re-builds the simulation model for the chosen tool. -These changes can be reverted at the end of the execution (default). If changes were not commited, accepting this operation will revert them! - -The success of the script is not required for merging of a PR. - -## Debug - -Follow the [Debug](./docs/source/How_to/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](./docs/source/How_to/ExecuteFromFlash.md) guide to exxecute code directly from the FLASH with modelsim, FPGA, or ASIC. - -## Emulation on Xilinx FPGAs - -This project offers two different X-HEEP implementetions on Xilinx FPGAs, called Standalone and FEMU. - -### Standalone - -In this version, the X-HEEP architecture is implemented on the programmable logic (PL) side of the FPGA, and its input/output are connected to the available headers on the FPGA board. - -Three FPGA boards are supported: the Xilinx Pynq-z2, Nexys-A7-100t, Zynq Ultrascale+ ZCU104. - -Make sure you have the FPGA board files installed in your Vivado. - -For example, for the Pynq-Z2 board, use the documentation provided at the following [link](https://pynq.readthedocs.io/en/v2.5/overlay_design_methodology/board_settings.html) to download and install them: - -To build and program the bitstream for your FPGA with vivado, type: - -``` -make vivado-fpga FPGA_BOARD=pynq-z2 -``` - -or - -``` -make vivado-fpga FPGA_BOARD=nexys-a7-100t -``` - -or - -``` -make vivado-fpga FPGA_BOARD=zcu104 -``` - -or add the flag `use_bscane_xilinx` to use the native Xilinx scanchain: - -``` -make vivado-fpga FPGA_BOARD=pynq-z2 FUSESOC_FLAGS=--flag=use_bscane_xilinx -``` - -Only Vivado 2021.2 has been tried. - -To program the bitstream, open Vivado, - -``` -open --> Hardware Manager --> Open Target --> Autoconnect --> Program Device -``` - -and choose the file `openhwgroup.org_systems_core-v-mini-mcu_0.bit`. - -Or simply type: - -``` -bash vivado-fpga-pgm FPGA_BOARD=pynq-z2 -``` - -or - -``` -make vivado-fpga-pgm FPGA_BOARD=nexys-a7-100t -``` - -To run SW, follow the [Debug](./docs/source/How_to/Debug.md) guide -to load the binaries with the HS2 cable over JTAG, -or follow the [ExecuteFromFlash](./docs/source/How_to/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](./docs/source/How_to/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). - -### FPGA EMUlation Platform (FEMU) - -In this version, the X-HEEP architecture is implemented on the programmable logic (PL) side of the Xilinx Zynq-7020 chip on the Pynq-Z2 board and Linux is run on the ARM-based processing system (PS) side of the same chip. - -NOTE: This platform is not part of this repository, but you can access it with the following link: [FEMU](https://github.com/esl-epfl/x-heep-femu-sdk). - -# ASIC Implementation - -This project can be implemented using standard cells based ASIC flow. - -## Synthesis with Synopsys Design Compiler - -First, you need to provide technology-dependent implementations of some of the cells which require specific instantiation. - -Then, please provide a set_libs.tcl and set_constraints.tcl scripts to set link and target libraries, and constraints as the clock. - -To generate the `analyze` script for the synthesis scripts with DC, execute: - -``` -make asic -``` - -## OpenRoad support for SkyWater 130nm - -We are working on supporting OpenRoad and SkyWater 130nm PDK, please refer to the -[Implement on ASIC](./docs/source/How_to/ImplementASIC.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. +``` \ No newline at end of file diff --git a/docs/source/How_to/AnalogMixedSignal.md b/docs/source/How_to/AnalogMixedSignal.md index 8ba4ed5c3..841b8a882 100644 --- a/docs/source/How_to/AnalogMixedSignal.md +++ b/docs/source/How_to/AnalogMixedSignal.md @@ -1,4 +1,4 @@ -# integrate Analog / Mixed-Signal simulations +# Integrate Analog / Mixed-Signal simulations ## About diff --git a/docs/source/How_to/CompileMakefile b/docs/source/How_to/CompileMakefile.md similarity index 92% rename from docs/source/How_to/CompileMakefile rename to docs/source/How_to/CompileMakefile.md index 2db8a17d0..14a877319 100644 --- a/docs/source/How_to/CompileMakefile +++ b/docs/source/How_to/CompileMakefile.md @@ -1,4 +1,4 @@ -# compile with Makefile +# Compile with Makefile You can compile the example applications and the platform using the Makefile. Type 'make help' or 'make' for more information. Moreover, please, check the different 'clean' commands to verify that you are using the corret one. @@ -53,7 +53,7 @@ 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 +make app COMPILER_PREFIX=riscv32-corev- ARCH=rv32imc_zicsr_zifencei_xcvhwlp_xcvmem_xcvmac_xcvbi_xcvalu_xcvsimd_xcvbitmanip ``` This will create the executable file to be loaded in your target system (ASIC, FPGA, Simulation). @@ -75,7 +75,7 @@ Moreover, FreeRTOS is being fetch from 'https://github.com/FreeRTOS/FreeRTOS-Ker ## Simulating -This project supports simulation with Verilator, Synopsys VCS, and Siemens Questasim. +This project supports simulation with Verilator, Synopsys VCS, Siemens Questasim and Cadence Xcelium. It relies on `fusesoc` to handle multiple EDA tools and parameters. For example, if you want to set the `FPU` and `COREV_PULP` parameters of the `cv32e40p` CPU, you need to add next to your compilation command `FUSESOC_PARAM="--COREV_PULP=1 --FPU=1"` @@ -147,7 +147,7 @@ cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-vcs and running the same executable as for the digital simulation. Note that with Verdi you can view both the digital and the analog waveforms. -Additional instructions on how to run an analog / mixed-signal simulation of X-HEEP can be found [here](AnalogMixedSignal.md). To try out the simulation, we provide an example SPICE netlist of an simple 1-bit ADC created by us and exported from [xschem](https://xschem.sourceforge.io/stefan/index.html) and which uses the PTM 65nm bulk CMOS model from [https://ptm.asu.edu](https://ptm.asu.edu/). +Additional instructions on how to run an analog / mixed-signal simulation of X-HEEP can be found [here](./AnalogMixedSignal.md). To try out the simulation, we provide an example SPICE netlist of an simple 1-bit ADC created by us and exported from [xschem](https://xschem.sourceforge.io/stefan/index.html) and which uses the PTM 65nm bulk CMOS model from [https://ptm.asu.edu](https://ptm.asu.edu/). ### Compiling for Questasim @@ -200,6 +200,26 @@ make run RUN_OPT=1 RUN_UPF=1 PLUSARGS="c firmware=../../../sw/build/main.hex" Questasim version must be >= Questasim 2020.4 +### Compiling for Xcelium + +To simulate your application with Xcelium, first compile the HDL: + +``` +make xcelium-sim +``` + +then, go to your target system built folder + +``` +cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-xcelium/ +``` + +and type to run your compiled software: + +``` +make run PLUSARGS="c firmware=../../../sw/build/main.hex" +``` + ### UART DPI To simulate the UART, we use the LowRISC OpenTitan [UART DPI](https://github.com/lowRISC/opentitan/tree/master/hw/dv/dpi/uartdpi). @@ -322,7 +342,19 @@ To program the bitstream, open Vivado, open --> Hardware Manager --> Open Target --> Autoconnect --> Program Device ``` -and choose the file `openhwgroup.org_systems_core-v-mini-mcu_0.bit` +and choose the file `openhwgroup.org_systems_core-v-mini-mcu_0.bit`. + +Or simply type: + +``` +bash vivado-fpga-pgm FPGA_BOARD=pynq-z2 +``` + +or + +``` +make vivado-fpga-pgm FPGA_BOARD=nexys-a7-100t +``` To run SW, follow the [Debug](./Debug.md) guide to load the binaries with the HS2 cable over JTAG, @@ -332,15 +364,10 @@ 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). ### FPGA EMUlation Platform (FEMU) diff --git a/docs/source/How_to/Debug.md b/docs/source/How_to/Debug.md index 2a5882f66..243d54469 100644 --- a/docs/source/How_to/Debug.md +++ b/docs/source/How_to/Debug.md @@ -1,4 +1,4 @@ -# debug +# Debug ## Prerequisite diff --git a/docs/source/How_to/ExecuteFromFlash.md b/docs/source/How_to/ExecuteFromFlash.md index 8413a1299..ce7b9a9c6 100644 --- a/docs/source/How_to/ExecuteFromFlash.md +++ b/docs/source/How_to/ExecuteFromFlash.md @@ -1,4 +1,4 @@ -# execute Code from FLASH +# Execute Code from FLASH ## Boot Procedure diff --git a/docs/source/How_to/ExternalDevices.md b/docs/source/How_to/ExternalDevices.md deleted file mode 100644 index bbc89bd32..000000000 --- a/docs/source/How_to/ExternalDevices.md +++ /dev/null @@ -1,151 +0,0 @@ -# interface with external devices - -The top module [`core_v_mini_mcu`]((./../../../hw/core-v-mini-mcu/corecore_v_mini_mcu.sv) exposes several external interfaces: - -- `ext_xbar_master`: N ports to connect external masters to the internal 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. - -- `ext_peripheral_slave`: 1 peripheral slave port connected to the system bus (through the peripheral interface). - -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: - -```bash -make app PROJECT=example_external_dma -``` - -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 -``` - -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: - -```bash -cat uart0.log -``` - -It should print: - -``` ---- MEMCOPY EXAMPLE - external peripheral --- -Init the PLIC...success -Set MEMCOPY interrupt priority to 1...success -Enable MEMCOPY interrupt...Success -Memcopy launched...finished -Complete interrupt...success -MEMCOPY SUCCESS -``` - -## Add an external master/slave or peripheral - -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). 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. - -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: - -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); - - . . . -} -``` \ No newline at end of file diff --git a/docs/source/How_to/GettingStarted.md b/docs/source/How_to/GettingStarted.md index e5b877dd4..d7c8dd318 100644 --- a/docs/source/How_to/GettingStarted.md +++ b/docs/source/How_to/GettingStarted.md @@ -1,4 +1,4 @@ -# get started +# Get started ## 1. OS requirements @@ -108,7 +108,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: diff --git a/IDEs.md b/docs/source/How_to/IDEs.md similarity index 98% rename from IDEs.md rename to docs/source/How_to/IDEs.md index e1fce194f..a4bb7728e 100644 --- a/IDEs.md +++ b/docs/source/How_to/IDEs.md @@ -1,14 +1,14 @@ +# Set up an IDE 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. +## 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. +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**: ``` @@ -34,7 +34,7 @@ Note that on the right part, you have the memory usage based on the linker we ha # 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. +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: diff --git a/docs/source/How_to/ImplementASIC.md b/docs/source/How_to/ImplementASIC.md index bacb70509..2ddf20c85 100644 --- a/docs/source/How_to/ImplementASIC.md +++ b/docs/source/How_to/ImplementASIC.md @@ -1,4 +1,4 @@ -# implement on ASIC +# Implement on ASIC This project can be implemented using standard cells based ASIC flow. diff --git a/docs/source/How_to/IntegratePeripheral.md b/docs/source/How_to/IntegratePeripheral.md index ae8b3b3f6..f39bdbd19 100644 --- a/docs/source/How_to/IntegratePeripheral.md +++ b/docs/source/How_to/IntegratePeripheral.md @@ -206,7 +206,7 @@ module #( b. The corresponding package must be imported: -```systemverilog +``` import _reg_pkg::*; ``` diff --git a/docs/source/How_to/ProgramFlash.md b/docs/source/How_to/ProgramFlash.md index 7ed89d246..efbe78a99 100644 --- a/docs/source/How_to/ProgramFlash.md +++ b/docs/source/How_to/ProgramFlash.md @@ -1,4 +1,4 @@ -# program the FLASH on the EPFL Programmer +# Program the FLASH on the EPFL Programmer Install the required linux tools: diff --git a/docs/source/How_to/UpdateDocumentation.md b/docs/source/How_to/UpdateDocumentation.md new file mode 100644 index 000000000..0997e90e4 --- /dev/null +++ b/docs/source/How_to/UpdateDocumentation.md @@ -0,0 +1,19 @@ +# Update the documentation + +All documentation is found in the `/docs` directory. + +1. If you need to create a new entry, add the new document in markdown (`.md` extension) to the corresponding folder. Otherwise, just edit the corresponding file. + + +> Make sure the document has one single `# header`, otherwise they will be considered different documents. + + +2. If a new folder is added, add it to the `toctree` inside `docs/source/index.rst` (as the `peripherals` folder is) +3. Commit and push +4. Once the branch is merged into the main branch of X-HEEP, anyone can open a terminal in the docs folder and run +```bash +make clean html +``` +5. Wait a few minutes and enjoy your brand new documentation in Read the Docs. + +Thank you for helping keep X-HEEP accurately and extensively documented! \ No newline at end of file diff --git a/docs/source/images/x-heep-outline.png b/docs/source/images/x-heep-outline.png new file mode 100644 index 000000000..b2aa5446f Binary files /dev/null and b/docs/source/images/x-heep-outline.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index e3968a3f4..f7605b7d7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,11 @@ X-HEEP ====== +.. image:: images/x-heep-outline.png + :width: 600 + + + ``X-HEEP`` (eXtendable Heterogeneous Energy-Efficient Platform) is a RISC-V microcontroller described in SystemVerilog that can be configured to target small and tiny platforms as well as extended to support accelerators. The cool thing about X-HEEP is that we provide a simple customizable MCU, so CPUs, common peripherals, memories, etc. so that you can extend it with your own accelerator without modifying the MCU, but just instantiating it in your design. By doing so, you inherit an IP capable of booting RTOS (such as FreeRTOS) with the whole FW stack, including HAL drivers and SDK, and you can focus on building your special HW or APP supported by the microcontroller. diff --git a/logo/x-heep.png b/logo/x-heep.png deleted file mode 100644 index 76814a075..000000000 Binary files a/logo/x-heep.png and /dev/null differ