Skip to content

Commit

Permalink
Edit DOC (#480)
Browse files Browse the repository at this point in the history 
* Edit IDEs doc structure and fix broken images

* Remove

* Updated documentation on requirements to run vivado

---------

Co-authored-by: Juan Sapriza <[email protected]>
  • Loading branch information
@LuigiGiuffrida98 @JuanSapriza
LuigiGiuffrida98 and JuanSapriza authored Apr 15, 2024
1 parent a49c47a commit d2e3aaa
Show file tree
Hide file tree
Showing 9 changed files with 275 additions and 260 deletions.
244 changes: 1 addition & 243 deletions docs/source/How_to/CompileMakefile.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,166 +73,6 @@ 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

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 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](./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

Expand Down Expand Up @@ -292,86 +132,4 @@ For both usages (commands or manual), the order of the arguments is irrelevant.
* 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](./Debug.md) guide to debug core-v-mini-mcu.

## Execute From Flash

Follow the [ExecuteFromFlash](./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.

Two FPGA boards are supported: the Xilinx Pynq-z2 and Nexys-A7-100t.

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 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](./Debug.md) guide
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).

### 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).
The success of the script is not required for merging of a PR.
2 changes: 1 addition & 1 deletion docs/source/How_to/Debug.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
1. Install the required linux tools:

```
sudo apt install pkg-config libftdi1-2 libusb-1.0-4
sudo apt install pkg-config libftdi1-2
```

You need at least gcc>10, so in case you do not have it:
Expand Down
24 changes: 14 additions & 10 deletions docs/source/How_to/GettingStarted.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# Get started

## 1. OS requirements
## Docker setup



## Manual setup

### 1. OS requirements

To use `X-HEEP`, first make sure you have the following apt packages, or install them as:

Expand All @@ -10,16 +16,14 @@ sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 lib

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
### 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
#### 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:
Expand All @@ -35,7 +39,7 @@ conda activate core-v-mini-mcu
```


### 2.b Virtual Environment
#### 2.b Virtual Environment

Install the python virtual environment just as:

Expand All @@ -49,7 +53,7 @@ You need to do it only the first time, then just activate the environment everyt
source .venv/bin/activate
```

## 3. Install the RISC-V Compiler:
### 3. Install the RISC-V Compiler:

```
git clone --branch 2022.01.17 --recursive https://github.com/riscv/riscv-gnu-toolchain
Expand All @@ -75,7 +79,7 @@ cmake -G "Unix Makefiles" -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Releas
cmake --build . --target install
```

## 4. Install Verilator:
### 4. Install Verilator:

```
export VERILATOR_VERSION=4.210
Expand Down Expand Up @@ -104,7 +108,7 @@ sudo apt install libcanberra-gtk-module libcanberra-gtk3-module
sudo apt-get install -y gtkwave
```

## Files are formatted with Verible
### Files are formatted with Verible

We use version v0.0-1824-ga3b5bedf

Expand All @@ -115,7 +119,7 @@ To format your RTL code type:
```
make verible
```
## Compilation Flow and Package Manager
### Compilation Flow and Package Manager

We use [FuseSoC](https://github.com/olofk/fusesoc) for all the tools we use.

Expand Down
12 changes: 6 additions & 6 deletions docs/source/How_to/IDEs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
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.


## 1. SES installation.
## 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
## 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.

Expand All @@ -22,23 +22,23 @@ gdb_server_command_line="/home/< user >/tools/openocd/bin/openocd -f &quot;$(Pro
```
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
## 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>
<p align="left"><img src="../_static/ides/build_screenshot.png" width="600"></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
## 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>
<p align="left"><img src="../_static/ides/debug_screenshot.png" width="600"></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.

Expand Down
Loading

0 comments on commit d2e3aaa

Please sign in to comment.