esl-epfl · JoseCalero · Aug 11, 2022 · Aug 12, 2022 · Aug 17, 2022 · Aug 25, 2022
diff --git a/IDEs.md b/IDEs.md
@@ -0,0 +1,45 @@
+
+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. 
+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. 
+
+For the RISC-V Compiler path, **line 71**:
+```
+build_toolchain_directory="/home/< user >/tools/riscv/bin"
+```
+Please, substitute that path to your current path where the RISC-V compiler was installed. Do not forget to target the `bin` folder inside the installation folder of the toolchain.
+
+For the openOCS path, **line 88**:
+```
+gdb_server_command_line="/home/< user >/tools/openocd/bin/openocd -f &quot;$(ProjectDir)/../../tb/core-v-mini-mcu-pynq-z2-esl-programmer.cfg&quot;"
+```
+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
+
+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>
+
+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
+
+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>
+
+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.
+
+Further improvements and support will be provided and explain in following releases.
diff --git a/README.md b/README.md
@@ -238,10 +238,12 @@ 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
 ```
 
-This will create the executable file to be loaded in your target system (ASIC, FPGA, Simulation).
+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`.
@@ -462,6 +464,8 @@ The success of the script is not required for merging of a PR.
 
 Follow the [Debug](./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](./ExecuteFromFlash.md) guide to exxecute code directly from the FLASH with modelsim, FPGA, or ASIC.

diff --git a/docs/source/How_to/Debug.md b/docs/source/How_to/Debug.md
@@ -45,7 +45,7 @@ The remote bitbang server is simplemented in the folder ./hw/vendor/pulp_platfor
 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_PARAM="--JTAG_DPI=1"
+make verilator-sim "FUSESOC_PARAM="--JTAG_DPI=1"
 ```
 
 then, go to your target system built folder
@@ -65,7 +65,7 @@ and type to run your compiled software:
 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_PARAM="--JTAG_DPI=1"
+make questasim-sim "FUSESOC_PARAM="--JTAG_DPI=1"
 ```
 
 then, go to your target system built folder

