treewide: Update docs and tutorial

pulp-platform · Oct 2, 2024 · 3a41223 · 3a41223
1 parent 8a7b526
commit 3a41223
Show file tree

Hide file tree

Showing 34 changed files with 533 additions and 124,523 deletions.
diff --git a/README.md b/README.md
@@ -40,55 +40,59 @@ licenses. See the respective folder for the licenses used.
 
 ## Publications
 
+<!--start-publications-->
 
 If you use the Snitch cluster or its extensions in your work, you can cite us:
 
 <details>
-<summary><b>Snitch: A tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads</b></summary>
+<summary><b><a href="https://doi.org/10.1109/TC.2020.3027900">Snitch: A Tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads</a></a></b></summary>
 <p>
 
 ```
-@article{zaruba2020snitch,
-  title={Snitch: A tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads},
+@ARTICLE{zaruba2021snitch,
   author={Zaruba, Florian and Schuiki, Fabian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
-  year={2020},
-  publisher={IEEE}
+  journal={IEEE Transactions on Computers}, 
+  title={Snitch: A Tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads}, 
+  year={2021},
+  volume={70},
+  number={11},
+  pages={1845-1860},
+  doi={10.1109/TC.2020.3027900}
 }
 ```
 
 </p>
 </details>
 
 <details>
-<summary><b>Stream semantic registers: A lightweight risc-v isa extension achieving full compute utilization in single-issue cores</b></summary>
+<summary><b><a href="https://doi.org/10.1109/TC.2020.2987314">Stream Semantic Registers: A Lightweight RISC-V ISA Extension Achieving Full Compute Utilization in Single-Issue Cores</a></b></summary>
 <p>
 
 ```
-@article{schuiki2020stream,
-  title={Stream semantic registers: A lightweight risc-v isa extension achieving full compute utilization in single-issue cores},
+@ARTICLE{schuiki2021ssr,
   author={Schuiki, Fabian and Zaruba, Florian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
+  journal={IEEE Transactions on Computers}, 
+  title={Stream Semantic Registers: A Lightweight RISC-V ISA Extension Achieving Full Compute Utilization in Single-Issue Cores}, 
+  year={2021},
   volume={70},
   number={2},
-  pages={212--227},
-  year={2020},
-  publisher={IEEE}
+  pages={212-227},
+  doi={10.1109/TC.2020.2987314}
 }
 ```
 
 </p>
 </details>
 
 <details>
-<summary><b>Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra</b></summary>
+<summary><b><a href="https://doi.org/10.1109/TPDS.2023.3322029">Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra</a></b></summary>
 <p>
 
 ```
-@article{scheffler2023sparsessr,
+@ARTICLE{scheffler2023sparsessr,
   author={Scheffler, Paul and Zaruba, Florian and Schuiki, Fabian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Parallel and Distributed Systems},
-  title={Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra},
+  journal={IEEE Transactions on Parallel and Distributed Systems}, 
+  title={Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra}, 
   year={2023},
   volume={34},
   number={12},
@@ -101,52 +105,54 @@ If you use the Snitch cluster or its extensions in your work, you can cite us:
 </details>
 
 <details>
-<summary><b>A High-performance, Energy-efficient Modular DMA Engine Architecture</b></summary>
+<summary><b><a href="https://doi.org/10.1109/TC.2023.3329930">A High-Performance, Energy-Efficient Modular DMA Engine Architecture</a></b></summary>
 <p>
 
 ```
