Reorganize and update docs (#615)

* Fix minor issues

* Improve organization

* Add collapsable side pannel and sections

* Update indexes

* Add logo to side menu

* Update updating documentation

* Update and restructure the eXtending HEEP documentation

* Restructure and update the configuration documentation

* Rename eXtending HEEP

.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

Makefile

@@ -150,9 +150,9 @@ verible:
 ## @param PROJECT=<folder_name_of_the_project_to_be_built>
 ## @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), <any RISC-V ISA string supported by the CPU>
+## @param ARCH=rv32imc(default),<any_RISC-V_ISA_string_supported_by_the_CPU>
 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) \
 	|| { \

docs/source/Configuration/BusConfiguration.md

@@ -0,0 +1,3 @@
+# Bus Type Configuration
+
+The bus type can either be configured to `NtoM` or `onetoM`.

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
+        }
+    ]
+}
+```

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
+            },
+        ]
+    }
+}
+```

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

docs/source/Configuration/PeripheralConfiguration.md

@@ -0,0 +1,3 @@
+# Peripheral Configuration
+
+The configuration of the peripherals is in `mcu_cfg.hjson`.

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
+```