diff --git a/.gitignore b/.gitignore index d369ddf84..ea9c6ccc8 100644 --- a/.gitignore +++ b/.gitignore @@ -54,7 +54,7 @@ sw/device/lib/drivers/**/*_structs.h flow/OpenROAD-flow-scripts # automatically generated docs -/docs/source/Configuration/generated +/docs/source/Configuration/x_heep_gen # User-dependent configuration files .vscode diff --git a/Makefile b/Makefile index 61d01468c..0dd22befd 100644 --- a/Makefile +++ b/Makefile @@ -150,9 +150,9 @@ verible: ## @param PROJECT= ## @param TARGET=sim(default),systemc,pynq-z2,nexys-a7-100t,zcu104 ## @param LINKER=on_chip(default),flash_load,flash_exec -## @param COMPILER=gcc(default), clang +## @param COMPILER=gcc(default),clang ## @param COMPILER_PREFIX=riscv32-unknown-(default) -## @param ARCH=rv32imc(default), +## @param ARCH=rv32imc(default), app: clean-app @$(MAKE) -C sw PROJECT=$(PROJECT) TARGET=$(TARGET) LINKER=$(LINKER) LINK_FOLDER=$(LINK_FOLDER) COMPILER=$(COMPILER) COMPILER_PREFIX=$(COMPILER_PREFIX) ARCH=$(ARCH) SOURCE=$(SOURCE) \ || { \ diff --git a/docs/source/Configuration/BusConfiguration.md b/docs/source/Configuration/BusConfiguration.md new file mode 100644 index 000000000..4cc3ee793 --- /dev/null +++ b/docs/source/Configuration/BusConfiguration.md @@ -0,0 +1,3 @@ +# Bus Type Configuration + +The bus type can either be configured to `NtoM` or `onetoM`. diff --git a/docs/source/Configuration/Configuration.rst b/docs/source/Configuration/Configuration.rst deleted file mode 100644 index c18a4e26b..000000000 --- a/docs/source/Configuration/Configuration.rst +++ /dev/null @@ -1,172 +0,0 @@ -Configuration -============= - -Project Configuration ---------------------- -The project can be configured either by a hjson file or a python script. -The default configurations and examples are located in the `config` directory. - -Hjson Configuration File -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. literalinclude:: ../../../configs/example_interleaved.hjson - :language: js - -Bus Type Configuration -^^^^^^^^^^^^^^^^^^^^^^ -The bus type can either be configured to `NtoM` or `onetoM`. - -Ram Bank Configuration -^^^^^^^^^^^^^^^^^^^^^^ - -The system can be configured with banks of different sizes. The sizes should be a power of two in kiB. -All banks are configured in one continuous address region. - - -To configure interleaved banks the number and the size of the banks have to be provided. -The following restrictions apply: All banks must have the same size and a power of two banks must be configured. - - -For continuous banks the default mode, only the `sizes` filed is required. -It can be either the size in kiB of a single bank, -a dictionary of the same format containing more banks, or a list of multiple entries. -If the `num` field is also provided the configuration in the `sizes` field is repeated `num` times. - -.. code:: js - - ram_banks: { - code: {sizes: 64} // configure just one bank - - data: { - type: continuous // the default, can be omitted - num: 2 - sizes: 32 - } - - alt_data: {sizes: [32, 32]} // the same as data but with a list - - more_complex: { - // This also works recursively so we can easily have different sizes of banks - // and in bigger numbers without listing them all one by one. - sizes: [ - { - num: 4 - sizes: 8 - }, - { - num: 16 - sizes: 4 - }, - ] - } - - } - - -Linker Section Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The linker script sections can be configured in two ways. -Either a section can be matched with a group of ram banks -or it can be manually defined. - -To automatically add a section the entry `auto_section: auto` should be added to the banks. -It will add a section that matches the banks exactly, it can only be used in the non recursive part. -The name of the section is set with the name of the group of banks. - -When manually setting the the linker section the name and the start address have to be provided. -Additionally the end is either provided by it's address or by the size of the section. -If no end is provided the end is inferred by the start of the next linker section. -Or if no section follows, the end address of the last ram bank. - -Both configuration types can be freely combined as long as no section overlap. -All sections will e sorted by the configuration system. - -The first two sections should always be code and data. -The other name can be used in code with a `.xheep_` prefix, like in `example_matadd_interleaved` - -.. code:: c - - int32_t __attribute__((section(".xheep_data_interleaved"))) m_c[16*16]; - -.. code:: js - - { - ram_address: 0 - bus_type: "onetoM", - ram_banks: { - code_and_data: { - num: 2 - sizes: [32] - } - i_am_a_section_name: { - auto_section: auto - sizes: 16 - } - } - - linker_sections: - [ - { - name: code - start: 0 - - // Alternatively the end tag can be used to provide the end. - size: 0x00000C800 - }, - { - name: data - start: 0x00000C800 - // The end of this section will be at the beginning of the next. - // In this example the next section is i_am_a_section_name - } - ] - } - - - - -Python Configuration -~~~~~~~~~~~~~~~~~~~~ - -The same can be done by using a python script - -.. literalinclude:: ../../../configs/example.py - :language: python - - -The script should include a config function that return an :py:class:`x_heep_gen.system.XHeep` instance. -The configuration is simmilar to the hjson one. The order in which sections are added is also the one used in hardware. -The script writer is responsible to call :py:meth:`x_heep_gen.system.XHeep.build` and :py:meth:`x_heep_gen.system.XHeep.validate` and to raise an error in case of failure. -The first does make the system ready to be used and the second does check for errors in the configuration. - - - -Select Configuration File -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To configure the system call - -.. code:: bash - - make mcu-gen X_HEEP_CFG=configs/name_of_file.hjson - - - -Other configurations -~~~~~~~~~~~~~~~~~~~~ - -The pads are configured in `pad_cfg.hjson`. - -One part of the configuration is in `mcu_cfg.hjson`. - -Additionally if a `hjson` file is ussed for configuration the following parameters can be set to the make command to override the configuration: - -- `BUS=NtoM,onetoM` -- `MEMORY_BANKS=integer` -- `MEMORY_BANKS_IL=integer` - -They will replace the configuration used in the configuration file. -When one parameter is not provided the configuration files value is used. -The memory banks configured this way will only be of size 32kiB. -For compatibility reasons `MEMORY_BANKS` does not create linker sections while `MEMORY_BANKS_IL` does create a linker section. - diff --git a/docs/source/Configuration/LinkerConfiguration.md b/docs/source/Configuration/LinkerConfiguration.md new file mode 100644 index 000000000..1540269bc --- /dev/null +++ b/docs/source/Configuration/LinkerConfiguration.md @@ -0,0 +1,58 @@ +# Linker Section Configuration + +The linker script sections can be configured in two ways. +Either a section can be matched with a group of ram banks +or it can be manually defined. + +To automatically add a section the entry `auto_section: auto` should be added to the banks. +It will add a section that matches the banks exactly, it can only be used in the non recursive part. +The name of the section is set with the name of the group of banks. + +When manually setting the the linker section the name and the start address have to be provided. +Additionally the end is either provided by it's address or by the size of the section. +If no end is provided the end is inferred by the start of the next linker section. +Or if no section follows, the end address of the last ram bank. + +Both configuration types can be freely combined as long as no section overlap. +All sections will e sorted by the configuration system. + +The first two sections should always be code and data. +The other name can be used in code with a `.xheep_` prefix, like in `example_matadd_interleaved` + +```{code} c +int32_t __attribute__((section(".xheep_data_interleaved"))) m_c[16*16]; +``` + +```{code} js +{ + ram_address: 0 + bus_type: "onetoM", + ram_banks: { + code_and_data: { + num: 2 + sizes: [32] + } + i_am_a_section_name: { + auto_section: auto + sizes: 16 + } + } + + linker_sections: + [ + { + name: code + start: 0 + + // Alternatively the end tag can be used to provide the end. + size: 0x00000C800 + }, + { + name: data + start: 0x00000C800 + // The end of this section will be at the beginning of the next. + // In this example the next section is i_am_a_section_name + } + ] +} +``` diff --git a/docs/source/Configuration/MemoryConfiguration.md b/docs/source/Configuration/MemoryConfiguration.md new file mode 100644 index 000000000..12cc59a49 --- /dev/null +++ b/docs/source/Configuration/MemoryConfiguration.md @@ -0,0 +1,41 @@ +# Memory Banks Configuration + +The system can be configured with banks of different sizes. The sizes should be a power of two in kiB. +All banks are configured in one continuous address region. + +To configure interleaved banks the number and the size of the banks have to be provided. +The following restrictions apply: All banks must have the same size and a power of two banks must be configured. + +For continuous banks, the default mode, only the `sizes` filed is required. +It can be either the size in kiB of a single bank, +a dictionary of the same format containing more banks, or a list of multiple entries. +If the `num` field is also provided the configuration in the `sizes` field is repeated `num` times. + +```{code} js +ram_banks: { + code: {sizes: 64} // configure just one bank + + data: { + type: continuous // the default, can be omitted + num: 2 + sizes: 32 + } + + alt_data: {sizes: [32, 32]} // the same as data but with a list + + more_complex: { + // This also works recursively so we can easily have different sizes of banks + // and in bigger numbers without listing them all one by one. + sizes: [ + { + num: 4 + sizes: 8 + }, + { + num: 16 + sizes: 4 + }, + ] + } +} +``` \ No newline at end of file diff --git a/docs/source/Configuration/PadConfiguration.md b/docs/source/Configuration/PadConfiguration.md index a330de70c..8a9408e63 100644 --- a/docs/source/Configuration/PadConfiguration.md +++ b/docs/source/Configuration/PadConfiguration.md @@ -145,7 +145,7 @@ The following section describes how the spacing between pads is performed. When 2. Leaving these attributes empty and allowing `mcu-gen` to calculate them automatically using the global `physical_attributes`. Please note that a combination of the two can be performed; If a given `skip` or `offset` parameter is defined for a pad, then the calculated values are overwritten. This gives the designer flexibility to modify the pad locations on only one side, for example. -![Physical attributes and layout attributes illustration](../images/pad_spacing.png) +![Physical attributes and layout attributes illustration](/images/pad_spacing.png) The automatic pad placement calculates the pad `offset` and `skip` parameters such that: 1. Bondpads are evenly spaced and centered on their respecitve side diff --git a/docs/source/Configuration/PeripheralConfiguration.md b/docs/source/Configuration/PeripheralConfiguration.md new file mode 100644 index 000000000..d3c2f8809 --- /dev/null +++ b/docs/source/Configuration/PeripheralConfiguration.md @@ -0,0 +1,3 @@ +# Peripheral Configuration + +The configuration of the peripherals is in `mcu_cfg.hjson`. diff --git a/docs/source/Configuration/SystemConfiguration.md b/docs/source/Configuration/SystemConfiguration.md new file mode 100644 index 000000000..0450701a2 --- /dev/null +++ b/docs/source/Configuration/SystemConfiguration.md @@ -0,0 +1,63 @@ +# System Configuration + +The X-HEEP system can be configured by three methods: +- Directly passing arguments to the make command. +- Using an hjson file. +- Using a Python script. + +## Make Command + +The easiest way of changing the default values is with some arguments in the make command. For example, you can change the CPU type (cv32e20), the default bus type (onetoM), the default continuous memory size (2 banks), or the default interleaved memory size (0 banks) with: + +```bash +make mcu-gen CPU=cv32e40p BUS=NtoM MEMORY_BANKS=12 MEMORY_BANKS_IL=4 +``` + +This generates X-HEEP with the cv32e40p core, a parallel bus, and 16 memory banks (12 continuous and 4 interleaved), 32KB each, for a total memory of 512KB. + +This method has certain limitations, such as the size of the memory banks, which are fixed at 32KB. You can find more details in the documented code of the Makefile. + +## Hjson Configuration File + +X-HEEP can be configured in more detail using an hjson file. The default configurations and examples are located in the `configs` directory. + +To run `mcu-gen` with a specific `hjson` configuration file, use the following command: + +```{code} bash +make mcu-gen X_HEEP_CFG=configs/name_of_file.hjson +``` + +The `general.hjson` file is shown below as an example: + +```{literalinclude} ../../../configs/general.hjson +``` + +If an `hjson` file is used for configuration, the following parameters can be set in the make command to override the configuration: + +- `BUS` +- `MEMORY_BANKS` +- `MEMORY_BANKS_IL` + +These will replace the configuration used in the hjson file. When one parameter is not provided the configuration files value is used. +The memory banks configured this way will only be 32KB. +For compatibility reasons `MEMORY_BANKS` does not create linker sections while `MEMORY_BANKS_IL` does create a linker section. + +## Python Configuration + +A more complex configuration can be done using a python script. The default configurations and examples are located in the `configs` directory. + +The script should include a config function that returns a {py:class}`x_heep_gen.system.XHeep` instance. +The configuration is similar to the hjson one. The order in which sections are added is also the one used in hardware. +The script writer is responsible to call {py:meth}`x_heep_gen.system.XHeep.build` to make the system ready to be used, {py:meth}`x_heep_gen.system.XHeep.validate` to check for errors in the configuration, and to raise an error in case of failure. + +To run `mcu-gen` with a specific python configuration script, use the following command: + +```{code} bash +make mcu-gen X_HEEP_CFG=configs/name_of_file.py +``` + +The `example.py` file is shown below as an example: + +```{literalinclude} ../../../configs/example.py +:language: python +``` diff --git a/docs/source/Configuration/index.md b/docs/source/Configuration/index.md new file mode 100644 index 000000000..4f5f670d9 --- /dev/null +++ b/docs/source/Configuration/index.md @@ -0,0 +1,28 @@ +# Configuration + +Here you can find the documentation for how to configure X-HEEP. X-HEEP uses a series of Python scripts to generate the desired configuration of the MCU and its related files using [Mako](https://www.makotemplates.org/) `.tpl` templates. For example, `hw/core-v-mini-mcu/core_v_mini_mcu.sv.tpl` will generate `hw/core-v-mini-mcu/core_v_mini_mcu.sv`. + +The configuration is triggered by the `mcu-gen` make target, and it has to be run every time the configuration or any of the `.tpl` files change. If you have to modify any file that is generated from a `.tpl` file, you should modify the `.tpl` file and run `mcu-gen` to generate the new file. + +The default configuration of X-HEEP is generated by running: + +```bash +make mcu-gen +``` + +If you want to modify the default parameters, check the [system configuration guide](./SystemConfiguration). + +In this section you will also find the detailed documentation for configuring the different elements of X-HEEP (e.g. the bus, the memory, the pads...), and the API documentation of the `x_heep_gen` Python project that models and is in charge of generating X-HEEP according to the specified configuration. + +```{toctree} +:maxdepth: 3 + +SystemConfiguration + +MemoryConfiguration +BusConfiguration +LinkerConfiguration +PadConfiguration +PeripheralConfiguration + +x_heep_gen/index diff --git a/docs/source/Extending/eXamples.md b/docs/source/Extending/eXamples.md new file mode 100644 index 000000000..02d1e6f3b --- /dev/null +++ b/docs/source/Extending/eXamples.md @@ -0,0 +1,13 @@ +# X-HEEP-based eXamples + +Here you can find a list of `X-HEEP` based open-source examples. If you want to include your project in this list, please open an issue with a link to your repository. + +* [CGRA-X-HEEP](https://github.com/esl-epfl/cgra_x_heep): A CGRA loosely coupled with X-HEEP. +* [F-HEEP](https://github.com/davidmallasen/F-HEEP): System integrating [fpu_ss](https://github.com/pulp-platform/fpu_ss) into X-HEEP via the eXtension interface and cv32e40px. +* [KALIPSO](https://github.com/vlsi-lab/ntt_intt_kyber) and [KRONOS](https://github.com/vlsi-lab/keccak_integration/tree/keccak_xheep): Loosely-coupled, post-quantum cryptography accelerators for NTT/INTT and Keccak hash function integrated into X-HEEP. + +## Inter-process communication using Verilator's DPI + +The following [repository](https://github.com/specs-feup/x-heep) uses X-HEEP and the Verilator simulator to model a CPU-CGRA hybrid system. This architecture simulates the CPU integrated into the X-HEEP system, and an external Java process simulates the accelerator. Both components require a communication channel to exchange instructions and data. Using the existing infrastructure to to interact with an external OS process is not feasible at first sight, given that the X-HEEP ecosystem's pipeline encapsulates most of the simulation build and execution, with all modules supplied directly to Verilator. + +To circumvent this issue, this project uses [Direct Programming Interface (DPI)](https://verilator.org/guide/latest/connecting.html) calls (defined in `hw/ip_examples/cgraitf/cgraitfdpi.c`) to establish a connection and communicate with an external process through a Unix Domain Socket. This behavior mirrors the UART module (used as the skeleton code) that connects and outputs _printf_ information to the pseudo-terminal. These calls are embedded in a mock CGRA peripheral/interface, located in `hw/ip_examples/cgraitf/cgraitf.sv`. The module overrides reads and writes to the specified peripheral address, with the proper socket-based mechanism (_send_ or _recv_). The _simple_accelerator_ module could also be similarly customized to perform the same operations, using X-HEEP's interfaces and memory access protocols. A given user program executed in the CPU (such as `sw/applications/cgra_itf/main.c`) must then select assignments to or from the address to trigger the appropriate action. \ No newline at end of file diff --git a/docs/source/Extending/eXtendingHW.md b/docs/source/Extending/eXtendingHW.md new file mode 100644 index 000000000..8ada44673 --- /dev/null +++ b/docs/source/Extending/eXtendingHW.md @@ -0,0 +1,200 @@ +# eXtending hardware + +To extend X-HEEP with your own custom IPs, you first have to create a top-level repository that will contain both X-HEEP and your IP. + +## Repository structure + +The following is an example repository folder structure. + + BASE + ├── hw + │ ├── TOP + │ │ └── top.sv + │ └── vendor + │ ├── your_copro + │ ├── your_copro.vendor.hjson + │ ├── esl_epfl_x_heep + │ └── esl_epfl_x_heep.vendor.hjson + ├── top.core + ├── scripts + │ └── sim + │ ├── compile_remote_bitbang.sh + │ └── compile_uart_dpi.sh + ├── tb + │ └── testharness.sv + ├── util + │ └── vendor.py + ├── Makefile + └── sw + +## Adding a CV-X-IF coprocessor + +We recomend using the [vendor](https://opentitan.org/book/util/doc/vendor.html) tool as used inside X-HEEP, although you could modify it to use git submodules. + +- Create a new top-level repository (`BASE`) and vendorize both your `CV-X-IF` compliant coprocessor and X-HEEP. For X-HEEP, create inside your top-level repository's base directory (`BASE`) a `hw/vendor` directory containing a file named `esl_epfl_x_heep.vendor.hjson`: + +
+ Example of esl_epfl_x_heep.vendor.hjson + +``` +// Copyright EPFL +// Licensed under the Solderpad Hardware License v2.1, see LICENSE.txt for details +// SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 + +{ + name: "esl_epfl_x_heep", + target_dir: "esl_epfl_x_heep", + + upstream: { + url: "https://github.com/esl-epfl/x-heep.git", + rev: "main", + }, + + patch_dir: "patches/esl_epfl_x_heep", + + exclude_from_upstream: [ + ".github", + "ci", + ] +} + +``` +

