docs: Extend documentation + deploy with mkdocs

.github/workflows/publish-docs.yml

@@ -0,0 +1,32 @@
+# Copyright 2024 ETH Zurich and University of Bologna.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# Author: Tim Fischer <[email protected]>
+
+name: publish-docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: pip
+      - name: Install Python requirements
+        run: pip install .[docs]
+      - name: Deploy Documentation
+        run: mkdocs gh-deploy --force

Makefile

@@ -24,7 +24,7 @@ run-sim-batch: run-vsim-batch
 ############
 
 BENDER     	?= bender
-VSIM       	?= questa-2023.4 vsim
+VSIM       	?= vsim
 SPYGLASS   	?= sg_shell
 VERIBLE_FMT	?= verible-verilog-format
 VCS		      ?= vcs-2022.06 vcs

README.md

@@ -9,7 +9,7 @@
 <img src="docs/img/pulp_logo_icon.svg" alt="Logo" width="100" align="right">
 </a>
 
-This repository provides modules for the FlooNoC, a Network-on-Chip (NoC) which is part of the [PULP (Parallel Ultra-Low Power) Platform](https://pulp-platform.org/). The repository includes Network Interface IPs (named chimneys), Routers and further NoC components to build a complete NoC. FlooNoC mainly supports [AXI4+ATOPs](https://github.com/pulp-platform/axi/tree/master), but can be easily extended to other On-Chip protocols. Arbitrary topologies are supported with several routing algorithms. FlooNoC is designed to be scalable and modular, and can be easily extended with new components. Additionally, FlooNoC provides a generation framework for creating customized NoC configurations.
+_FlooNoC_, is a Network-on-Chip (NoC) research project, which is part of the [PULP (Parallel Ultra-Low Power) Platform](https://pulp-platform.org/). The main idea behind _FlooNoC_ is to provide a scalable high-performance NoC for non-coherent systems. _FlooNoC_ was mainly designed to interface with [AXI4+ATOPs](https://github.com/pulp-platform/axi/tree/master), but can easily be extended to other On-Chip protocols. _FlooNoC_ already provides network interface IPs (named chimneys) for AXI4 protocol, which converts to a custom-link level protocol that provides significantly better scalability than AXI4. _FlooNoC_ also includes protocol-agnostic routers based on the custom link-level protocol to transport payloads. Finally, _FlooNoC_ also include additional NoC components to assemble a complete NoC in a modular fashion. _FlooNoC_ is also highly flexible and supports a wide variety of topologies and routing algorithms. A Network generation framework called _FlooGen_ makes it possible to easily generate entire networks based on a simple configuration file.
 
 <div align="center">
 
@@ -29,13 +29,18 @@ This repository provides modules for the FlooNoC, a Network-on-Chip (NoC) which
 
 ## 💡 Design Principles
 
-Our NoC design is grounded in the following key principles:
+_FlooNoC_ design is based on the following key principles:
+
+1. **Full AXI4 Support**: _FlooNoC_ fully supports AXI4+ATOPs from AXI5 as outlined [here](https://github.com/pulp-platform/axi/tree/master), providing a high-bandwidth and latency-tolerant solution. _FlooNoC_ achieves this with full support for bursts and multiple outstanding transactions.
+
+1. **Decoupled Links and Networks**: _FlooNoC_ uses a link-level protocol that is decoupled from the network-level protocol. This allows us to move the complexity of the network-level protocol into the network interfaces, while deploying low-complexity routers in the network, that enable better scalability than multi-layer AXI networks.
+
+1. **Wide Physical Channels**: _FlooNoC_ uses wide physical channels to meet the high-bandwidth requirements at network endpoints without being constrained by the operating frequency. In contrast to traditional NoCs which use serialization with header and tail flits to transport a message, _FlooNoC_ avoids any kind of serialization and sends entire messages in a single flit including header and tail information.
+
+1. **Separation of traffic**: _FlooNoC_ addresses diverse types of traffic that can occur in non-coherent systems, by decoupling multiple links to handle wide, high-bandwidth, burst-based traffic and narrow, latency-sensitive traffic with separate physical channels.
+
+1. **Modularity:** The _FlooNoC_ architecture is designed with modularity in mind. It includes a set of IPs that can be instantiated together to build a NoC. This approach not only promotes reusability but also facilitates flexibility in designing custom NoCs to cater to a variety of specific system requirements.
 
-1. **Full AXI4 Support**: Our design fully supports AXI4+ATOPs from AXI5 as outlined [here](https://github.com/pulp-platform/axi/tree/master), particularly multiple outstanding burst transactions. It utilizes low-complexity routers and a decoupled link-level protocol to ensure scalability, thereby enabling tolerance to high-latency off-chip accesses.
-1. **Decoupled Links and Networks**: We use a link-level protocol that is decoupled from the network-level protocol. This allows us to move the complexity of the network-level protocol into the network interfaces, while deploying low-complexity routers in the network, that enable better scalability.
-1. **Wide Physical Channels**: We incorporate wide physical channels in order to meet the high-bandwidth requirements at network endpoints without being constrained by the operating frequency. This is in contrast to the traditional narrow link approach. Further, the NoC avoids any kind of serialization and sends entire messages in a single flit including header and tail information.
-1. **Separation of traffic**: Our design acknowledges the diversity in traffic patterns, as it decouples links and networks to handle wide, high-bandwidth, burst-based traffic and narrow, latency-sensitive traffic with separate physical channels.
-1. **Modularity:** Our design principles also emphasize modularity. We have developed a set of IPs that can be instantiated together to build a NoC. This approach not only promotes reusability but also facilitates flexibility in designing custom NoCs to cater to a variety of specific system requirements.
 
 ## 🔮 Origin of the name
 

docs/Apache-License.md

@@ -0,0 +1 @@
+../LICENSE-APACHE

docs/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Guide to Contributing
+
+TODO

docs/SHL-License.md

@@ -0,0 +1 @@
+../LICENSE-SHL

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/floogen/overview.md

@@ -0,0 +1,70 @@
+# Overview
+
+_FlooNoC_ comes with a generation framework called _FlooGen_. It allows to create complex network configurations with a high-level configuration file.
+
+## How it works
+
+Internally _FlooGen_ has a graph-based representation of the network based on the configuration file that is given as an input by the user. Thanks to this, _FlooGen_ is capable of performing the following things:
+
+- **Validation**: The configuration given by the user is validated to ensure that the input is valid and does not contain any accidental mistakes. For instance, _FlooGen_ automatically checks for overlapping address ranges, or router ports that are assigned multpile times.
+
+- **Routing**: Based on the connectivity graph of the network, _FlooGen_ is able to derive all required routing related information such as routing tables and the system address map which is used by routers and network interfaces.
+
+- **Package Generation**: _FlooGen_ automatically generates a SystemVerilog package with all the needed AXI and flit types, which additionally includes all the routing information.
+
+- **Top Module Generation**: _FlooGen_ can also generate a top module that instantiates all router and network interfaces. The interfaces of the top module are AXI4 interfaces for all the enpdoints specified in the configuration.
+
+## Exmaple configuration
+
+Below is an example of a configuration for a simple 4x4 mesh network, which will be explained in more detail in the next sections:
+
+```yaml
+name: axi_mesh
+description: "AXI mesh configuration with XY routing for FlooGen"
+network_type: "axi"
+
+routing:
+  route_algo: "XY"
+  use_id_table: true
+
+protocols:
+  - name: "axi_in"
+    protocol: "AXI4"
+    data_width: 64
+    addr_width: 48
+    id_width: 4
+    user_width: 1
+  - name: "axi_out"
+    protocol: "AXI4"
+    data_width: 64
+    addr_width: 48
+    id_width: 2
+    user_width: 1
+
+endpoints:
+  - name: "cluster"
+    array: [4, 4]
+    addr_range:
+      base: 0x0000_0000_0000
+      size: 0x0000_0001_0000
+    mgr_port_protocol:
+      - "axi_in"
+    sbr_port_protocol:
+      - "axi_out"
+
+routers:
+  - name: "router"
+    array: [4, 4]
+    degree: 5
+
+connections:
+  - src: "cluster"
+    dst: "router"
+    src_range:
+    - [0, 3]
+    - [0, 3]
+    dst_range:
+    - [0, 3]
+    - [0, 3]
+    dst_dir: "Eject"
+```

docs/getting_started.md

@@ -0,0 +1,93 @@
+# Getting Started
+
+## Prerequisites
+
+### Bender
+
+_FlooNoC_ uses [Bender](https://github.com/pulp-platform/bender) for hardware IPs and dependency management. Bender is available through Cargo or as pre-compiled binaries for Linux, macOS, and Windows:
+
+=== "Cargo"
+
+    ```bash
+    cargo install bender
+    ```
+
+=== "Precompiled"
+
+    ```bash
+    curl --proto '=https' --tlsv1.2 https://pulp-platform.github.io/bender/init -sSf | sh
+    ```
+
+Make sure that the Bender binary directory is in your `PATH`, or set the `BENDER` environment variable to the path of the Bender binary.
+
+### Python
+
+Some parts of _FlooNoC_ including the _FlooGen_ generator are written in Python. The required Python version is 3.10 or higher. You can install Python from the [official website](https://www.python.org/downloads/).
+
+### Simulation Tools
+
+Currently, we don't provide any open-source simulation setup such as Verilator. _FlooNoC_ was internally tested and verified with QuestaSim-2023.4. To run the RTL simulations you need to have QuestaSim installed. By default, _FlooNoC_ uses the `vsim` command to run the simulations, which can be overridden by setting the `VSIM` environment variable.
+
+## Installation
+
+Clone the repository from GitHub:
+
+```bash
+git clone https://github.com/pulp-platform/FlooNoC.git
+```
+Install the python dependencies and _FlooGen_:
+
+```bash
+pip install .
+```
+
+## Usage
+
+### Running the Testbenches
+
+Now you can compile and run the testbenches with the following command:
+
+```bash
+make compile-sim
+make run-sim VSIM_TB_DUT=tb_floo_dut
+```
+where you replace `tb_floo_dut` with the testbench that you want to simulate.
+
+### Generating a _FlooNoC_ Network
+
+To generate a _FlooNoC_ network using the _FlooGen_ generator, you can use the following command:
+
+```bash
+floogen -c examples/floo_dut.yaml -o generated
+```
+
+## Optional dependencies
+
+For the development on _FlooGen_, it is recommended to install the `dev` dependencies for python linting and testing:
+
+=== "bash"
+
+    ```bash
+    pip install .[dev]
+    ```
+
+=== "zsh"
+
+    ```zsh
+    pip install .\[dev\]
+
+    ```
+For documentation generation, you can install the `docs` dependencies:
+
+=== "bash"
+
+    ```bash
+    pip install .[docs]
+    ```
+
+=== "zsh"
+
+    ```zsh
+    pip install .\[docs\]
+
+    ```