Modifications to documentation (#400)

* Moved ide.md

* Updated the initial readme to point to read the docs

* Added how to change documentation

* Added logo

* Updated image location

* Updated documentation on how to update documention (the meta-update)

* Updated location of the logo in the main readme

* updating docs

* Removed comment

* Removed inconsistencies

---------

Co-authored-by: Hossein <[email protected]>

docs/source/How_to/AnalogMixedSignal.md

@@ -1,4 +1,4 @@
-#  integrate Analog / Mixed-Signal simulations
+#  Integrate Analog / Mixed-Signal simulations
 
 ## About
 

docs/source/How_to/CompileMakefile → 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)

docs/source/How_to/Debug.md

@@ -1,4 +1,4 @@
-#  debug
+#  Debug
 
 ## Prerequisite
 

docs/source/How_to/ExecuteFromFlash.md

@@ -1,4 +1,4 @@
-#  execute Code from FLASH
+#  Execute Code from FLASH
 
 ## Boot Procedure
 

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:
 

IDEs.md → 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:
 

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.
 

docs/source/How_to/IntegratePeripheral.md

@@ -206,7 +206,7 @@ module <peripheral> #(
 
 b. The corresponding package must be imported:
 
-```systemverilog
+```
 import <peripheral>_reg_pkg::*;
 ```
 

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:
 

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!

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.