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/getting_started.md

@@ -0,0 +1,94 @@
+# 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
+```
+
+### Generating a _FlooNoC_ Network
+
+where you replace `tb_floo_dut` with the testbench that you want to simulate.
+
+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\]
+
+    ```

docs/hw/chimneys.md

@@ -0,0 +1,47 @@
+# Network interfaces (a.k.a. chimneys)
+
+Network interfaces (NIs) are essentially the gateway to the Network-on-Chip (NoC). Every endpoint in the system requires its own NI to issue and receive packets over the NoC. The main purpose of the NI is to translate the on-chip protocol (e.g. AXI) to the link-level protocol of the network. NIs are not trivial to implement since they need to adhere to all the rules of the on-chip protocol e.g. ordering, flow control, etc. However, the advantage of using NIs is that the rest of the network can be agnostic to the on-chip protocol, which results in simpler router microarchitecture and as well as better scalability. Currently, _FlooNoC_ was mainly designed to support AXI4 and ships with dedicated NIs. However, it is possible to extend _FlooNoC_ also with other protocols, by implementing custom NIs.
+
+??? quote "Why chimneys?"
+    The name of _FlooNoC_ is derived from the Floo Network of Harry Potter. In the books, the Floo Network is a magical network of fireplaces that allows witches and wizards to travel from one place to another. Therefore, the chimneys are the gateways to the Floo Network, which is why they are called chimneys.
+
+## AXI Network Interface
+
+_FlooNoC_ ships with two different AXI NIs: the `axi_chimney` and the `nw_chimney`, which mainly differ from the ports and links that are connected to them. As the name implies, the `axi_chimney` has a single AXI port and uses only `req`/`rsp` physical channels, while the `nw_chimney` has a narrow *and* a wide AXI port and additionally features a `wide` physical channel. In the following, we will describe the inner workings of the `axi_chimney` in more detail. The `nw_chimney` is very similar, with largely duplicate datapaths for the narrow and wide ports.
+
+### Ordering
+
+One of the main challenges of implementing an NI for the AXI protocol is the strict ordering requirement that is imposed by AXI. The NI interface needs to be able to guarantee that for transactions with the same `txnID` all responses arrive with the same order as how the request were injected into the network. By design, the _FlooNoC_ link-level protocol does not guarantee ordering. For instance, if one request is sent to destination `A` and second request to destination `B`, the response from `B` can arrive before the response from `A`. There are essentially to ways of solving this problem: _Reordering_ or _stalling_.
+
+#### Reordering
+
+Responses that arrive out-of-order are buffered in a reorder buffer (RoB) until they can be delivered in-order. This approach is more performant, since multiple requests can be issued to different endpoints at the same time. However, a RoB is costly in terms of area and needs to be limited in size. Furthermore, the NI still needs to ensure that all responses from the NoC can be handled, either by buffering them in the RoB or forwarding them to the on-chip protocol (if they are in order). Stalling the network is not an option, as this would inevitably lead to deadlocks. Therefore, the NI also needs to track or allocate space in the RoB and only inject new requests into the network if it can guarantee that the responses can be handled:
+
+#### Stalling
+
+Another way to solve the ordering problem is to simply stall the injection of new requests into the network if the NI cannot guarantee that the responses will arrive in order. This approach is very simple to implement, and has a very small overhead, but it can lead to significant performance degredation in some cases. Luckily, there are some optimizations that the AXI NIs apply, which reduce the number of stalls. First, transactions to the same destination are always guaranteed to arrive in order (assuming a static routing algorithm is used in side the network). This means that the NI can inject multiple requests into the network, while the destination stays the same. Second, the ordering requirement only applies to transactions with the same `txnID`. Therefore, downstream components can also use different IDs to avoid ordering issues.
+
+The AXI NIs of _FlooNoC_ offers both options, and there are different implementations that can be set with the `ChimneyCfg.RoBType` parameter. The following table shows the different options:
+
+| RoBType | Description |
+|---------|-------------|
+| `NoRoB` | No RoB, which stalls transactions of the same `txnID` going to different destinations until the previous transaction is completed. This is option is useful if the ordering of transactions is handled downstream, e.g. in the DMA by issuing AXI transactions with different `txnIDs`. The overhead of this RoB is very low, since it only requires counters for tracking the number of outstanding transactions of each `txnID`.|
+| `NormalRoB` |  The most performant but also most complex RoB, which supports reodering of responses. This reorder buffer retains the out-of-order nature of AXI transactions with different IDs. Supports multiple outstanding transactions and bursts |
+| `SimpleRoB` | Simpler FIFO-like RoB, which does not support reordering of responses with the same AXI `txnID`. Transactions with different `txnIDs` are effectively serialized. Supports multiple outstanding transactions but currently does not support burst transactions. Mainly useful for B-responses which are single transactions. |
+
+The selection of the RoB type depends on the endpoints that are attached to it. For instance, cores with narrower AXI interfaces might are less costly to reorder with a RoB, while DMAs with wider interfaces and burst requests might be prohibitively expensive to reorder. `FlooNoC` gives the option to specify the RoB type and size in the `ChimneyCfg` parameter. In AXI, both read and write response exist, for which different RoBs can be selected. For instance, the `B` response is very small and the cost of reordering it is quite low, which might not be true for the `R` responses.
+
+### Routing
+
+Another task of the NI is also to create the header of the flit which contains all the information required to route a packet from source to destination. To do this, the NI needs to translate the request address to a destination ID, which can be done in two different ways:
+
+* Address Offset: The NI simply uses a fixed offset into the request address to determine the destination ID. For instance, assuming an node ID width of 3, and an address offset of 8, the address `0x0f00` would be translated to node ID `0x7`. This is the simplest way to route packets, but it is also the least flexible. For instance, if not all of the endpoints have the same address range size, a lot of address space might be wasted. For simpler systems, this might however be a good choice. The Address Offset method can be enabled by setting the `RouteCfg.IdAddrOffset`, respectively `RouteCfg.XYAddrOffsetX` and `RouteCfg.XYAddrOffsetX` in case of `XYRouting`.
+
+* Address Map: The other alternative is to use an address map to translate the request address to a node ID. This is usually in the form of a global System Address Map (SAM), which consists of a list of address ranges and the corresponding node IDs. To configure this, the `RouteCfg.UseIdTable` needs to be set and the System Address Map can be passed to the network interface with the `Sam` parameter (which also requires setting the `RouteCfg.NumSamRules` parameter).
+
+Source-based routing is handled a bit different, since the route instead of the destination ID needs to be included in the header. Calculating the route is done in two steps 1) the destination ID is computed the same way as for the node ID based routing and 2) the destination ID is used as an index into a routing table to determine the route. The routing table is passed to the network interface over the `route_table_i` port (which requires setting the `RouteCfg.NumRoutes` parameter).
+
+### AXI Transaction ID handling
+
+### Configuration
+* spill registers

docs/hw/commons.md

@@ -0,0 +1,3 @@
+# Common IPs
+
+*TODO*