+ +The `main` branch can be replaced with an specific commit. This is the recommended operation to prevent accidental updates to an incompatible version. + +In a directory `BASE/util` add the [vendor python script](https://github.com/lowRISC/opentitan/blob/master/util/vendor.py). + +To vendorize or revendorize the X-HEEP repository inside a `BASE/hw/vendor/esl_epfl_x_heep/` folder run the following command from your `BASE`. +``` +util/vendor.py --update hw/vendor/esl_epfl_x_heep.vendor.hjson +``` + +- Copy the `x-heep/hw/system/x_heep_system.sv` as your new top-level module. Then modify it as needed to include your coprocessor and connect it to the `core_v_mini_mcu` with the `XIF`. The `XIF` SystemVerilog interface must be instantiated in the top-level module, where X-HEEP and your co-processor are connected. See X-HEEP's testbench (`tb/testharness.sv`) as an example. +- Before building software remember to run `make mcu-gen CPU=cv32e40px`. + +## Adding an accelerator on the bus + +Documentation TBD. The start should be similar to a CV-X-IF coprocessor. You can look at the available [eXamples](./eXamples.md). + +## Creating a simulation or synthesis flow + +To add this new top-level module to the simulation/synthesis flow you can extend the [FuseSoC](https://fusesoc.readthedocs.io/en/stable/user/index.html) support of X-HEEP. + +- Create a new `tb/testharness.sv` modifying the one in `x-heep/tb/testharness.sv` by adding your new top-level module. +- Create a new `scripts/sim` directory adapting the corresponding ones in `x-heep/scripts/sim`. +- Create a new `.core` FuseSoC file following this example for Modelsim simulation and adapting it to your particular needs: + +
+ Example of .core + +``` + CAPI=2: + + # Solderpad Hardware License, Version 2.1, see LICENSE for details. + # SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 + + name: "[YOUR_FUSESOC_IP_NAME]" + description: "[YOUR_IP_DESCRIPTION]" + + filesets: + files_rtl_generic: + depend: + - openhwgroup.org:systems:core-v-mini-mcu + - x-heep:ip:pad_control + - [YOUR_COPROCESSOR] + files: + - hw/[YOUR_TOPLEVEL_SV] + - hw/vendor/esl-epfl_x-heep/hw/system/pad_ring.sv + file_type: systemVerilogSource + + tb: + depend: + - x-heep::tb-utils + files: + - tb/testharness.sv # Your modified testharness + - hw/vendor/esl-epfl_x-heep/tb/tb_top.sv + file_type: systemVerilogSource + + # Scripts for hooks + pre_build_uartdpi: + files: + - scripts/sim/compile_uart_dpi.sh # Your modified scripts + file_type: user + + pre_build_remote_bitbang: + files: + - scripts/sim/compile_remote_bitbang.sh # Your modified scripts + file_type: user + + pre_patch_modelsim_Makefile: + files: + - hw/vendor/esl-epfl_x-heep/scripts/sim/modelsim/patch_modelsim_Makefile.py + file_type: user + + parameters: + COREV_PULP: + datatype: int + paramtype: vlogparam + default: 0 + JTAG_DPI: + datatype: int + paramtype: vlogparam + default: 0 + USE_UPF: + datatype: bool + paramtype: vlogdefine + description: | + Enables simulation with UPF with Modelsim/VCS + + scripts: + pre_build_remote_bitbang: + cmd: + - sh + - ../../../scripts/sim/compile_remote_bitbang.sh + pre_build_uartdpi: + cmd: + - sh + - ../../../scripts/sim/compile_uart_dpi.sh + pre_patch_modelsim_Makefile: + cmd: + - python + - ../../../hw/vendor/esl-epfl_x-heep/scripts/sim/modelsim/patch_modelsim_Makefile.py + + targets: + default: &default_target + filesets: + - files_rtl_generic + + sim: + <<: *default_target + default_tool: modelsim + filesets_append: + - tb + - tool_modelsim? (pre_build_remote_bitbang) + - tool_modelsim? (pre_build_uartdpi) + - tool_modelsim? (pre_patch_modelsim_Makefile) + toplevel: + - tb_top + hooks: + pre_build: + - tool_modelsim? (pre_build_uartdpi) + - tool_modelsim? (pre_build_remote_bitbang) + - tool_modelsim? (pre_patch_modelsim_Makefile) # this is required by Questa 2020 on + parameters: + - COREV_PULP + - JTAG_DPI + tools: + modelsim: + vlog_options: + - -override_timescale 1ns/1ps + - -suppress vlog-2583 + - -suppress vlog-2577 + - -pedanticerrors + - -define MODELSIM + vsim_options: + - -sv_lib ../../../hw/vendor/esl-epfl_x-heep/hw/vendor/lowrisc_opentitan/hw/dv/dpi/uartdpi/uartdpi + - -sv_lib ../../../hw/vendor/esl-epfl_x-heep/hw/vendor/pulp_platform_pulpissimo/rtl/tb/remote_bitbang/librbs +``` + +

diff --git a/docs/source/Extending/eXtendingSW.md b/docs/source/Extending/eXtendingSW.md new file mode 100644 index 000000000..ec3502ac7 --- /dev/null +++ b/docs/source/Extending/eXtendingSW.md @@ -0,0 +1,179 @@ +# eXtending software + +If X-HEEP is vendorized into your project, you can still have software source files in any directory of your top-level repository and build them using X-HEEP's compilation flow. + +## Repository structure + +The following is an example repository folder structure focusing on extending the software flow. + + BASE + ├── sw + │ ├── applications + │ │ └── your_app + │ │ ├── main.c + │ │ ├── your_app.c + │ │ ├── your_app.h + │ │ └── ... + │ ├── build -> ../hw/vendor/esl_epfl_x_heep/sw/build + │ ├── device -> ../hw/vendor/esl_epfl_x_heep/sw/device + │ ├── linker -> ../hw/vendor/esl_epfl_x_heep/sw/linker + │ └── external + │ ├── drivers + │ │ └── your_copro + │ │ ├── your_copro.c + │ │ ├── your_copro.h + │ │ └── your_copro_defs.h -> ../../../../hw/vendor/your_copro/sw/your_copro_defs.h + │ └── extensions + │ │ └── your_copro_x_heep.h + │ └── lib + │ └── crt + │ └── external_crt0.S + ├── hw + │ └── vendor + │ ├── your_copro + │ ├── esl_epfl_x_heep.vendor.hjson + │ └── esl_epfl_x_heep + │ ├── hw + │ ├── sw + │ │ ├── applications + │ │ ├── build + │ │ ├── device + │ │ └── ... + │ ├── Makefile + │ ├── external.mk + │ └── ... + ├── Makefile + ├── util + │ └── vendor.py + └── ... + +Where `BASE` is your repository's base directory, `esl_epfl_x_heep` is the vendorized X-HEEP repository and `your_app` is the name of the application you intend to build. + +## The /sw/ folder + +The `BASE/sw/` folder must comply with X-HEEP's repository structure and therefore include an `applications`, `build`, `device` and `linker` folder. +It is not compulsory for it to be on the `BASE` directory, although this is the default structure that X-HEEP's Makefiles will assume if no other path is specified through the `SOURCE` variable. If you plan to store source files in a different location that the one proposed, just call `make` making the `SOURCE` path explicit. +``` +make app PROJECT=your_app SOURCE= +``` +Consider that, inside this `sw` folder, the same structure than the one proposed is required. + +Inside the `applications` folder different projects can be stored (still respecting the `name_of_project/main.c` structure of X-HEEP). +The `build`, `device` and `linker` should be linked with the vendorized folders inside X-HEEP. +In this example that is done from the `BASE` directory as follows: +``` +ln -s ../hw/vendor/esl_epfl_x_heep/sw/build sw/build +ln -s ../hw/vendor/esl_epfl_x_heep/sw/device sw/device +ln -s ../hw/vendor/esl_epfl_x_heep/sw/linker sw/linker +``` + +## The /sw/applications folder + +Inside the `sw/applications/` folder you may have different applications that can be built separately. Each application is a directory named after your application, containing one and only one `main.c` file which is built during the compilation process. The folder can contain other source or header files (of any name but `main.c`). + +## The /sw/external folder + +In the (optional) `external` folder you can add whatever is necessary for software to work with your coprocessor/accelerator. This might include: + +* Sources and header files. +* Soft links to folders or files. +* A `lib/crt/` directory with an `exteral_crt0.S` file (will be included inside `BASE/sw/device/lib/crt/crt0.S`). + +The external folder or any of its subdirectories cannot contain neither a `device` nor an `applications` folder as it would collide with the respective folders inside `BASE/sw/`. It should also not contain a `main.c` file. + +## The BASE/Makefile + +The `BASE/Makefile` is your own custom Makefile. You can use it as a bridge to access the Makefile from X-HEEP. To do so, it MUST include the `external.mk` AFTER all your custom rules. + + +
+ Example of BASE/Makefile + +```Makefile +MAKE = make +.PHONY: custom +custom: + @echo Nothing is executed from X-HEEP, as custom is not a target inside X-HEEP. + +app: + @echo This target will do something and then call the one inside X-HEEP. + $(MAKE) -f $(XHEEP_MAKE) $(MAKECMDGOALS) PROJECT=hello_world SOURCE=. + +verilator-sim: + @echo You will not access the verilator-sim target from X-HEEP. + +export HEEP_DIR = hw/vendor/esl_epfl_x_heep/ +XHEEP_MAKE = $(HEEP_DIR)/external.mk +include $(XHEEP_MAKE) +``` + +- The `custom` rule will not use the X-HEEP Makefile in any way. Make the target a prerequisite of `.PHONY` to prevent X-HEEP's Makefile from attempting to run a non-existent target. +- The `app` rule will perform actions before calling X-HEEP Makefile's `app` rule. In this case, the project and where the source files are to be extracted from is being specified. The `SOURCE=.` argument will set X-HEEP's own `sw/` folder as the directory from which to fetch source files. This is an example of building inner sources from an external directory. +- The `verilator-sim` rule will override the X-HEEP Makefile's one. +- Any other target will be passed straight to X-HEEP's Makefile. For example +```sh +make mcu-gen CPU=cv32e40px +``` + +If you plan to vendorize X-HEEP in a different directory than the one proposed, just update: +``` +export HEEP_DIR = +``` +

+ +## Excluding files from compilation + +If you have files that need to be excluded from the gcc compilation flow, you can add them to a directory containing the keyword `exclude`, and/or rename the file to include the keyword `exclude`. +In the following example, the files marked with ✅ will be compiled, and the ones marked with ❌ will not. + + BASE + ├── sw + │ ├── applications + │ │ └── your_app + │ │ ├── ✅ main.c + │ │ ├── ✅ your_app.c + │ │ ├── your_app.h + │ │ ├── ❌ my_kernel_exclude.c + │ │ ├── my_kernel.h + │ │ └── exclude_files + │ │ └── ❌ kernel_asm.S + +## Makefile help + +If you want that the commands `make` or `make help` show the help for your external Makefile, add the following lines before the first `include` directive or target. + +
+ Addition to print the target's help + +```Makefile +# HEEP_DIR might already be defined, you may want to move it to the top +export HEEP_DIR = hw/vendor/esl_epfl_x_heep/ + +# Get the path of this Makefile to pass to the Makefile help generator +MKFILE_PATH = $(shell dirname "$(realpath $(firstword $(MAKEFILE_LIST)))") +export FILE_FOR_HELP = $(MKFILE_PATH)/Makefile + + +## Call the help generator. Calling simply +## $ make +## or +## $ make help +## Will print the help of this project. +## With the parameter WHICH you can select to print +## either the help of X-HEEP (WHICH=xheep) +## or both this project's and X-HEEP's (WHICH=all) +help: +ifndef WHICH + ${HEEP_DIR}/util/MakefileHelp +else ifeq ($(filter $(WHICH),xheep x-heep),) + ${HEEP_DIR}/util/MakefileHelp + $(MAKE) -C $(HEEP_DIR) help +else + $(MAKE) -C $(HEEP_DIR) help +endif +``` + +

+ +> Remeber to add double hashes `##` on any comment you want printed on the help. +> Use `## @section SectionName` to divide the documentation in sections diff --git a/docs/source/Extending/index.md b/docs/source/Extending/index.md new file mode 100644 index 000000000..57ca9bbff --- /dev/null +++ b/docs/source/Extending/index.md @@ -0,0 +1,31 @@ +# eXtending X-HEEP + +X-HEEP is meant to be extended with your own custom IPs. X-HEEP itself posseses a hardware-software framework capable of working standalone. If you want to extend it, you will need to merge your hardware and software with X-HEEP's. + +For this purpose we support the [CV-X-IF](https://docs.openhwgroup.org/projects/openhw-group-core-v-xif/en/latest/intro.html) interface with the [cv32e40px](https://github.com/esl-epfl/cv32e40px) or [cv32e40x](https://github.com/openhwgroup/cv32e40x) RISC-V CPUs, and we expose master and slave ports to/from the bus. + +> We recommend using the cv32e40px for pairing with your CV-X-IF compliant coprocessor. If you choose to use the cv32e40x, X-HEEP currently uses the revision [`0.9.0`](https://github.com/openhwgroup/cv32e40x/commit/f17028f2369373d9443e4636f2826218e8d54e0f). It is recommended to use the same revision in peripheral IPs to prevent conflicts during RTL compilation. + +In addition, the X-HEEP testbench has been extended with a DMA, dummy peripherals (including the flash), and a CV-X-IF compatible coprocessor implementing the F RISC-V extension. This has been done to help us maintaining and verifying the extension interface. + +If you want to try the FPU-like coprocessor with a CV-X-IF compatible CPU as the cv32e40px, you can do it in the base X-HEEP as follows: + +``` +make mcu-gen CPU=cv32e40px +make verilator-sim FUSESOC_PARAM="--X_EXT=1" +make app PROJECT=example_matfadd ARCH=rv32imfc +cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator +./Vtestharness +firmware=../../../sw/build/main.hex +``` + +The program should terminate with value 0. + +To learn how to extend X-HEEP you can read the guides in this section. + +```{toctree} +:maxdepth: 3 +:numbered: 1 + +eXtendingHW +eXtendingSW +eXamples diff --git a/docs/source/GettingStarted/CompilingRunningSW.md b/docs/source/GettingStarted/CompilingRunningSW.md new file mode 100644 index 000000000..6c5865afa --- /dev/null +++ b/docs/source/GettingStarted/CompilingRunningSW.md @@ -0,0 +1,29 @@ +# Compiling and running software + +Here we will show how to compile and simulate with verilator a `hello_world` application. + +## Compiling applications + +To compile the `hello_world` application, you simply have to run: + +``` +make app +``` + +```{warning} +Don't forget to set the `RISCV` env variable to the compiler folder (without the `/bin` included). +``` + +You can find all the documentation and parameters for compiling applications in the [compiling applications guide](/How_to/CompileApps.md). + +## Running applications + +Once you know how to generate the MCU and compile the `hello_world` application, you can run it on X-HEEP using the open-source Verilator simulator. This can be easily done with: + +``` +make run-helloworld +``` + +After a couple of minutes, you should se a "hello world!" output. + +All of the detailed documentation for simulating applications with the different tools can be found in the [simulating guide](/How_to/Simulate.md). Furthermore, you are now ready to [run applications on FPGA](/How_to/RunOnFPGA.md) and to follow the rest of the "How to..." guides. diff --git a/docs/source/GettingStarted/GeneratingMCU.md b/docs/source/GettingStarted/GeneratingMCU.md new file mode 100644 index 000000000..6381972f2 --- /dev/null +++ b/docs/source/GettingStarted/GeneratingMCU.md @@ -0,0 +1,19 @@ +# Generating the microcontroller + +X-HEEP uses a series of Python scripts to generate the desired configuration of the MCU and its related files using [Mako](https://www.makotemplates.org/) `.tpl` templates. For example, `hw/core-v-mini-mcu/core_v_mini_mcu.sv.tpl` will generate `hw/core-v-mini-mcu/core_v_mini_mcu.sv`. + +For the default configuration of X-HEEP, you simply have to run: + +```bash +make mcu-gen +``` + +The easiest way of changing the default values is with some arguments. For example, you can change the CPU type (cv32e20), the default bus type (onetoM), the default continuous memory size (2 banks), or the default interleaved memory size (0 banks) with: + +```bash +make mcu-gen CPU=cv32e40p BUS=NtoM MEMORY_BANKS=12 MEMORY_BANKS_IL=4 +``` + +This generates X-HEEP with the cv32e40p core, a parallel bus, and 16 memory banks (12 continuous and 4 interleaved), 32KB each, for a total memory of 512KB. + +This method has certain limitations, such as the size of the memory banks, which are fixed at 32KB. You can find the full documentation on how to configure X-HEEP in the [Configuration](/Configuration/index) section. This includes using `hjson` files or Python scripts for a more detailed and powerful configuration. diff --git a/docs/source/How_to/GettingStarted.md b/docs/source/GettingStarted/Setup.md similarity index 86% rename from docs/source/How_to/GettingStarted.md rename to docs/source/GettingStarted/Setup.md index d015701dd..8984cf32d 100644 --- a/docs/source/How_to/GettingStarted.md +++ b/docs/source/GettingStarted/Setup.md @@ -1,4 +1,6 @@ -# Get started +# Setup + +There are two ways of setting up X-HEEP. You can either use the provided docker image or install and configure the environment manually. ## Docker setup @@ -16,15 +18,17 @@ Assuming that X-HEEP has been cloned to `X-HEEP-DIR=\absolute\path\to\x-HEEP\fol docker run -it -v ${X-HEEP-DIR}:/workspace/x-heep ghcr.io/esl-epfl/x-heep-toolchain ``` -:warning: Take care to indicate the absolute path to the local clone of X-HEEP, otherwise docker will not be able to properly mount the local folder in the container. +```{warning} +Take care to indicate the absolute path to the local clone of X-HEEP, otherwise docker will not be able to properly mount the local folder in the container. +``` -All the command listed in the README can be execute in the docker container, except for: +The docker setup has certain limitations. For example, the following are not supported: -- Simulation with Questasim and VCS, synthesis with Design Compiler (licenses are required to use these tools, so they are not installed in the container) +- 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 +- OpenRoad flow is not installed in the container, so it is not possible to run the related make commands. -- Synthesis with Vivado could be possible, but currently is untested +- Synthesis with Vivado could be possible, but currently is untested. ## Manual setup @@ -40,7 +44,6 @@ In general, have a look at the [Install required software](https://opentitan.org ### 2. Python - We rely on either (a) `miniconda`, or (b) `virtual environment` enviroment. Choose between `2.a` or `2.b` to setup your enviroment. @@ -60,7 +63,6 @@ You need to do it only the first time, then just activate the environment everyt conda activate core-v-mini-mcu ``` - #### 2.b Virtual Environment Install the python virtual environment just as: @@ -130,9 +132,9 @@ sudo apt install libcanberra-gtk-module libcanberra-gtk3-module sudo apt-get install -y gtkwave ``` -### Files are formatted with Verible +### 5. Install Verible -We use version v0.0-1824-ga3b5bedf +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) @@ -141,9 +143,3 @@ To format your RTL code type: ``` make verible ``` -### 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. - diff --git a/docs/source/GettingStarted/index.rst b/docs/source/GettingStarted/index.rst new file mode 100644 index 000000000..cd8df82fd --- /dev/null +++ b/docs/source/GettingStarted/index.rst @@ -0,0 +1,12 @@ +Getting started +=============== + +This section will guide you in the process of setting up X-HEEP and running your first application. + +.. toctree:: + :maxdepth: 2 + :numbered: 1 + + Setup + GeneratingMCU + CompilingRunningSW diff --git a/docs/source/How_to/AnalogMixedSignal.md b/docs/source/How_to/AnalogMixedSignal.md index 5e2d0bb4e..18607ec2c 100644 --- a/docs/source/How_to/AnalogMixedSignal.md +++ b/docs/source/How_to/AnalogMixedSignal.md @@ -68,7 +68,7 @@ The example AMS peripheral used by simulations of X-HEEP is located in `hw/ip_ex ### The repository's example SPICE files -

+![Example ADC](/images/example_adc.svg) An example `adc.sp` file can be found in `hw/ip_examples/ams/analog`. This is a 1-bit ADC with a threshold that is configured through the 2-bit wide SEL input: an input of 00, 01, 10 and 11 will provide a threshold of 20%, 40%, 60% and 80% of VDD (1.2V) respectively. The input signal of the ADC is a sine wave with a peak-to-peak amplitude of 1.2V directly placed inside the SPICE netlist. diff --git a/docs/source/How_to/CompileApps.md b/docs/source/How_to/CompileApps.md new file mode 100644 index 000000000..e9dd0eb80 --- /dev/null +++ b/docs/source/How_to/CompileApps.md @@ -0,0 +1,59 @@ +# Compile applications + +All software applications can be found in `sw/applications`. These can be compiled with the `app` target of the top-level makefile of X-HEEP. To compile the `hello world` application with default parameters, just type: + +``` +make app +``` + +This will create the executable file to be loaded in your target system (ASIC, FPGA, Simulation). +X-HEEP is using CMake to compile and link. Thus, the generated files after having compiled and linked are under `sw\build`. + +```{warning} +Don't forget to set the `RISCV` env variable to the compiler folder (without the `/bin` included). +``` + +You can select the application to run, the target, compiler, etc. by modifying the 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: ) + - 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),) +``` + +```{note} +You can run `make help` or `make` to see the most up-to-date documentation for the makefile. This includes the parameters available for this command, as well as the documentation for all other commands. Also check the different `clean` commands in the makefile to verify that you are using the correct one. +``` + +For instance, to compile the `hello world` app with clang for the pynq-z2 FPGA, just run: + +``` +make app PROJECT=hello_world TARGET=pynq-z2 COMPILER=clang +``` + +## Using the OpenHW Group compiler + +If you want to 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 +``` + +## Compiling FreeRTOS based applications + +X-HEEP supports FreeRTOS based applications. Please see `sw\applications\example_freertos_blinky`. + +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=example_freertos_blinky +``` + +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 fetched 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. diff --git a/docs/source/How_to/CompileMakefile.md b/docs/source/How_to/CompileMakefile.md deleted file mode 100644 index 9e4ea873d..000000000 --- a/docs/source/How_to/CompileMakefile.md +++ /dev/null @@ -1,145 +0,0 @@ -# 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. - -## 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 -``` - -To change the default cpu type (i.e., cv32e20), the default bus type (i.e., onetoM), -the default continuous memory size (i.e., 2 continuous banks) or the default interleaved memory size (i.e., 0 interleaved banks): - -``` -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. -This method is limmited to 32KB banks. - -To configure the ram banks with more flexibility, edit `configs/general.hjson` or provided your own one. -Both method work together the first one overrides the second. - -``` -make mcu-gen X_HEEP_CFG=configs/my_config.hjson -``` - -For more information see Configuration section. - -## 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),pynq-z2 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),pynq-z2) -- 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 in 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` - -## FreeRTOS based applications - -'X-HEEP' supports 'FreeRTOS' based applications. Please see `sw\applications\example_freertos_blinky`. - -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=example_freertos_blinky -``` - -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. - - -## 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. \ No newline at end of file diff --git a/docs/source/How_to/IDEs.md b/docs/source/How_to/IDEs.md index ee932dc39..4803a1a4e 100644 --- a/docs/source/How_to/IDEs.md +++ b/docs/source/How_to/IDEs.md @@ -2,8 +2,8 @@ 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. +## 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 @@ -28,7 +28,7 @@ Once the paths are set properly, you can open `xheep.emProject` with SES. That w The output should be like this: -

+![SES Build](/images/ses_build.png) 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`. @@ -38,7 +38,7 @@ Finally, after building (compile and linking), you can directly start debugging The output should be something like this: -

+![SES Debug](/images/ses_debug.png) 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. diff --git a/docs/source/How_to/Simulate.md b/docs/source/How_to/Simulate.md index dba83e7a8..f2e67dc69 100644 --- a/docs/source/How_to/Simulate.md +++ b/docs/source/How_to/Simulate.md @@ -1,38 +1,48 @@ # Simulate This project supports simulation with Verilator, Synopsys VCS, Siemens Questasim and Cadence Xcelium. -It relies on `fusesoc` to handle multiple EDA tools and parameters. +We use [FuseSoC](https://github.com/olofk/fusesoc) for all the EDA tools we use. The `fusesoc` commands are used in the targets in the Makefile. 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 +## Simulating with Verilator -To simulate your application with Verilator, first compile the HDL: +To simulate your application with Verilator, first build the Verilator model: ``` make verilator-sim ``` -then, go to your target system built folder +then, go to your target system build folder ``` cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator ``` -and type to run your compiled software: +and type to run your compiled application: ``` ./Vtestharness +firmware=../../../sw/build/main.hex ``` -or to execute all these three steps type: +Finally, you can check the output by running: ``` -make run-helloworld +cat uart0.log +``` + +You can directly compile the app and run all of the previous steps with: + +``` +make run-app-verilator +``` + +```{warning} +The `run-app-verilator` target calls the `app` target, so the application will be recompiled with default parameters unless you add specific ones. ``` -## Compiling for VCS +## Simulating with VCS To simulate your application with VCS, first compile the HDL: @@ -74,7 +84,7 @@ and running the same executable as for the digital simulation. Note that with Ve 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 +## Simulating with Questasim To simulate your application with Questasim, first set the env variable `MODEL_TECH` to your Questasim bin folder, then compile the HDL: @@ -125,7 +135,7 @@ 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 +## Simulating with Xcelium To simulate your application with Xcelium, first compile the HDL: @@ -166,7 +176,7 @@ You may pass additional simulation parameters to the generated simulation execut If you're launching the Verilator simulation via `make`, you may pass this parameter via the `MAX_SIM_TIME=` command line argument, e.g. `make run-helloworld MAX_SIM_TIME=750us`. -## UART DPI +## Simulating the 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). diff --git a/docs/source/How_to/UpdateDocumentation.md b/docs/source/How_to/UpdateDocumentation.md index f0125b141..b8fc0f9b4 100644 --- a/docs/source/How_to/UpdateDocumentation.md +++ b/docs/source/How_to/UpdateDocumentation.md @@ -6,14 +6,14 @@ All documentation is found in the `/docs` directory. Thank you for helping keep > 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). +2. If a new folder is added, add it to the `toctree` inside the corresponding index file. 3. Commit and push. 4. Open a pull request and you can preview the updates to the docs in the CI build. 5. Once the pull request is merged, the documentation will be updated automatically. ## Build locally the web documentation -If you want to build the web documentation locally to test or debug the build: +If you want to build the web documentation locally to see your updates to the docs or to debug the build: 1. Open a terminal in the `docs` folder and make sure the conda environment is activated. 2. The first time you do this, run: @@ -24,3 +24,4 @@ pip install -r requirements.txt ```bash make clean html ``` +4. Open `docs/build/html/index.html` using a web browser. diff --git a/docs/source/How_to/eXtendingHEEP.md b/docs/source/How_to/eXtendingHEEP.md deleted file mode 100644 index 41e9bed70..000000000 --- a/docs/source/How_to/eXtendingHEEP.md +++ /dev/null @@ -1,410 +0,0 @@ -# eXtend X-HEEP - -`X-HEEP` is meant to be extended with your own custom IPs. `X-HEEP` itself posseses a hardware-software framework capable of working standalone. If you want to extend it, you will need to merge your hardware and software with `X-HEEP`'s. - -For this purpose we support the [CV-X-IF](https://docs.openhwgroup.org/projects/openhw-group-core-v-xif/en/latest/intro.html) interface with the [cv32e40x](https://github.com/openhwgroup/cv32e40x) or [cv32e40px](https://github.com/esl-epfl/cv32e40px) RISCV-CPU, and we expose master and slave ports to/from the bus. - -> We recommend using the `cv32e40px` for pairing with your CV-X-IF compliant coprocessor. If you choose to use the `cv32e40x`, `X-HEEP` currently uses the revision [`0.9.0`](https://github.com/openhwgroup/cv32e40x/commit/f17028f2369373d9443e4636f2826218e8d54e0f). It is recommended to use the same revision in peripheral IPs to prevent conflicts during RTL compilation. - -Here you can find a list of `X-HEEP` based open-source examples. If you want to include your project in this list, please open an issue with a link to your repository. - -* [CGRA-X-HEEP](https://github.com/esl-epfl/cgra_x_heep): A CGRA loosely coupled with X-HEEP. -* [F-HEEP](https://github.com/davidmallasen/F-HEEP): System integrating [fpu_ss](https://github.com/pulp-platform/fpu_ss) into X-HEEP via the eXtension interface and cv32e40px. -* [KALIPSO](https://github.com/vlsi-lab/ntt_intt_kyber) and [KRONOS](https://github.com/vlsi-lab/keccak_integration/tree/keccak_xheep): Loosely-coupled, post-quantum cryptography accelerators for NTT/INTT and Keccak hash function integrated into X-HEEP. - - -In addition, the `X-HEEP` testbench has been extended with a `DMA`, dummy `PERIPHERALs` (including the `FLASH`), and a CORE-V-XIF compatible co-processor -implementing the `RV32F` RISC-V ISA. This has been done to help us maintaining and verifying the extension interface. - -If you want to try the co-processor with a CORE-V-XIF compatible CPU as the `cv32e40px`, do as follow: - -``` -make mcu-gen CPU=cv32e40px -make verilator-sim FUSESOC_PARAM="--X_EXT=1" -make app PROJECT=example_matfadd ARCH=rv32imfc -./Vtestharness +firmware=../../../sw/build/main.hex -``` - -## Vendorizing X-HEEP - -In order to vendorize `X-HEEP` create inside your repository's base directory (`BASE`) a `hw/vendor` directory containing a file named `esl_epfl_x_heep.vendor.hjson`: - -
- Example of esl_epfl_x_heep.vendor.hjson - -``` -// Copyright EPFL -// Licensed under the Solderpad Hardware License v2.1, see LICENSE.txt for details -// SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 - -{ - name: "esl_epfl_x_heep", - target_dir: "esl_epfl_x_heep", - - upstream: { - url: "https://github.com/esl-epfl/x-heep.git", - rev: "main", - }, - - patch_dir: "patches/esl_epfl_x_heep", - - exclude_from_upstream: [ - ".github", - "ci", - ] -} - -``` -
- -The branch `main` can be replaced with an specific commit. This is the recommended operation to prevent accidental updates to an incompatible version. - -In a directory `BASE/util` add the [vendor python script](https://github.com/lowRISC/opentitan/blob/master/util/vendor.py). - -To vendorize or revendorize the X-HEEP repository inside a `BASE/hw/vendor/esl_epfl_x_heep/` folder run the following command from your `BASE`. -``` -util/vendor.py --update hw/vendor/esl_epfl_x_heep.vendor.hjson -``` - - -## Extending Hardware -To get started you will need to integrate both your coprocessor or accelerator and `X-HEEP` into a new system. - -### Proposed repository folder structure -The following is an example repository folder structure. - - BASE - ├── hw - │ ├── TOP - │ │ └── top.sv - │ └── vendor - │ ├── your_copro - │ ├── your_copro.vendor.hjson - │ ├── esl_epfl_x_heep - │ └── esl_epfl_x_heep.vendor.hjson - ├── top.core - ├── scripts - │ └── sim - │ ├── compile_remote_bitbang.sh - │ └── compile_uart_dpi.sh - ├── tb - │ └── testharness.sv - ├── util - │ └── vendor.py - ├── Makefile - └── sw - -To achieve this: - -* Create a new top-level repository (`BASE`) and vendorize (or add as git submodules) both your `CORE-V-XIF/OBI` compliant coprocessor/accelerator and `X-HEEP`. -* Copy the `x-heep/hw/system/x_heep_system.sv` as your new top-level module. Then modify it as needed to include your co-processor and connect it to the `core_v_mini_mcu` with the `XIF`. The `XIF` SystemVerilog interface must be instantiated in the top-level module, where `X-HEEP` and your co-processor are connected. See the `X-HEEP` [testbench](./../../../tb/testharness.sv) as an example. -* Before building software remember to run `make mcu-gen CPU=cv32e40px`. - -To add this new top-level module to the simulation/synthesis flow you can extend the [FuseSoC](https://fusesoc.readthedocs.io/en/stable/user/index.html) support of `X-HEEP`. - -- Create a new `tb/testharness.sv` modifying the one in `x-heep/tb/testharness.sv` by adding your new top-level module. -- Create a new `scripts/sim` directory adapting the corresponding ones in `x-heep/scripts/sim`. -- Create a new `.core` FuseSoC file following this example for Modelsim simulation and adapting it to your particular needs: - -
- Example of .core - -``` - CAPI=2: - - # Solderpad Hardware License, Version 2.1, see LICENSE for details. - # SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 - - name: "[YOUR_FUSESOC_IP_NAME]" - description: "[YOUR_IP_DESCRIPTION]" - - filesets: - files_rtl_generic: - depend: - - openhwgroup.org:systems:core-v-mini-mcu - - x-heep:ip:pad_control - - [YOUR_COPROCESSOR] - files: - - hw/[YOUR_TOPLEVEL_SV] - - hw/vendor/esl-epfl_x-heep/hw/system/pad_ring.sv - file_type: systemVerilogSource - - tb: - depend: - - x-heep::tb-utils - files: - - tb/testharness.sv # Your modified testharness - - hw/vendor/esl-epfl_x-heep/tb/tb_top.sv - file_type: systemVerilogSource - - # Scripts for hooks - pre_build_uartdpi: - files: - - scripts/sim/compile_uart_dpi.sh # Your modified scripts - file_type: user - - pre_build_remote_bitbang: - files: - - scripts/sim/compile_remote_bitbang.sh # Your modified scripts - file_type: user - - pre_patch_modelsim_Makefile: - files: - - hw/vendor/esl-epfl_x-heep/scripts/sim/modelsim/patch_modelsim_Makefile.py - file_type: user - - parameters: - COREV_PULP: - datatype: int - paramtype: vlogparam - default: 0 - JTAG_DPI: - datatype: int - paramtype: vlogparam - default: 0 - USE_UPF: - datatype: bool - paramtype: vlogdefine - description: | - Enables simulation with UPF with Modelsim/VCS - - scripts: - pre_build_remote_bitbang: - cmd: - - sh - - ../../../scripts/sim/compile_remote_bitbang.sh - pre_build_uartdpi: - cmd: - - sh - - ../../../scripts/sim/compile_uart_dpi.sh - pre_patch_modelsim_Makefile: - cmd: - - python - - ../../../hw/vendor/esl-epfl_x-heep/scripts/sim/modelsim/patch_modelsim_Makefile.py - - targets: - default: &default_target - filesets: - - files_rtl_generic - - sim: - <<: *default_target - default_tool: modelsim - filesets_append: - - tb - - tool_modelsim? (pre_build_remote_bitbang) - - tool_modelsim? (pre_build_uartdpi) - - tool_modelsim? (pre_patch_modelsim_Makefile) - toplevel: - - tb_top - hooks: - pre_build: - - tool_modelsim? (pre_build_uartdpi) - - tool_modelsim? (pre_build_remote_bitbang) - - tool_modelsim? (pre_patch_modelsim_Makefile) # this is required by Questa 2020 on - parameters: - - COREV_PULP - - JTAG_DPI - tools: - modelsim: - vlog_options: - - -override_timescale 1ns/1ps - - -suppress vlog-2583 - - -suppress vlog-2577 - - -pedanticerrors - - -define MODELSIM - vsim_options: - - -sv_lib ../../../hw/vendor/esl-epfl_x-heep/hw/vendor/lowrisc_opentitan/hw/dv/dpi/uartdpi/uartdpi - - -sv_lib ../../../hw/vendor/esl-epfl_x-heep/hw/vendor/pulp_platform_pulpissimo/rtl/tb/remote_bitbang/librbs -``` - -
- - -## Building Software - -If `X-HEEP` is vendorized into your project, you can still have software source files in any directory of your convenience and build them using `X-HEEP`'s compilation flow. - -### Proposed repository folder structure -The following is an example repository folder structure. - - BASE - ├── sw - │ ├── applications - │ │ └── your_app - │ │ ├── main.c - │ │ ├── your_app.c - │ │ ├── your_app.h - │ │ └── ... - │ ├── build -> ../hw/vendor/esl_epfl_x_heep/sw/build - │ ├── device -> ../hw/vendor/esl_epfl_x_heep/sw/device - │ ├── linker -> ../hw/vendor/esl_epfl_x_heep/sw/linker - │ └── external - │ ├── drivers - │ │ └── your_copro - │ │ ├── your_copro.c - │ │ ├── your_copro.h - │ │ └── your_copro_defs.h -> ../../../../hw/vendor/your_copro/sw/your_copro_defs.h - │ └── extensions - │ │ └── your_copro_x_heep.h - │ └── lib - │ └── crt - │ └── external_crt0.S - ├── hw - │ └── vendor - │ ├── your_copro - │ ├── esl_epfl_x_heep.vendor.hjson - │ └── esl_epfl_x_heep - │ ├── hw - │ ├── sw - │ │ ├── applications - │ │ ├── build - │ │ ├── device - │ │ └── ... - │ ├── Makefile - │ ├── external.mk - │ └── ... - ├── Makefile - ├── util - │ └── vendor.py - └── ... - -Where `BASE` is your repository's base directory, `esl_epfl_x_heep` is the vendorized `X-HEEP` repository and `your_app` is the name of the application you intend to build. - -### The /sw/ folder - -The `BASE/sw/` folder must comply with `X-HEEP` repository structure and therefore include an `applications`, `build`, `device` and `linker` folder. -It is not compulsory for it to be on the `BASE` directory, although this is the default structure that `X-HEEP`'s Makefiles will assume if no other path is specified through the `SOURCE` variable. -Inside the `applications` folder different projects can be stored (still respecting the `name_of_project/main.c` structure). -The `build`, `device` and `linker` should be linked with the vendorized folders inside `X-HEEP`. -In this example that is done from the `BASE` directory as follows: -``` -ln -s ../hw/vendor/esl_epfl_x_heep/sw/build sw/build -ln -s ../hw/vendor/esl_epfl_x_heep/sw/device sw/device -ln -s ../hw/vendor/esl_epfl_x_heep/sw/linker sw/linker -``` - -### The /sw/applications folder -Inside the `sw/applications/` folder you may have different applications that can be built separately. Each application is a directory named after your application, containing one and only one `main.c` file which is built during the compilation process. The folder can contain other source or header files (of any name but `main.c`). - -### The /sw/external folder -In the `external` folder you can add whatever is necessary for software to work with your coprocessor/accelerator. This might include: - -* Sources and header files -* Soft links to folders or files. -* A `lib/crt/` directory with and `exteral_crt0.S` file (will be included inside `BASW/sw/device/lib/crt/crt0.S`). - -The external folder or any of its subdirectories cannot contain neither a `device` nor an `applications` folder as it would collide with the respective folders inside `BASE/sw/`. It should also not contain a `main.c` file. - -### The BASE/Makefile -The `BASE/Makefile` is your own custom Makefile. You can use it as a bridge to access the Makefile from `X-HEEP`. - -To do so, it MUST include the `external.mk` AFTER all your custom rules. - - -
- Example of BASE/Makefile - -```Makefile -MAKE = make -.PHONY: test -test: - @echo Nothing is executed from X-HEEP, as test is not a target inside X-HEEP. - -app: - @echo This target will do something and then call the one inside X-HEEP. - $(MAKE) -f $(XHEEP_MAKE) $(MAKECMDGOALS) PROJECT=hello_world SOURCE=. - -verilator-sim: - @echo You will not access the verilator-sim target from X-HEEP. - -export HEEP_DIR = hw/vendor/esl_epfl_x_heep/ -XHEEP_MAKE = $(HEEP_DIR)/external.mk -include $(XHEEP_MAKE) -``` - -* The `test` rule will not use the `X-HEEP` Makefile in any way. Make the target a prerequisite of `.PHONY` to prevent the X-HEEP Makefile from attempting to run a non-existent target. -* The `app` rule will perform actions before calling `X-HEEP` Makefile's `app` rule. In this case, the project and where the source files are to be extracted from is being specified. The `SOURCE=.` argument will set `X-HEEP`'s own `sw/` folder as the directory from which to fetch source files. This is an example of building inner sources from an external directory. -* The `verilator-sim` rule will override the `X-HEEP` Makefile's one. -* Any other target will be passed straight to `X-HEEP`'s Makefile. For example -```sh -make mcu-gen CPU=cv32e40px -``` -
- - -### Excluding files from compilation -If you have files that need to be excluded from the gcc compilation flow, you can add them to a directory containing the keyword `exclude`, and/or rename the file to include the keyword `exclude`. -In the following example, the files marked with ✅ will be compiled, and the ones marked with ❌ will not. - - BASE - ├── sw - │ ├── applications - │ │ └── your_app - │ │ ├── ✅ main.c - │ │ ├── ✅ your_app.c - │ │ ├── your_app.h - │ │ ├── ❌ my_kernel_exclude.c - │ │ ├── my_kernel.h - │ │ └── exclude_files - │ │ └── ❌ kernel_asm.S - - - -### Makefile help -If you want that the commands `make` or `make help` show the help for your external Makefile, add the following lines before the first `include` directive or target. - -
- Addition to print the target's help - -```Makefile -# HEEP_DIR might already be defined, you may want to move it to the top -export HEEP_DIR = hw/vendor/esl_epfl_x_heep/ - -# Get the path of this Makefile to pass to the Makefile help generator -MKFILE_PATH = $(shell dirname "$(realpath $(firstword $(MAKEFILE_LIST)))") -export FILE_FOR_HELP = $(MKFILE_PATH)/Makefile - - -## Call the help generator. Calling simply -## $ make -## or -## $ make help -## Will print the help of this project. -## With the parameter WHICH you can select to print -## either the help of X-HEEP (WHICH=xheep) -## or both this project's and X-HEEP's (WHICH=all) -help: -ifndef WHICH - ${HEEP_DIR}/util/MakefileHelp -else ifeq ($(filter $(WHICH),xheep x-heep),) - ${HEEP_DIR}/util/MakefileHelp - $(MAKE) -C $(HEEP_DIR) help -else - $(MAKE) -C $(HEEP_DIR) help -endif -``` - -
- -> Remeber to add double hashes `##` on any comment you want printed on the help. -> Use `## @section SectionName` to divide the documentation in sections - -### Different use cases -If you plan to vendorize `X-HEEP` in a different directory than the one proposed, just update in your `BASE/Makefile`: -``` -export HEEP_DIR = -``` - -If you plan to store source files in a different location that the one proposed, just call `make` making the `SOURCE` path explicit. -``` -make app PROJECT=your_app SOURCE= -``` -Consider that inside this `sw` folder the same structure than the one proposed is required. - - -## Inter-process communication using Verilator's DPI - -The following [repository](https://github.com/specs-feup/x-heep) uses X-HEEP and the Verilator simulator to model a CPU-CGRA hybrid system. This architecture simulates the CPU integrated into the X-HEEP system, and an external Java process simulates the accelerator. Both components require a communication channel to exchange instructions and data. Using the existing infrastructure to to interact with an external OS process is not feasible at first sight, given that the X-HEEP ecosystem's pipeline encapsulates most of the simulation build and execution, with all modules supplied directly to Verilator. - -To circumvent this issue, this project uses [Direct Programming Interface (DPI)](https://verilator.org/guide/latest/connecting.html) calls (defined in `hw/ip_examples/cgraitf/cgraitfdpi.c`) to establish a connection and communicate with an external process through a Unix Domain Socket. This behavior mirrors the UART module (used as the skeleton code) that connects and outputs _printf_ information to the pseudo-terminal. These calls are embedded in a mock CGRA peripheral/interface, located in `hw/ip_examples/cgraitf/cgraitf.sv`. The module overrides reads and writes to the specified peripheral address, with the proper socket-based mechanism (_send_ or _recv_). The _simple_accelerator_ module could also be similarly customized to perform the same operations, using X-HEEP's interfaces and memory access protocols. A given user program executed in the CPU (such as `sw/applications/cgra_itf/main.c`) must then select assignments to or from the address to trigger the appropriate action. \ No newline at end of file diff --git a/docs/source/How_to/index.rst b/docs/source/How_to/index.rst new file mode 100644 index 000000000..cb89b7d6a --- /dev/null +++ b/docs/source/How_to/index.rst @@ -0,0 +1,13 @@ +How to... +========= + +Here you can find a list of guides that describe in detail how to use X-HEEP. + +.. toctree:: + :maxdepth: 1 + :glob: + + CompileApps + Simulate + RunOnFPGA + * diff --git a/docs/source/Peripherals/DMA.md b/docs/source/Peripherals/DMA.md index 9b6947633..22bbc0694 100644 --- a/docs/source/Peripherals/DMA.md +++ b/docs/source/Peripherals/DMA.md @@ -22,7 +22,7 @@ The DMA **SDK**, on the other hand, offers user-friendly functions for essential ## Structural description -![DMA subsystem structure](https://github.com/esl-epfl/x-heep/docs/images/dma_structure.png) +![DMA subsystem structure](/images/dma_structure.png)

Figure 1: Structure of the DMA subsystem in X-Heep

diff --git a/docs/source/Peripherals/index.rst b/docs/source/Peripherals/index.rst new file mode 100644 index 000000000..18de3d83d --- /dev/null +++ b/docs/source/Peripherals/index.rst @@ -0,0 +1,10 @@ +Peripherals +=========== + +Here you can find the documentation for all the peripherals in X-HEEP. + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/source/Testing/Testing.md b/docs/source/Testing/Testing.md new file mode 100644 index 000000000..f03b0b06d --- /dev/null +++ b/docs/source/Testing/Testing.md @@ -0,0 +1,61 @@ +# Automatic testing + +X-HEEP includes two tools to perform automatic tests on 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 tests 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. + +```{warning} +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 a PR. diff --git a/docs/source/Verification/VerifHEEP.md b/docs/source/Testing/VerifHEEP.md similarity index 100% rename from docs/source/Verification/VerifHEEP.md rename to docs/source/Testing/VerifHEEP.md diff --git a/docs/source/Testing/index.rst b/docs/source/Testing/index.rst new file mode 100644 index 000000000..e83dad833 --- /dev/null +++ b/docs/source/Testing/index.rst @@ -0,0 +1,10 @@ +Testing +======= + +This section documents the testing and verification systems available in X-HEEP. + +.. toctree:: + :maxdepth: 2 + + Testing + VerifHEEP diff --git a/docs/source/conf.py b/docs/source/conf.py index fd4912ae4..50c9e7fd9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,8 +25,6 @@ 'myst_parser', ] -html_static_path = ['_static'] - source_suffix = ['.rst', '.md'] intersphinx_mapping = { @@ -39,11 +37,14 @@ html_theme = 'sphinx_rtd_theme' +html_logo = "images/x-heep-outline.png" + epub_show_urls = 'footnote' apidoc_module_dir = '../../util/x_heep_gen' -apidoc_output_dir = 'Configuration/generated' +apidoc_output_dir = 'Configuration/x_heep_gen' apidoc_separate_modules = True +apidoc_toc_file = 'index' # Auto-generate header anchors for MyST myst_heading_anchors = 4 diff --git a/docs/source/_static/ides/build_screenshot.png b/docs/source/images/ses_build.png similarity index 100% rename from docs/source/_static/ides/build_screenshot.png rename to docs/source/images/ses_build.png diff --git a/docs/source/_static/ides/debug_screenshot.png b/docs/source/images/ses_debug.png similarity index 100% rename from docs/source/_static/ides/debug_screenshot.png rename to docs/source/images/ses_debug.png diff --git a/docs/source/index.rst b/docs/source/index.rst index 2459bc788..085235e70 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,10 +1,7 @@ X-HEEP ====== -.. image:: images/x-heep-outline.png - :width: 600 - - +.. image:: /images/x-heep-outline.png ``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. @@ -17,8 +14,7 @@ Architecture ^^^^^^^^^^^^ The architecture is thought to be divided into the following power domains: CPU subsystem domain, memory banks domains, peripheral subsystem domain and always-on peripheral subsystem domain. The following image highlights each power domain with a different colour. IPs are carefully selected and grouped in the mentioned power domains in order to maximize energy savings during the processing and acquisition phases of our target ultra-low-power edge-computing applications. We reused several IPs from the most important open-source projects, such as `PULP `_, `OpenHW `_ and `lowRISC `_. Moreover, we custom-designed some specific IPs to meet our architectural needs. -.. image:: images/x_heep.svg - :width: 600 +.. image:: /images/x_heep.svg CPU subsystem domain ^^^^^^^^^^^^^^^^^^^^ @@ -46,8 +42,7 @@ ASIC implementation The following image shows the block diagram of an ASIC implementation (``HEEPocrates``) of X-HEEP that we used to extract the power values for our energy model. -.. image:: images/asic.svg - :width: 600 +.. image:: /images/asic.svg In addition to the already mentioned peripherals, we added a pad ring, a pad controller, a frequency-locked loop (FLL), and an MCU controller. Then, we synthesised and placed and routed the design with ``TSMC 65nm CMOS technology`` and two flavours of cells: low-voltage threshold (LVT) and high-voltage threshold (HVT). The former is high-performance but high-power, while the latter is low-power but low-performance. @@ -61,39 +56,18 @@ We simulated our design with dedicated test applications storing the switching a We extended our ASIC version, adding a course-grained reconfigurable array (CGRA) accelerator and an in-memory computing (IMC) accelerator, and then, we realized our first X-HEEP-based silicon chip, called HEEPpocrates. The chip targets ultra-low-power healthcare applications and is fabricated with TSMC 65nm CMOS technology. Soon, we will be able to perform power measurements on the physical chip and update our energy model with much more accurate real-world power values! -.. image:: images/tapeout.png - :width: 600 +.. image:: /images/tapeout.png Index ^^^^^ .. toctree:: - :maxdepth: 1 - :glob: - :caption: How to... - - ./How_to/GettingStarted - ./How_to/* - -.. toctree:: - :maxdepth: 1 - :glob: - :caption: Peripherals - - ./Peripherals/* - -.. toctree:: - :maxdepth: 5 - :glob: - :caption: Configuration - - ./Configuration/* - ./Configuration/generated/modules.rst - -.. toctree:: - :maxdepth: 1 - :glob: - :caption: Verification - - ./Verification/* + :maxdepth: 2 + + /GettingStarted/index + /How_to/index + /Configuration/index + /Extending/index + /Testing/index + /Peripherals/index