diff --git a/ides/img/build_screenshot.png b/ides/img/build_screenshot.png
diff --git a/ides/img/debug_screenshot.png b/ides/img/debug_screenshot.png
diff --git a/ides/ses/xheep.emProject b/ides/ses/xheep.emProject
@@ -0,0 +1,155 @@
+<!DOCTYPE CrossStudio_Project_File>
+<solution Name="xheep_ses" target="20" version="2">
+  <configuration Name="Debug" hidden="Yes" />
+  <configuration
+    Name="Debug External"
+    build_toolchain_directory="$(ProjectDir)/tools/riscv/bin"
+    inherited_configurations="External GNU" />
+  <configuration
+    Name="Debug Internal"
+    inherited_configurations="Internal;Debug" />
+  <configuration Name="External GNU" Platform="RISCV" hidden="Yes" />
+  <configuration
+    Name="Release"
+    c_preprocessor_definitions="NDEBUG"
+    gcc_debugging_level="Level 2"
+    gcc_omit_frame_pointer="Yes"
+    gcc_optimization_level="Level 2 balanced"
+    hidden="Yes" />
+  <configuration
+    Name="Release External"
+    inherited_configurations="External GNU" />
+  <configuration
+    Name="Release Internal"
+    inherited_configurations="Internal;Release" />
+  <project Name="helloworld">
+    <configuration
+      LIBRARY_HEAP_TYPE="None"
+      LIBRARY_IO_TYPE="SEMIHOST (host-formatted)"
+      Name="Common"
+      arm_keep_assembly="Yes"
+      arm_linker_search_path="$(ProjectDir)/../../sw/device/lib/base/;$(ProjectDir)/../../sw/device/lib/base/freestanding/;$(ProjectDir)/../../sw/device/lib/runtime/;$(ProjectDir)/../../sw/device/lib/drivers/uart/;$(ProjectDir)/../../sw/device/lib/drivers/rv_plic/;$(ProjectDir)/../../sw/device/lib/drivers/fast_intr_ctrl/;$(ProjectDir)/../../sw/device/lib/drivers/soc_ctrl/;$(ProjectDir)/../../sw/device/lib/drivers/i2s/;$(ProjectDir)/../../sw/device/lib/drivers/i2c/;$(ProjectDir)/../../sw/device/lib/drivers/gpio/;$(ProjectDir)/../../sw/device/lib/drivers/dma/;$(ProjectDir)/../../sw/device/lib/drivers/spi_host/;$(ProjectDir)/../../sw/device/target/pynq-z2/"
+      build_always_rebuild="Yes"
+      build_quietly="No"
+      build_toolchain_directory=""
+      compiler_diagnostics_show_caret="No"
+      debug_target_connection="GDB Server"
+      gcc_debugging_level="Level 3"
+      gcc_dwarf_generate_pubnames="No"
+      gcc_dwarf_version="None"
+      gcc_short_enum="None"
+      gcc_use_cxa_at_exit="No"
+      gdb_server_allow_memory_access_during_execution="Yes"
+      gdb_server_autostart_server="No"
+      gdb_server_command_line=""
+      gdb_server_ignore_checksum_errors="No"
+      gdb_server_port="3333"
+      gdb_server_register_access="General and Individual"
+      gdb_server_reset_command="reset halt"
+      gdb_server_type="OpenOCD"
+      link_include_standard_libraries="No"
+      link_linker_script_file="$(ProjectDir)/../../sw/linker/link.ld"
+      link_use_linker_script_file="Yes"
+      linker_additional_files=""
+      linker_output_format="hex"
+      linker_pre_build_command="$(StudioDir)/bin/mkld -section-placement-file $(StudioDir)/targets/flash_placement_riscv.xml -memory-map-segments &quot;$(MemorySegments)&quot; -symbols __STACKSIZE__=1024;__HEAPSIZE__=1024 Setup/flash_rv32.ld"
+      linker_section_placements_segments="RAM0 RX 0x00000000 0x00000C800;RAM1 RWX 0x00000C800 0x00003800"
+      project_directory=""
+      project_type="Executable"
+      rv_abi="ilp32"
+      rv_architecture="rv32imc"
+      rv_relax="No"
+      target_device_name="RV32" />
+    <configuration
+      BUILD_OPTIONS="RV32 GNU"
+      Name="Debug External"
+      RISCV_TOOLCHAIN_VARIANT="Standard"
+      arm_assembler_variant="gcc"
+      arm_compiler_variant="gcc"
+      build_always_rebuild="Yes"
+      build_generic_options_file_name=""
+      build_toolchain_directory="/home/< user >/tools/riscv/bin"
+      c_additional_options="-march=rv32imc  -w -Os -g  -nostdlib"
+      c_include_files=""
+      c_preprocessor_definitions="HOST_BUILD;ON_CHIP"
+      c_user_include_directories="$(ProjectDir)/../../sw/device/lib/base/;$(ProjectDir)/../../sw/device/lib/base/freestanding/;$(ProjectDir)/../../sw/device/lib/runtime/;$(ProjectDir)/../../sw/device/lib/drivers/uart/;$(ProjectDir)/../../sw/device/lib/drivers/rv_plic/;$(ProjectDir)/../../sw/device/lib/drivers/fast_intr_ctrl/;$(ProjectDir)/../../sw/device/lib/drivers/soc_ctrl/;$(ProjectDir)/../../sw/device/lib/drivers/i2s/;$(ProjectDir)/../../sw/device/lib/drivers/i2c/;$(ProjectDir)/../../sw/device/lib/drivers/gpio/;$(ProjectDir)/../../sw/device/lib/drivers/dma/;$(ProjectDir)/../../sw/device/lib/drivers/spi_host/;$(ProjectDir)/../../sw/device/target/pynq-z2/"
+      c_user_include_directories_c_only=""
+      debug_target_connection="GDB Server"
+      external_build_file_name=""
+      external_c_compile_command="&quot;$(ToolChainDir)/$(GCCPrefix)gcc&quot; $(COptions) $(COnlyOptions) $(Defines) $(Undefines) $(Includes) $(IncludeFiles) -c &quot;$(RelInputPath)&quot; -o &quot;$(RelTargetPath)&quot;"
+      external_cpp_compile_command="&quot;$(ToolChainDir)/$(GCCPrefix)g++&quot; -c $(COptions) $(CppOnlyOptions) $(Defines) $(Undefines) $(Includes) $(IncludeFiles) &quot;$(RelInputPath)&quot; -MD -MF &quot;$(RelDependencyPath)&quot; -fno-diagnostics-show-caret -o &quot;$(RelTargetPath)&quot;"
+      external_cpp_link_command="&quot;$(ToolChainDir)/$(GCCPrefix)g++&quot; $(Objects) $(LinkOptions) -T &quot;$(RelLinkerScriptPath)&quot; -o &quot;$(RelTargetPath)&quot; -Xlinker -Map=&quot;$(RelMapPath)&quot;"
+      external_link_command="&quot;$(ToolChainDir)/$(GCCPrefix)gcc&quot; $(Objects) $(LinkOptions)  -Wl,-Map=&quot;$(RelMapPath)&quot; -T &quot;$(RelLinkerScriptPath)&quot; -o &quot;$(RelTargetPath)&quot;"
+      external_load_file_type="Detect"
+      gcc_cl_dwarf_version="None"
+      gdb_breakpoint_types="Hardware Only"
+      gdb_server_allow_memory_access_during_execution="Yes"
+      gdb_server_autostart_server="Yes"
+      gdb_server_command_line="/home/< user >/tools/openocd/bin/openocd -f &quot;$(ProjectDir)/../../tb/core-v-mini-mcu-pynq-z2-esl-programmer.cfg&quot;"
+      gdb_server_ignore_checksum_errors="No"
+      gdb_server_log_file="$(ProjectDir)/gdb_out.txt"
+      gdb_server_port="3333"
+      gdb_server_register_access="General and Individual"
+      gdb_server_reset_command="reset halt"
+      gdb_server_type="OpenOCD"
+      gnu_cl_enable_debug_info="Yes"
+      gnu_cl_optimization_level="None"
+      link_linker_script_file="$(ProjectDir)/../../sw/linker/link.ld"
+      linker_additional_options="-I &quot;$(ProjectDir)/../../sw/device/lib/base/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/base/freestanding/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/runtime/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/uart/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/rv_plic/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/fast_intr_ctrl/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/soc_ctrl/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/i2s/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/i2c/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/gpio/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/dma/&quot;;-I &quot;$(ProjectDir)/../../sw/device/lib/drivers/spi_host/&quot;;-I &quot;$(ProjectDir)/../../sw/device/target/pynq-z2/&quot;;-static &quot;$(ProjectDir)/../../sw/device/lib/crt/crt0.S&quot; &quot;$(ProjectDir)/../../sw/device/lib/crt/vectors.S&quot;;-L &quot;$(ToolChainDir)/../riscv32-unknown-elf/lib&quot;;-lc -lm -lgcc -flto -ffunction-sections -fdata-sections -specs=nano.specs -w -march=rv32imc  -Os -g  -nostdlib"
+      linker_post_build_command="$(ToolChainDir)/riscv32-unknown-elf-objdump -S  &quot;$(ProjectDir)/$(OutDir)/$(ProjectName).elf&quot; &gt; &quot;$(ProjectDir)/$(OutDir)/$(ProjectName).disasm&quot;"
+      linker_pre_build_command=""
+      linker_section_placements_segments="RAM0 RX 0x00000000 0x00000C800;RAM1 RWX 0x00000C800 0x00003800"
+      post_build_command="$(ToolChainDir)/riscv32-unknown-elf-objcopy -O verilog  &quot;$(ProjectDir)/$(OutDir)/$(ProjectName).elf&quot; &quot;$(ProjectDir)/$(OutDir)/$(ProjectName)_vfmt.hex&quot;"
+      pre_build_command=""
+      rv32gnu_cl_arch="rv32imc"
+      rv_arch_ext=""
+      rv_arch_zicsr="Yes"
+      rv_arch_zifencei="Yes"
+      rv_debug_extensions="None"
+      rv_toolchain_prefix=""
+      use_compiler_driver="No" />
+    <configuration
+      BUILD_OPTIONS="RV32 GNU"
+      Name="External GNU"
+      build_generic_options_file_name="$(StudioDir)/targets/RV32GNU_build_options.xml"
+      build_toolchain_directory=""
+      gcc_prefix="riscv32-unknown-elf-"
+      link_linker_script_file="Setup/flash_rv32.ld"
+      link_use_linker_script_file="Yes"
+      linker_additional_options=""
+      linker_pre_build_command="$(StudioDir)/bin/mkld -section-placement-file $(StudioDir)/targets/flash_placement_riscv.xml -memory-map-segments &quot;$(MemorySegments)&quot; -symbols __STACKSIZE__=1024;__HEAPSIZE__=1024 Setup/flash_rv32.ld"
+      project_type="Externally Built Executable"
+      rv32gnu_cl_abi="ilp32"
+      rv32gnu_cl_arch="rv32i" />
+    <configuration
+      Name="Release External"
+      gnu_cl_enable_debug_info="No"
+      gnu_cl_optimization_level="Level 1" />
+    <folder Name="base">
+      <file file_name="../../sw/device/lib/base/bitfield.c" />
+      <file file_name="../../sw/device/lib/base/memory.c" />
+      <file file_name="../../sw/device/lib/base/memory.h" />
+      <file file_name="../../sw/device/lib/base/mmio.c" />
+    </folder>
+    <folder Name="crt">
+      <file file_name="../../sw/device/lib/crt/crt0.S" />
+      <file file_name="../../sw/device/lib/crt/vectors.S" />
+    </folder>
+    <folder Name="drivers">
+      <file file_name="../../sw/device/lib/drivers/dma/dma.c" />
+      <file file_name="../../sw/device/lib/drivers/fast_intr_ctrl/fast_intr_ctrl.c" />
+      <file file_name="../../sw/device/lib/drivers/gpio/gpio.c" />
+      <file file_name="../../sw/device/lib/drivers/rv_plic/rv_plic.c" />
+      <file file_name="../../sw/device/lib/drivers/soc_ctrl/soc_ctrl.c" />
+      <file file_name="../../sw/device/lib/drivers/uart/uart.c" />
+    </folder>
+    <folder Name="runtime">
+      <file file_name="../../sw/device/lib/runtime/handler.c" />
+      <file file_name="../../sw/device/lib/runtime/init.c" />
+      <file file_name="../../sw/device/lib/runtime/syscalls.c" />
+    </folder>
+    <folder Name="source">
+      <file file_name="../../sw/applications/hello_world/main.c" />
+    </folder>
+  </project>
+</solution>
diff --git a/ides/ses/xheep.emSession b/ides/ses/xheep.emSession
@@ -0,0 +1,39 @@
+<!DOCTYPE CrossStudio_Session_File>
+<session>
+ <Bookmarks/>
+ <Breakpoints groups="Breakpoints" active_group="Breakpoints"/>
+ <ExecutionProfileWindow/>
+ <FrameBuffer/>
+ <Memory1/>
+ <Memory2/>
+ <Memory3/>
+ <Memory4/>
+ <Project>
+  <ProjectSessionItem path="xheep_ses"/>
+  <ProjectSessionItem path="xheep_ses;helloworld"/>
+ </Project>
+ <Register1/>
+ <Register2/>
+ <Register3/>
+ <Register4/>
+ <Threads>
+  <ThreadsWindow showLists=""/>
+ </Threads>
+ <TraceWindow>
+  <Trace enabled="Yes"/>
+ </TraceWindow>
+ <Watch1>
+  <Watches active="1" update="Never"/>
+ </Watch1>
+ <Watch2>
+  <Watches active="0" update="Never"/>
+ </Watch2>
+ <Watch3>
+  <Watches active="0" update="Never"/>
+ </Watch3>
+ <Watch4>
+  <Watches active="0" update="Never"/>
+ </Watch4>
+ <Files/>
+ <EMStudioWindow activeProject="helloworld" fileDialogDefaultFilter="*" autoConnectTarget="GDB Server" buildConfiguration="Debug External" sessionSettings="" debugSearchFileMap="" fileDialogInitialDirectory="" debugSearchPath="" autoConnectCapabilities="1343"/>
+</session>
diff --git a/readthedocs.yaml b/readthedocs.yaml
@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: docs/requirements.txt