From edf07eec1b3c08e1b306a33b13bbb85ba5bc339d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Mallas=C3=A9n?= Date: Fri, 20 Dec 2024 11:42:17 +0100 Subject: [PATCH 1/4] Fix typo --- docs/source/How_to/CompileMakefile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/How_to/CompileMakefile.md b/docs/source/How_to/CompileMakefile.md index 972c93f8e..9e4ea873d 100644 --- a/docs/source/How_to/CompileMakefile.md +++ b/docs/source/How_to/CompileMakefile.md @@ -70,7 +70,7 @@ This will create the executable file to be loaded in your target system (ASIC, F Remember that, `X-HEEP` is using CMake to compile and link. Thus, the generated files after having compiled and linked are under `sw\build` -## FreeROTS based applications +## FreeRTOS based applications 'X-HEEP' supports 'FreeRTOS' based applications. Please see `sw\applications\example_freertos_blinky`. From c4d6cea02fc698e243da98fda377bc459aa0015c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Mallas=C3=A9n?= Date: Fri, 20 Dec 2024 11:52:18 +0100 Subject: [PATCH 2/4] Add make to prerequisites --- docs/source/How_to/GettingStarted.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/How_to/GettingStarted.md b/docs/source/How_to/GettingStarted.md index 4b7b66855..d015701dd 100644 --- a/docs/source/How_to/GettingStarted.md +++ b/docs/source/How_to/GettingStarted.md @@ -33,7 +33,7 @@ All the command listed in the README can be execute in the docker container, exc To use `X-HEEP`, first make sure you have the following apt packages, or install them as: ```bash -sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 libssl-dev libudev-dev libusb-1.0-0 lsb-release texinfo autoconf cmake flex bison libexpat-dev gawk tree xterm python3-venv python3-dev +sudo apt install lcov libelf1 libelf-dev libftdi1-2 libftdi1-dev libncurses5 libssl-dev libudev-dev libusb-1.0-0 lsb-release texinfo autoconf make cmake flex bison libexpat-dev gawk tree xterm python3-venv python3-dev ``` In general, have a look at the [Install required software](https://opentitan.org/guides/getting_started/index.html) section of the OpenTitan documentation. From 09499835e2bc742e2e54163b990da845fa2a8a71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Mallas=C3=A9n?= Date: Fri, 20 Dec 2024 12:09:16 +0100 Subject: [PATCH 3/4] Fix minor doc errors --- docs/source/Peripherals/DMA.md | 12 ++++++------ docs/source/Peripherals/SPI.md | 2 +- docs/source/Verification/VerifHEEP.md | 24 ++++++++++++------------ docs/source/conf.py | 5 ++++- docs/source/index.rst | 9 ++++++++- 5 files changed, 31 insertions(+), 21 deletions(-) diff --git a/docs/source/Peripherals/DMA.md b/docs/source/Peripherals/DMA.md index a3b4d890f..9b6947633 100644 --- a/docs/source/Peripherals/DMA.md +++ b/docs/source/Peripherals/DMA.md @@ -26,7 +26,7 @@ The DMA **SDK**, on the other hand, offers user-friendly functions for essential

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

-#### DMA channels layout +### DMA channels layout The DMA subsystem is composed of a parametrized number of control units called **channels**. Each channel can be configured, by the CPU or by an external controller, to perform a *transaction*, independently of the state of other channels. @@ -52,7 +52,7 @@ While the 1st solution is a general purpose, balanced configuration, the 2nd sol This mechanism guarantees **maximum flexibility**, enabling the user to adapt the DMA subsystem to its requirements, both in terms of area and performance.
-#### Interrupts +### Interrupts If enabled, a transaction interrupt is raised every time a DMA transaction is completed. However, due to architectural limitations, there is only a single transaction done signal for the entire DMA subsystem. @@ -64,7 +64,7 @@ It is possible that a channel could raise an interrupt while the CPU is processi For this reason, the handler implemented by the user should be as brief as possible. -#### Data FIFOs configuration +### Data FIFOs configuration Each DMA channel uses FIFOs to buffer the data to be read and written, which is crucial for mitigating the combined delays from the system bus and the Always On Peripheral Bus (**AOPB**). @@ -96,7 +96,7 @@ Now, let's set the first 2 channels, CH0 and CH1, to the large size, CH2 to smal
-#### Triggers +### Triggers In the case of memory-peripheral operations, it is common for the peripheral to have a reaction time that cannot match the system clock. For example, the SPI trasmits data with a period of circa 30 clock cycles. @@ -107,7 +107,7 @@ The DMA can be configured to respond to triggers by enabling the appropriate _sl
-#### Tips for DMA-based accelerator developers +### Tips for DMA-based accelerator developers The DMA subsystem has been developed with specific features to facilitate the creation of custom accelerators that can leverage it to improve memory-intense applications. @@ -132,7 +132,7 @@ Additional documentation can be found in the **VerifHEEP documentation**, but in - Analyze the performance of the tests.
-### Registers description +## Registers description This section will describe every register of a DMA channel and their function. The complete addres of a DMA channel register is the following: diff --git a/docs/source/Peripherals/SPI.md b/docs/source/Peripherals/SPI.md index 72315f6c5..06d020107 100644 --- a/docs/source/Peripherals/SPI.md +++ b/docs/source/Peripherals/SPI.md @@ -1189,7 +1189,7 @@ checks wherever needed. A performance testing was carried out utilizing the _EPFL Programmer_, which includes a _W25Q128JW_ flash memory, and the _PYNQ-Z2_ FPGA. The -[SPI Flash Loading Boot Procedure](/How_to/ExecuteFromFlash.html#spi-flash-loading-boot-procedure) +[SPI Flash Loading Boot Procedure](../How_to/ExecuteFromFlash.md#spi-flash-loading-boot-procedure) was employed for all tests. The test application used the diff --git a/docs/source/Verification/VerifHEEP.md b/docs/source/Verification/VerifHEEP.md index 13ffd94e9..ef75168d2 100644 --- a/docs/source/Verification/VerifHEEP.md +++ b/docs/source/Verification/VerifHEEP.md @@ -20,7 +20,7 @@ Additionally, the EPFL programmer will be used for serial communication with the ## Methods description -#### __init__ +### __init__ _Purpose_: The initialization function is used to create the VerifHeep object. During this process, it's required to indicate the target of the verification and its directory. Furthermore, an optimization flag can be set when synthesis or simulation module building will be performed. @@ -33,7 +33,7 @@ _Parameters_: - **xheep_dir**: Sets the directory of the X-Heep project, necessary to run scripts. - **opt_en**: By default set to _false_, this flag indicates whether optimization should be performed when building the simulation model. Available **only** with QuestaSim! -#### compileModel +### compileModel _Purpose_: This method is used to compile a simulation model for both Verilator and QuestaSim, i.e. run _make mcu-gen_, provided they are properly installed on the host system. @@ -43,7 +43,7 @@ _Parameters_: - **cpu**: By default set to `cv32e40px`, this flags indicates which CPU will be included in the model. - **bus**: By default set to `1toN`, this flag indicates the bus type. -#### buildModel +### buildModel _Purpose_: This method is used to either build a simulation model for Verilator or QuestaSim or to synthesize the project with Xilinx Vivado, provided they are properly installed on the host system. @@ -53,7 +53,7 @@ _Parameters_: - **cpu**: By default set to `cv32e40px`, this flags indicates which CPU will be included. - **bus**: By default set to `1toN`, this flag indicates the bus type. -#### serialBegin +### serialBegin _Purpose_: This method is used to set up the serial communication with the _pynq-z2_ FPGA board. @@ -68,7 +68,7 @@ _Parameters_: _Return value_: - **Outcome of the connection**, which is _False_ for unsuccessful. -#### setupDeb +### setupDeb _Purpose_: This method is used to set up the GDB debugger. It creates a process on which the debug communication will be run, thus making this function conveniently non-blocking. @@ -78,7 +78,7 @@ This method is used to set up the GDB debugger. It creates a process on which th _Parameters_: None -#### stopDeb +### stopDeb _Purpose_: This method is used to close the debugger. Useful both at the end of a script or during the cyclical reset of the debug connection, as explained before. @@ -86,7 +86,7 @@ This method is used to close the debugger. Useful both at the end of a script or _Parameters_: None -#### genInputDataset +### genInputDataset _Purpose_: This method is used to generate random data that the application can use to perform verification. It's possible to set the range of the data, the dimension of the array, the datatype and its variable identifier. In addition, it's possible to obtain a single _.h_ file or both a _.c_ and a _.h_ file. @@ -101,7 +101,7 @@ _Parameters_: - **dataset_name**: Indicates the name of the dataset. - **datatype**: By default set to *uint32_t*, indicates the datatype of the array to be generated. -#### genGoldenResult +### genGoldenResult _Purpose_: This method is used to generate golden data from an input dataset, enabling applications to verify the functionality of a unit or accelerator. This feature is performed by a user-defined function, passed as a parameter, which processes the input data. @@ -120,7 +120,7 @@ _Parameters_: - **golden_name**: Indicates the name of the golden result array. - **output_datatype**: By default set to *uint32_t*, indicates the datatype of the array to be computed. -#### modifyFile +### modifyFile _Purpose_: This method is simple yet very useful in particular situations. It allows the user to modify a row with a replacement of its choice. It can be used to modify _#define_ that could change the behaviour of the application. @@ -133,14 +133,14 @@ _Parameters_: - **pattern**: Indicates the pattern to look for in the file, using the library **re**. - **replacement**: Indicates the row that will be put in place instead of the pattern found. -#### chronoStart/chronoStop +### chronoStart/chronoStop _Purpose_:This method is used to track the execution time of an iteration and, by extension, to estimate the total execution time of the verification process. _Parameters_: None -#### chronoExecutionEst +### chronoExecutionEst _Purpose_:This method estimates the total execution time of the verification process, assuming the verification consists of a loop with N iterations. It requires that the `_chronoStart_` method is called at the beginning and the `_chronoStop_` method is called at the end of each iteration. @@ -153,7 +153,7 @@ _Return value_: - _"minutes"_ - _"seconds"_ -#### launchTest +### launchTest _Purpose_: This method is crucial in the verification process, as it's in charge of compiling the application, loading it on the FPGA using the scan chains and GDB, waiting for the results and storing then in *self.results*. diff --git a/docs/source/conf.py b/docs/source/conf.py index 44ce6b68c..fd4912ae4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -43,4 +43,7 @@ apidoc_module_dir = '../../util/x_heep_gen' apidoc_output_dir = 'Configuration/generated' -apidoc_separate_modules = True \ No newline at end of file +apidoc_separate_modules = True + +# Auto-generate header anchors for MyST +myst_heading_anchors = 4 diff --git a/docs/source/index.rst b/docs/source/index.rst index a0d4c7463..2459bc788 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -89,4 +89,11 @@ Index :caption: Configuration ./Configuration/* - ./Configuration/generated/modules.rst \ No newline at end of file + ./Configuration/generated/modules.rst + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: Verification + + ./Verification/* From a5faa2c9be58a03315af5db64c582b661785db60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Mallas=C3=A9n?= Date: Fri, 20 Dec 2024 12:09:37 +0100 Subject: [PATCH 4/4] Update documentation instructions --- docs/source/How_to/UpdateDocumentation.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/source/How_to/UpdateDocumentation.md b/docs/source/How_to/UpdateDocumentation.md index c27a87760..f0125b141 100644 --- a/docs/source/How_to/UpdateDocumentation.md +++ b/docs/source/How_to/UpdateDocumentation.md @@ -1,27 +1,26 @@ # Update the documentation -All documentation is found in the `/docs` directory. +All documentation is found in the `/docs` directory. Thank you for helping keep X-HEEP accurately and extensively documented! 1. If you need to create a new entry, add the new document in markdown (`.md` extension) to the corresponding folder. Otherwise, just edit the corresponding file. > Make sure the document has one single `# header`, otherwise they will be considered different documents. -2. If a new folder is added, add it to the `toctree` inside `docs/source/index.rst` (as the `peripherals` folder is) -3. Commit and push +2. If a new folder is added, add it to the `toctree` inside `docs/source/index.rst` (as the `peripherals` folder is). +3. Commit and push. +4. 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. -## Refresh the web documentation +## Build locally the web documentation -After each change to the documentation, once the branch is merged into the main branch of X-HEEP, anyone must do the following: +If you want to build the web documentation locally to test or debug the build: 1. Open a terminal in the `docs` folder and make sure the conda environment is activated. -2. If it is your first time updating the web docs, run: +2. The first time you do this, run: ```bash pip install -r requirements.txt ``` -3. Run +3. Run: ```bash make clean html ``` -4. Wait a few minutes and enjoy your brand new documentation in [Read the Docs](https://x-heep.readthedocs.io/en/latest/). - -Thank you for helping keep X-HEEP accurately and extensively documented!