-@ARTICLE{benz2023idma,
+@ARTICLE{benz2024idma,
   author={Benz, Thomas and Rogenmoser, Michael and Scheffler, Paul and Riedel, Samuel and Ottaviano, Alessandro and Kurth, Andreas and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
-  title={A High-performance, Energy-efficient Modular DMA Engine Architecture},
-  year={2023},
-  volume={},
-  number={},
-  pages={1-14},
-  doi={10.1109/TC.2023.3329930}}
+  journal={IEEE Transactions on Computers}, 
+  title={A High-Performance, Energy-Efficient Modular DMA Engine Architecture}, 
+  year={2024},
+  volume={73},
+  number={1},
+  pages={263-277},
+  doi={10.1109/TC.2023.3329930}
+}
 ```
 
 </p>
 </details>
 
 <details>
-<summary><b>MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores</b></summary>
+<summary><b><a href="https://doi.org/10.1109/ARITH54963.2022.00010">MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores</a></b></summary>
 <p>
 
 ```
-@inproceedings{bertaccini2022minifloat,
+@INPROCEEDINGS{bertaccini2022minifloat,
   author={Bertaccini, Luca and Paulin, Gianna and Fischer, Tim and Mach, Stefan and Benini, Luca},
-  booktitle={2022 IEEE 29th Symposium on Computer Arithmetic (ARITH)},
-  title={MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores},
+  booktitle={2022 IEEE 29th Symposium on Computer Arithmetic (ARITH)}, 
+  title={MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores}, 
   year={2022},
   volume={},
   number={},
-  pages={1-8}
+  pages={1-8},
+  doi={10.1109/ARITH54963.2022.00010}
 }
 ```
 
 </p>
 </details>
 
 <details>
-<summary><b>Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters</b></summary>
+<summary><b><a href="https://doi.org/10.1109/ISVLSI54635.2022.00021">Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters</a></b></summary>
 <p>
 
 ```
-@inproceedings{paulin2022softtiles,
+@INPROCEEDINGS{paulin2022softtiles,
   author={Paulin, Gianna and Cavalcante, Matheus and Scheffler, Paul and Bertaccini, Luca and Zhang, Yichao and Gürkaynak, Frank and Benini, Luca},
-  booktitle={2022 IEEE Computer Society Annual Symposium on VLSI (ISVLSI)},
-  title={Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters},
+  booktitle={2022 IEEE Computer Society Annual Symposium on VLSI (ISVLSI)}, 
+  title={Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters}, 
   year={2022},
   volume={},
   number={},
@@ -159,20 +165,23 @@ If you use the Snitch cluster or its extensions in your work, you can cite us:
 </details>
 
 <details>
-<summary><b>SARIS: Accelerating Stencil Computations on Energy-Efficient RISC-V Compute Clusters with Indirect Stream Registers</b></summary>
+<summary><b><a href="https://doi.org/10.48550/arXiv.2404.05303">SARIS: Accelerating Stencil Computations on Energy-Efficient RISC-V Compute Clusters with Indirect Stream Registers</a></b></summary>
 <p>
 
 ```
 @misc{scheffler2024saris,
-      title={SARIS: Accelerating Stencil Computations on Energy-Efficient
-             RISC-V Compute Clusters with Indirect Stream Registers},
-      author={Paul Scheffler and Luca Colagrande and Luca Benini},
-      year={2024},
-      eprint={2404.05303},
-      archivePrefix={arXiv},
-      primaryClass={cs.MS}
+  title={SARIS: Accelerating Stencil Computations on Energy-Efficient
+         RISC-V Compute Clusters with Indirect Stream Registers},
+  author={Paul Scheffler and Luca Colagrande and Luca Benini},
+  year={2024},
+  eprint={2404.05303},
+  archivePrefix={arXiv},
+  primaryClass={cs.MS},
+  url={https://arxiv.org/abs/2404.05303}
 }
 ```
 
 </p>
 </details>
+
+<!--end-publications-->
diff --git a/docs/publications.md b/docs/publications.md
@@ -1,141 +1,8 @@
 # Publications
 
-If you use the Snitch cluster or its extensions in your work, you can cite us:
-
-<!--start-publications-->
-
-<details>
-<summary><b>Snitch: A tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads</b></summary>
-<p>
-
-```
-@article{zaruba2020snitch,
-  title={Snitch: A tiny Pseudo Dual-Issue Processor for Area and Energy Efficient Execution of Floating-Point Intensive Workloads},
-  author={Zaruba, Florian and Schuiki, Fabian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
-  year={2020},
-  publisher={IEEE}
-}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>Stream semantic registers: A lightweight risc-v isa extension achieving full compute utilization in single-issue cores</b></summary>
-<p>
-
-```
-@article{schuiki2020stream,
-  title={Stream semantic registers: A lightweight risc-v isa extension achieving full compute utilization in single-issue cores},
-  author={Schuiki, Fabian and Zaruba, Florian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
-  volume={70},
-  number={2},
-  pages={212--227},
-  year={2020},
-  publisher={IEEE}
-}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra</b></summary>
-<p>
-
-```
-@article{scheffler2023sparsessr,
-  author={Scheffler, Paul and Zaruba, Florian and Schuiki, Fabian and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Parallel and Distributed Systems},
-  title={Sparse Stream Semantic Registers: A Lightweight ISA Extension Accelerating General Sparse Linear Algebra},
-  year={2023},
-  volume={34},
-  number={12},
-  pages={3147-3161},
-  doi={10.1109/TPDS.2023.3322029}
-}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>A High-performance, Energy-efficient Modular DMA Engine Architecture</b></summary>
-<p>
-
-```
-@ARTICLE{benz2023idma,
-  author={Benz, Thomas and Rogenmoser, Michael and Scheffler, Paul and Riedel, Samuel and Ottaviano, Alessandro and Kurth, Andreas and Hoefler, Torsten and Benini, Luca},
-  journal={IEEE Transactions on Computers},
-  title={A High-performance, Energy-efficient Modular DMA Engine Architecture},
-  year={2023},
-  volume={},
-  number={},
-  pages={1-14},
-  doi={10.1109/TC.2023.3329930}}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores</b></summary>
-<p>
-
-```
-@inproceedings{bertaccini2022minifloat,
-  author={Bertaccini, Luca and Paulin, Gianna and Fischer, Tim and Mach, Stefan and Benini, Luca},
-  booktitle={2022 IEEE 29th Symposium on Computer Arithmetic (ARITH)},
-  title={MiniFloat-NN and ExSdotp: An ISA Extension and a Modular Open Hardware Unit for Low-Precision Training on RISC-V Cores},
-  year={2022},
-  volume={},
-  number={},
-  pages={1-8}
-}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters</b></summary>
-<p>
-
-```
-@inproceedings{paulin2022softtiles,
-  author={Paulin, Gianna and Cavalcante, Matheus and Scheffler, Paul and Bertaccini, Luca and Zhang, Yichao and Gürkaynak, Frank and Benini, Luca},
-  booktitle={2022 IEEE Computer Society Annual Symposium on VLSI (ISVLSI)},
-  title={Soft Tiles: Capturing Physical Implementation Flexibility for Tightly-Coupled Parallel Processing Clusters},
-  year={2022},
-  volume={},
-  number={},
-  pages={44-49},
-  doi={10.1109/ISVLSI54635.2022.00021}
-}
-```
-
-</p>
-</details>
-
-<details>
-<summary><b>SARIS: Accelerating Stencil Computations on Energy-Efficient RISC-V Compute Clusters with Indirect Stream Registers</b></summary>
-<p>
-
-```
-@misc{scheffler2024saris,
-      title={SARIS: Accelerating Stencil Computations on Energy-Efficient
-             RISC-V Compute Clusters with Indirect Stream Registers},
-      author={Paul Scheffler and Luca Colagrande and Luca Benini},
-      year={2024},
-      eprint={2404.05303},
-      archivePrefix={arXiv},
-      primaryClass={cs.MS}
-}
-```
-
-</p>
-</details>
-
-<!--end-publications-->
+{%
+   include-markdown '../README.md'
+   start="<!--start-publications-->"
+   end="<!--end-publications-->"
+   comments=false
+%}
diff --git a/docs/rm/custom_instructions.md → docs/rm/hw/custom_instructions.md b/docs/rm/custom_instructions.md → docs/rm/hw/custom_instructions.md
@@ -37,7 +37,7 @@ The FREP instruction has the following signature:
 | max_inst | max_rpt | stagger_max | stagger_mask | 0        | OP-CUSTOM1 | FREP.I    |
 | max_inst | max_rpt | stagger_max | stagger_mask | 1        | OP-CUSTOM1 | FREP.O    |
 
-FREP.I and FREP.O repeat the *max_inst + 1* instructions following the FREP instruction for *max_rpt + 1* times. The FREP.I instruction (*I* stands for inner) repeats every instruction the specified number of times and moves on to executing and repeating the next. The FREP.O instruction (*O* stands for outer) repeats the whole sequence of instructions *max_rpt + 1* times. Register staggering can be enabled and configured via the *stagger_mask* and *stagger_max* immediates. A detailed explanation of their use can be found in the Snitch [paper](/publications).
+FREP.I and FREP.O repeat the *max_inst + 1* instructions following the FREP instruction for *max_rpt + 1* times. The FREP.I instruction (*I* stands for inner) repeats every instruction the specified number of times and moves on to executing and repeating the next. The FREP.O instruction (*O* stands for outer) repeats the whole sequence of instructions *max_rpt + 1* times. Register staggering can be enabled and configured via the *stagger_mask* and *stagger_max* immediates. A detailed explanation of their use can be found in the Snitch [paper](../..//publications.md).
 
 The assembly instruction signature follows:
 

diff --git a/docs/rm/peripherals.md → docs/rm/hw/peripherals.md b/docs/rm/peripherals.md → docs/rm/hw/peripherals.md
@@ -2,4 +2,4 @@
 
 This section documents the registers exposed by the Snitch cluster to interface with various cluster-level peripherals, including the performance counters.
 
-{% include-markdown '../generated/peripherals.md' %}
+{% include-markdown '../../generated/peripherals.md' %}
diff --git a/docs/rm/hw/reqrsp_interface.md b/docs/rm/hw/reqrsp_interface.md
@@ -0,0 +1 @@
+../../../hw/reqrsp_interface/doc/index.md
diff --git a/docs/rm/hw/snitch.md b/docs/rm/hw/snitch.md
@@ -0,0 +1 @@
+../../../hw/snitch/doc/index.md
diff --git a/docs/rm/hw/snitch_cluster.md b/docs/rm/hw/snitch_cluster.md
@@ -0,0 +1 @@
+../../../hw/snitch_cluster/doc/index.md
diff --git a/docs/rm/reqrsp_interface.md b/docs/rm/reqrsp_interface.md
diff --git a/docs/rm/snitch.md b/docs/rm/snitch.md
diff --git a/docs/rm/snitch_cluster.md b/docs/rm/snitch_cluster.md
diff --git a/docs/rm/bench/join.md → docs/rm/sw/bench/join.md b/docs/rm/bench/join.md → docs/rm/sw/bench/join.md
diff --git a/docs/rm/bench/roi.md → docs/rm/sw/bench/roi.md b/docs/rm/bench/roi.md → docs/rm/sw/bench/roi.md
diff --git a/docs/rm/bench/visualize.md → docs/rm/sw/bench/visualize.md b/docs/rm/bench/visualize.md → docs/rm/sw/bench/visualize.md
diff --git a/docs/rm/sim/Elf.md → docs/rm/sw/sim/Elf.md b/docs/rm/sim/Elf.md → docs/rm/sw/sim/Elf.md
diff --git a/docs/rm/sim/Simulation.md → docs/rm/sw/sim/Simulation.md b/docs/rm/sim/Simulation.md → docs/rm/sw/sim/Simulation.md
diff --git a/docs/rm/sim/Simulator.md → docs/rm/sw/sim/Simulator.md b/docs/rm/sim/Simulator.md → docs/rm/sw/sim/Simulator.md
diff --git a/docs/rm/sim/data_utils.md → docs/rm/sw/sim/data_utils.md b/docs/rm/sim/data_utils.md → docs/rm/sw/sim/data_utils.md
diff --git a/docs/rm/sim/sim_utils.md → docs/rm/sw/sim/sim_utils.md b/docs/rm/sim/sim_utils.md → docs/rm/sw/sim/sim_utils.md
diff --git a/docs/rm/sim/verif_utils.md → docs/rm/sw/sim/verif_utils.md b/docs/rm/sim/verif_utils.md → docs/rm/sw/sim/verif_utils.md
diff --git a/docs/rm/snitch_target_utils/build.md → docs/rm/sw/snitch_target_utils/build.md b/docs/rm/snitch_target_utils/build.md → docs/rm/sw/snitch_target_utils/build.md
diff --git a/docs/rm/snitch_target_utils/run.md → docs/rm/sw/snitch_target_utils/run.md b/docs/rm/snitch_target_utils/run.md → docs/rm/sw/snitch_target_utils/run.md
diff --git a/docs/rm/trace/annotate.md → docs/rm/sw/trace/annotate.md b/docs/rm/trace/annotate.md → docs/rm/sw/trace/annotate.md
diff --git a/docs/rm/trace/events.md → docs/rm/sw/trace/events.md b/docs/rm/trace/events.md → docs/rm/sw/trace/events.md
diff --git a/docs/rm/trace/gen_trace.md → docs/rm/sw/trace/gen_trace.md b/docs/rm/trace/gen_trace.md → docs/rm/sw/trace/gen_trace.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		This section documents the registers exposed by the Snitch cluster to interface with various cluster-level peripherals, including the performance counters.

		{% include-markdown '../generated/peripherals.md' %}
		{% include-markdown '../../generated/peripherals.md' %}