From e16999945806ab34ff3ec9ab481abdd294f843c9 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:18:28 +0200 Subject: [PATCH 01/46] py: Add `docs` dependencies --- pyproject.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 0e4df9ff..13305d55 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,6 +31,11 @@ dependencies = [ "pygame" ] +[project.optional-dependencies] +docs = [ + "mkdocs", + "mkdocs-material" +] [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" From ecad55e4025620eea16726a50f94e7f73c589fe7 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:18:48 +0200 Subject: [PATCH 02/46] doc: Add initial doc flow --- .github/workflows/publish-docs.yml | 29 +++++++++++++++++++++++++++++ docs/gs.md | 3 +++ docs/index.md | 1 + mkdocs.yml | 25 +++++++++++++++++++++++++ 4 files changed, 58 insertions(+) create mode 100644 .github/workflows/publish-docs.yml create mode 100644 docs/gs.md create mode 120000 docs/index.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 00000000..19f671eb --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,29 @@ +# 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 + +name: publish-docs + +on: + push: + branches: [ main ] + workflow_dispatch: + +jobs: + + deploy: + runs-on: ubuntu-22.04 + steps: + - name: Checkout + uses: actions/checkout@v4 + - 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 diff --git a/docs/gs.md b/docs/gs.md new file mode 100644 index 00000000..65e07733 --- /dev/null +++ b/docs/gs.md @@ -0,0 +1,3 @@ +## I am just getting started + +Lorem ipsum dolor sit amet, consectetur adipiscing elit diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..7bef2ea9 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,25 @@ +# Copyright 2020 ETH Zurich and University of Bologna. +# Licensed under the Apache License, Version 2.0, see LICENSE for details. +# SPDX-License-Identifier: Apache-2.0 + +site_name: FlooNoC +theme: + name: material + icon: + repo: fontawesome/brands/github + features: + - navigation.expand + - navigation.tracking + - navigation.sections + - navigation.indexes + - navigation.footer + +repo_url: https://github.com/pulp-platform/FlooNoC +repo_name: pulp-platform/FlooNoC + +nav: +- Home: + - index.md + - Getting Started: gs.md +- FlooGen: + - floogen.md From ad57e135e91c0fa192ba39d8940f683537b35c8d Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:19:00 +0200 Subject: [PATCH 03/46] py: Remove unused dependencies --- pyproject.toml | 2 -- 1 file changed, 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 13305d55..9cd5a547 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,8 +23,6 @@ dependencies = [ "matplotlib", "mako", "ruamel.yaml", - "hjson", - "jsonref", "click", "pylint", "pytest", From e0758051633cd1b9e44f3a1b94f301e6614c2c79 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:19:10 +0200 Subject: [PATCH 04/46] py: Add `dev` dependencies --- pyproject.toml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 9cd5a547..9a74a838 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,6 +34,12 @@ docs = [ "mkdocs", "mkdocs-material" ] +dev = [ + "black", + "pylint", + "pytest" +] + [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" From 120e41d999ab87fd4672529e3054092e9d690033 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:22:13 +0200 Subject: [PATCH 05/46] REVERT: publish on feature branch --- .github/workflows/publish-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 19f671eb..97edb592 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -7,8 +7,8 @@ name: publish-docs on: - push: - branches: [ main ] + # push: + # branches: [ main ] workflow_dispatch: jobs: From fe5867551a29653ce3bd740add9e1f0cb47303fb Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Fri, 6 Sep 2024 22:23:02 +0200 Subject: [PATCH 06/46] ci: Correct python version --- .github/workflows/publish-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 97edb592..b28df1bc 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -21,7 +21,7 @@ jobs: - name: Install Python uses: actions/setup-python@v5 with: - python-version: 3.10 + python-version: '3.10' cache: pip - name: Install Python requirements run: pip install .[docs] From 102b878d04690970dfc5ec63a4fd36764faff88c Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 18:11:42 +0200 Subject: [PATCH 07/46] gh-pages: Try with lower case URL --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 7bef2ea9..6b578f74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,7 +14,7 @@ theme: - navigation.indexes - navigation.footer -repo_url: https://github.com/pulp-platform/FlooNoC +repo_url: https://github.com/pulp-platform/floo_noc repo_name: pulp-platform/FlooNoC nav: From 33175a1d69b70af8fff54cb934b795480824a64d Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 19:24:42 +0200 Subject: [PATCH 08/46] Revert "gh-pages: Try with lower case URL" This reverts commit 632d2eb23972acb4bbdd0620cd7d4247b964e25a. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6b578f74..7bef2ea9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,7 +14,7 @@ theme: - navigation.indexes - navigation.footer -repo_url: https://github.com/pulp-platform/floo_noc +repo_url: https://github.com/pulp-platform/FlooNoC repo_name: pulp-platform/FlooNoC nav: From fcd23ffa5ca1c5fa86f15b191e369bddfd922edf Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 20:28:39 +0200 Subject: [PATCH 09/46] docs: Rename `gs.md` to `getting_started.md` --- docs/{gs.md => getting_started.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{gs.md => getting_started.md} (100%) diff --git a/docs/gs.md b/docs/getting_started.md similarity index 100% rename from docs/gs.md rename to docs/getting_started.md From b3baf49e0e4c7e7c10785858b2e611fa9b686b98 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 20:29:04 +0200 Subject: [PATCH 10/46] docs: Update README --- README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3f671898..f83e54fa 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Logo -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.
@@ -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 From 13d4551e438a919d8aaf3319cbb6881805e0429f Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 20:39:33 +0200 Subject: [PATCH 11/46] docs: Initial `index.md` file --- docs/index.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) mode change 120000 => 100644 docs/index.md diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..cef38fc3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +# FlooNoC: A Fast, Low-Overhead On-chip Network + +_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. + +## Getting Started + +Check out our getting started [guide](https://pulp-platform.github.io/FlooNoC/getting_started/) + +## Directory structure + +- `docs`: Contains the documentation of the project +- `hw`: Contains all SystemVerilog files for the hardware implementation + - `test`: Contains verification IPs (VIPs) for testing + - `tb`: Contains testbenches for module verification + - `include`: Contains macros for _FlooNoC_ typedefs +- `floogen`: Contains the _FlooGen_ network generation framework + - `examples`: Contains example network configurations + - `model`: Contains the _FlooGen_ models for the network components such as network interfaces, routers and endpoints. + - `tempaltes`: Contains the `mako` templates to render the SV components + - `test`: Contains tests for the _FlooGen_ framework From f1b5d44778590d60032066484493aaf28b5da2c0 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 20:53:20 +0200 Subject: [PATCH 12/46] docs: Add repository structure --- docs/index.md | 13 ------------- docs/repository_structure.md | 23 +++++++++++++++++++++++ mkdocs.yml | 3 ++- 3 files changed, 25 insertions(+), 14 deletions(-) create mode 100644 docs/repository_structure.md diff --git a/docs/index.md b/docs/index.md index cef38fc3..0027c56d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,16 +5,3 @@ _FlooNoC_, is a Network-on-Chip (NoC) research project, which is part of the [PU ## Getting Started Check out our getting started [guide](https://pulp-platform.github.io/FlooNoC/getting_started/) - -## Directory structure - -- `docs`: Contains the documentation of the project -- `hw`: Contains all SystemVerilog files for the hardware implementation - - `test`: Contains verification IPs (VIPs) for testing - - `tb`: Contains testbenches for module verification - - `include`: Contains macros for _FlooNoC_ typedefs -- `floogen`: Contains the _FlooGen_ network generation framework - - `examples`: Contains example network configurations - - `model`: Contains the _FlooGen_ models for the network components such as network interfaces, routers and endpoints. - - `tempaltes`: Contains the `mako` templates to render the SV components - - `test`: Contains tests for the _FlooGen_ framework diff --git a/docs/repository_structure.md b/docs/repository_structure.md new file mode 100644 index 00000000..6de42ace --- /dev/null +++ b/docs/repository_structure.md @@ -0,0 +1,23 @@ +# Repository Structure and Contents + +This document describes the structure of the repository and the contents of the directories. + +## The `hw` hardware directory + +The `hw` directory contains all the hardware-related files for all the SystemVerilog IPs. The directory is structured as follows: + +- `*.sv`: SystemVerilog packages and modules for the IPs. +- `test`: Verification IPs (VIPs) such as monitors, random initiators for the testbenches. +- `tb`: Testbenches for the IPs. + +## The `floogen` _FlooGen_ directory + +The `floogen` directory contains the Python framework for _FlooGen_ to generate complete _FlooNoC_ networks based on a simple configuration file. The directory is structured as follows: + +- `examples`: A couple of example configuration files. +- `model`: The python models for routers, network interfaces and endpoints that are used by _FlooGen_. +- `templates`: Mako templates for the generation of the SystemVerilog files. +- `tests`: Unit tests for the _FlooGen_ framework. +- `floo_gen.py`: The main script for _FlooGen_. +- `config_parser.py`: The configuration parser for _FlooGen_. +- `utils.py`: Various utility functions for _FlooGen_. diff --git a/mkdocs.yml b/mkdocs.yml index 7bef2ea9..c9a6f1e3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,6 +20,7 @@ repo_name: pulp-platform/FlooNoC nav: - Home: - index.md - - Getting Started: gs.md + - Getting Started: getting_started.md + - Repository Structure: repository_structure.md - FlooGen: - floogen.md From fd1f5376580038493bab59b622177f13eb57eebe Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 21:06:27 +0200 Subject: [PATCH 13/46] docs: Initial `docs` directory structure --- docs/floogen/cli.md | 0 docs/floogen/connections.md | 0 docs/floogen/endpoints.md | 0 docs/floogen/known_issues.md | 0 docs/floogen/overview.md | 0 docs/floogen/protocols.md | 0 docs/floogen/routers.md | 0 docs/floogen/routing.md | 0 docs/hw/chimneys.md | 3 +++ docs/hw/common.md | 3 +++ docs/hw/links.md | 3 +++ docs/hw/overview.md | 3 +++ docs/hw/router.md | 3 +++ docs/hw/vips.md | 3 +++ mkdocs.yml | 16 +++++++++++++++- 15 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 docs/floogen/cli.md create mode 100644 docs/floogen/connections.md create mode 100644 docs/floogen/endpoints.md create mode 100644 docs/floogen/known_issues.md create mode 100644 docs/floogen/overview.md create mode 100644 docs/floogen/protocols.md create mode 100644 docs/floogen/routers.md create mode 100644 docs/floogen/routing.md create mode 100644 docs/hw/chimneys.md create mode 100644 docs/hw/common.md create mode 100644 docs/hw/links.md create mode 100644 docs/hw/overview.md create mode 100644 docs/hw/router.md create mode 100644 docs/hw/vips.md diff --git a/docs/floogen/cli.md b/docs/floogen/cli.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/connections.md b/docs/floogen/connections.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/endpoints.md b/docs/floogen/endpoints.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/known_issues.md b/docs/floogen/known_issues.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/overview.md b/docs/floogen/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/protocols.md b/docs/floogen/protocols.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/routers.md b/docs/floogen/routers.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/floogen/routing.md b/docs/floogen/routing.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/hw/chimneys.md b/docs/hw/chimneys.md new file mode 100644 index 00000000..d71478be --- /dev/null +++ b/docs/hw/chimneys.md @@ -0,0 +1,3 @@ +# Network interfaces (a.k.a. chimneys) + +*TODO* diff --git a/docs/hw/common.md b/docs/hw/common.md new file mode 100644 index 00000000..5d110782 --- /dev/null +++ b/docs/hw/common.md @@ -0,0 +1,3 @@ +# Common IPs + +*TODO* diff --git a/docs/hw/links.md b/docs/hw/links.md new file mode 100644 index 00000000..19c67392 --- /dev/null +++ b/docs/hw/links.md @@ -0,0 +1,3 @@ +# Link-level protocol + +*TODO* diff --git a/docs/hw/overview.md b/docs/hw/overview.md new file mode 100644 index 00000000..299ac497 --- /dev/null +++ b/docs/hw/overview.md @@ -0,0 +1,3 @@ +# Overview of the Hardware Components + +*TODO* diff --git a/docs/hw/router.md b/docs/hw/router.md new file mode 100644 index 00000000..ff4f3e83 --- /dev/null +++ b/docs/hw/router.md @@ -0,0 +1,3 @@ +# Routers + +*TODO* diff --git a/docs/hw/vips.md b/docs/hw/vips.md new file mode 100644 index 00000000..ced2cfd7 --- /dev/null +++ b/docs/hw/vips.md @@ -0,0 +1,3 @@ +# Verification IPs (VIPs) of _FlooNoC_ + +*TODO* diff --git a/mkdocs.yml b/mkdocs.yml index c9a6f1e3..fa29866e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,5 +22,19 @@ nav: - index.md - Getting Started: getting_started.md - Repository Structure: repository_structure.md +- Hardware IPs: + - Overview: hw/overview.md + - Links: hw/links.md + - Router: hw/router.md + - Network Interfaces: hw/chimneys.md + - Common IPs: hw/common.md + - Verification IPs: hw/vips.md - FlooGen: - - floogen.md + - Overview: floogen/overview.md + - Routing: floogen/routing.md + - Protocols: floogen/protocols.md + - Endpoints: floogen/endpoints.md + - Routers: floogen/routers.md + - Connections: floogen/connections.md + - CLI: floogen/cli.md + - Known Issues: floogen/known_issues.md From a1fb98b4303a436c33a153588f2ee3818d56a3d5 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:26:06 +0200 Subject: [PATCH 14/46] docs: Add custom color and stylesheet --- docs/stylesheets/extra.css | 5 +++++ mkdocs.yml | 29 +++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 docs/stylesheets/extra.css diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..73db8469 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,5 @@ +:root { + --md-primary-fg-color: #02793C; + --md-primary-fg-color--light: #21B42A; + --md-primary-fg-color--dark: #05422B; +} diff --git a/mkdocs.yml b/mkdocs.yml index fa29866e..732bfbea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,8 +3,37 @@ # SPDX-License-Identifier: Apache-2.0 site_name: FlooNoC + +extra_css: + - stylesheets/extra.css + theme: name: material + palette: + + # Default palette + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - scheme: default + media: "(prefers-color-scheme: light)" + primary: custom + accent: light green + toggle: + icon: material/weather-sunny + name: Switch to dark mode + + # Palette toggle for dark mode + - scheme: slate + media: "(prefers-color-scheme: dark)" + primary: custom + accent: light green + toggle: + icon: material/weather-night + name: Switch to light mode icon: repo: fontawesome/brands/github features: From 51b999d27e27d1f629a2995245ddfe48f2ed4077 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:26:26 +0200 Subject: [PATCH 15/46] docs: Use custom logo and favicon --- docs/img/floo_noc_favicon_logo.png | Bin 0 -> 17608 bytes docs/img/floo_noc_favicon_logo.svg | 102 ++++++++++++++++++++++++++++ docs/img/floo_noc_material_logo.png | Bin 0 -> 13061 bytes docs/img/floo_noc_material_logo.svg | 98 ++++++++++++++++++++++++++ mkdocs.yml | 2 + 5 files changed, 202 insertions(+) create mode 100644 docs/img/floo_noc_favicon_logo.png create mode 100644 docs/img/floo_noc_favicon_logo.svg create mode 100644 docs/img/floo_noc_material_logo.png create mode 100644 docs/img/floo_noc_material_logo.svg diff --git a/docs/img/floo_noc_favicon_logo.png b/docs/img/floo_noc_favicon_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..be19c4552f87150692bceb8a73417c023d48e7fa GIT binary patch literal 17608 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 literal 0 HcmV?d00001 diff --git a/docs/img/floo_noc_favicon_logo.svg b/docs/img/floo_noc_favicon_logo.svg new file mode 100644 index 00000000..23a7eb85 --- /dev/null +++ b/docs/img/floo_noc_favicon_logo.svg @@ -0,0 +1,102 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/docs/img/floo_noc_material_logo.png b/docs/img/floo_noc_material_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..85b0c540b9d084abd57306a985feacd15719bb15 GIT binary patch literal 13061 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 m@5f$Uh-b)XRHg4&%4&RE^N@aN1pW&PjA-X + + + + + + + + + + + + + + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index 732bfbea..67e6ec01 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,8 @@ extra_css: - stylesheets/extra.css theme: + logo: img/floo_noc_material_logo.png + favicon: img/floo_noc_favicon_logo.png name: material palette: From 1789fb793ab3fed838bc99381ad506eb923b7c66 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:26:38 +0200 Subject: [PATCH 16/46] docs: Use sticky tabs --- mkdocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 67e6ec01..95692bf7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,6 +40,8 @@ theme: repo: fontawesome/brands/github features: - navigation.expand + - navigation.tabs + - navigation.tabs.sticky - navigation.tracking - navigation.sections - navigation.indexes From ff180af4ef5c8bbbb27c9e6d0ccb92dbaa277e28 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:26:46 +0200 Subject: [PATCH 17/46] docs: Use instant navigation --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 95692bf7..6ab5753d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ theme: - navigation.expand - navigation.tabs - navigation.tabs.sticky + - navigation.instant - navigation.tracking - navigation.sections - navigation.indexes From 8bb6b1cc9544a3aff50c3c844bfe3883da8d9074 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:26:58 +0200 Subject: [PATCH 18/46] docs: Remove unused options --- mkdocs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6ab5753d..c34c0e54 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,12 +39,10 @@ theme: icon: repo: fontawesome/brands/github features: - - navigation.expand - navigation.tabs - navigation.tabs.sticky - navigation.instant - navigation.tracking - - navigation.sections - navigation.indexes - navigation.footer From aedadfece613eef00a163e6c02ae6a3053ab383b Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:27:22 +0200 Subject: [PATCH 19/46] docs: Make dedicated "Getting Started" tab --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c34c0e54..5c5a08e6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,8 +52,8 @@ repo_name: pulp-platform/FlooNoC nav: - Home: - index.md - - Getting Started: getting_started.md - Repository Structure: repository_structure.md +- Getting Started: getting_started.md - Hardware IPs: - Overview: hw/overview.md - Links: hw/links.md From cea5683df897ea2e1287181a560940e11d5e1eb2 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:27:35 +0200 Subject: [PATCH 20/46] docs: Add Changelog --- docs/changelog.md | 1 + mkdocs.yml | 1 + 2 files changed, 2 insertions(+) create mode 120000 docs/changelog.md diff --git a/docs/changelog.md b/docs/changelog.md new file mode 120000 index 00000000..04c99a55 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5c5a08e6..d2b36bea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,3 +70,4 @@ nav: - Connections: floogen/connections.md - CLI: floogen/cli.md - Known Issues: floogen/known_issues.md +- Changelog: changelog.md From 02817f5a6137a41734dca9dc1d8db0ca09b1e86b Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 22:36:27 +0200 Subject: [PATCH 21/46] docs: Try the `social` plugin --- mkdocs.yml | 3 +++ pyproject.toml | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index d2b36bea..b5ae6203 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,9 @@ theme: repo_url: https://github.com/pulp-platform/FlooNoC repo_name: pulp-platform/FlooNoC +plugins: + - social: + cards_layout: default nav: - Home: - index.md diff --git a/pyproject.toml b/pyproject.toml index 9a74a838..996b670c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,7 +32,9 @@ dependencies = [ [project.optional-dependencies] docs = [ "mkdocs", - "mkdocs-material" + "mkdocs-material", + "pillow", + "cairosvg" ] dev = [ "black", From 31a3672df385c4fc5d2eeaa5c487a9a5c60f3150 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 23:11:09 +0200 Subject: [PATCH 22/46] docs: Show revision date and authors --- mkdocs.yml | 5 +++++ pyproject.toml | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index b5ae6203..59b6c9de 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,11 @@ repo_name: pulp-platform/FlooNoC plugins: - social: cards_layout: default + - git-revision-date-localized: + enable_creation_date: true + - git-committers: + repository: pulp-platform/FlooNoC + branch: main nav: - Home: - index.md diff --git a/pyproject.toml b/pyproject.toml index 996b670c..9b901609 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,7 +34,9 @@ docs = [ "mkdocs", "mkdocs-material", "pillow", - "cairosvg" + "cairosvg", + "mkdocs-git-revision-date-localized-plugin", + "mkdocs-git-committers-plugin-2" ] dev = [ "black", From 536dcf70cb1cf7df8f104ca1facba278211c7cd7 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 23:14:44 +0200 Subject: [PATCH 23/46] docs: Add `site_url` --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 59b6c9de..bb7cb910 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,7 @@ theme: repo_url: https://github.com/pulp-platform/FlooNoC repo_name: pulp-platform/FlooNoC +site_url: https://pulp-platform.github.io/FlooNoC plugins: - social: From 6bba75a944cfab1f0fb1387f6a213299f2b86ad6 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 23:16:24 +0200 Subject: [PATCH 24/46] docs: Remove unused config --- mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index bb7cb910..9c763ff6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,7 +52,6 @@ site_url: https://pulp-platform.github.io/FlooNoC plugins: - social: - cards_layout: default - git-revision-date-localized: enable_creation_date: true - git-committers: From a416fe0e38b3a9e09d0983a09c733896a376051a Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 23:19:16 +0200 Subject: [PATCH 25/46] docs: Fetch entire history --- .github/workflows/publish-docs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index b28df1bc..7db9483c 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -18,6 +18,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + with: + fetch-depth: 0 - name: Install Python uses: actions/setup-python@v5 with: From 1f9912c44320f9a8af0fd0950bcc00c361130237 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 9 Sep 2024 23:29:10 +0200 Subject: [PATCH 26/46] docs: Make license linter happy --- docs/stylesheets/extra.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 73db8469..2ea440b2 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,3 +1,7 @@ +/* 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 */ + :root { --md-primary-fg-color: #02793C; --md-primary-fg-color--light: #21B42A; From 071bfa351f7ab1f185798ae1a10cc24cee5c353f Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Tue, 10 Sep 2024 18:11:49 +0200 Subject: [PATCH 27/46] docs: Update getting started guide --- docs/getting_started.md | 65 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 65e07733..30f003a8 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,3 +1,64 @@ -## I am just getting started +# Getting Started -Lorem ipsum dolor sit amet, consectetur adipiscing elit +## 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 + +_FlooGen_ is a python framework that requires Python 3.10 or later. _FlooGen_ and its dependencies can be installed using pip: + +```bash +pip install . +``` + +### 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. + +### Optional dependencies + +For the development with _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\] + + ``` From 227278d9b0550ad9e6bcef070c901ebf21bd0033 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Tue, 10 Sep 2024 18:12:03 +0200 Subject: [PATCH 28/46] docs: Don't use code commiters plugin anymore --- mkdocs.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 9c763ff6..88dc3379 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,9 +54,6 @@ plugins: - social: - git-revision-date-localized: enable_creation_date: true - - git-committers: - repository: pulp-platform/FlooNoC - branch: main nav: - Home: - index.md From 9882dd9e24972c52a53121fa5c36b80ca1802521 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Tue, 10 Sep 2024 18:12:18 +0200 Subject: [PATCH 29/46] docs: Use tabbed for code --- mkdocs.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 88dc3379..cd5243da 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ theme: - navigation.tracking - navigation.indexes - navigation.footer + - content.code.copy repo_url: https://github.com/pulp-platform/FlooNoC repo_name: pulp-platform/FlooNoC @@ -54,6 +55,12 @@ plugins: - social: - git-revision-date-localized: enable_creation_date: true + +markdown_extensions: + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + nav: - Home: - index.md From 8fb0e4c3c3c46a3f8f80d55cc1160e8bcc5cb00d Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Tue, 10 Sep 2024 18:12:32 +0200 Subject: [PATCH 30/46] make: Use `vsim` executable by default --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 74ae93fa..df5061dd 100644 --- a/Makefile +++ b/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 From 67f4eb87f3ea7906157c6d8454e7bc8fe9342c0f Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Sep 2024 08:48:17 +0200 Subject: [PATCH 31/46] docs: Update getting started --- docs/getting_started.md | 40 +++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 30f003a8..8b1155c7 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -22,19 +22,49 @@ Make sure that the Bender binary directory is in your `PATH`, or set the `BENDER ### Python -_FlooGen_ is a python framework that requires Python 3.10 or later. _FlooGen_ and its dependencies can be installed using pip: +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 . ``` -### Tools +## Usage -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. +### 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 +## Optional dependencies -For the development with _FlooGen_, it is recommended to install the `dev` dependencies for python linting and testing: +For the development on _FlooGen_, it is recommended to install the `dev` dependencies for python linting and testing: === "bash" From 567cb8575e03312fc272a0d7baab5875d4af3f3d Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Sep 2024 18:23:31 +0200 Subject: [PATCH 32/46] docs: Add quick links to Home --- docs/Apache-License.md | 1 + docs/SHL-License.md | 1 + docs/index.md | 54 ++++++++++++++++++++++++++++++++++++++++-- docs/license.md | 3 +++ mkdocs.yml | 9 ++++++- 5 files changed, 65 insertions(+), 3 deletions(-) create mode 120000 docs/Apache-License.md create mode 120000 docs/SHL-License.md create mode 100644 docs/license.md diff --git a/docs/Apache-License.md b/docs/Apache-License.md new file mode 120000 index 00000000..965b606f --- /dev/null +++ b/docs/Apache-License.md @@ -0,0 +1 @@ +../LICENSE-APACHE \ No newline at end of file diff --git a/docs/SHL-License.md b/docs/SHL-License.md new file mode 120000 index 00000000..db811d44 --- /dev/null +++ b/docs/SHL-License.md @@ -0,0 +1 @@ +../LICENSE-SHL \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 0027c56d..433e4587 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,56 @@ _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. -## Getting Started +## Quick Links -Check out our getting started [guide](https://pulp-platform.github.io/FlooNoC/getting_started/) +
+ +- :material-fast-forward:{ .lg .middle } __Setup & Installation__ + + --- + + Install Bender for HW IPs and python dependencies for _FlooGen_ + + [:octicons-arrow-right-24: Getting started](getting_started.md) + +- :fontawesome-solid-microchip:{ .lg .middle } __Hardware IPs__ + + --- + + Check out the documentation of _FlooNoC_ hardware IPs. + + [:octicons-arrow-right-24: Hardware IPs](hw/overview.md) + +- :material-magic-staff:{ .lg .middle } __Network Generation__ + + --- + + Learn how to generate a _FlooNoC_ network using _FlooGen_ + + [:octicons-arrow-right-24: FlooGen](floogen/overview.md) + +- :material-scale-balance:{ .lg .middle } __Open Source, MIT__ + + --- + + _FlooNoC_ is available open-source on [GitHub](https://github.com/pulp-platform/FlooNoC) under permissive licenses. + + [:octicons-arrow-right-24: License](license.md) + +- :material-bookshelf:{ .lg .middle } __Publication__ + + --- + + Read the publication of _FlooNoC_. + + [:octicons-arrow-right-24: Publication](https://arxiv.org/abs/2305.08562) + +- :material-file-document:{ .lg .middle } __Changelog__ + + --- + + Check out what has changed in the latest version of _FlooNoC_. + + [:octicons-arrow-right-24: Changelog](changelog.md) + +
diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..6ef3f5a9 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,3 @@ +# License + +All code checked into this repository is made available under a permissive license. All software sources of _FlooGen_ under `floogen` are licensed under the [Apache License 2.0](Apache-License.md), and all hardware sources in the `hw` folder are licensed under the [Solderpad Hardware License 0.51](SHL-License.md). diff --git a/mkdocs.yml b/mkdocs.yml index cd5243da..ff91d92f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,11 +60,18 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tabbed: alternate_style: true + - attr_list + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - md_in_html nav: - Home: - index.md - Repository Structure: repository_structure.md + - License: license.md + - Contributing: contributing.md - Getting Started: getting_started.md - Hardware IPs: - Overview: hw/overview.md @@ -75,7 +82,7 @@ nav: - Verification IPs: hw/vips.md - FlooGen: - Overview: floogen/overview.md - - Routing: floogen/routing.md + - Routing & Topologies: floogen/routing.md - Protocols: floogen/protocols.md - Endpoints: floogen/endpoints.md - Routers: floogen/routers.md From df6f297b7319802399d023d5f9ea0a36d0ee18a5 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Sep 2024 21:23:57 +0200 Subject: [PATCH 33/46] docs(theme): Don't use automatic dark/lite theme --- mkdocs.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index ff91d92f..168463a8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,12 +13,6 @@ theme: name: material palette: - # Default palette - - media: "(prefers-color-scheme)" - toggle: - icon: material/brightness-auto - name: Switch to light mode - # Palette toggle for light mode - scheme: default media: "(prefers-color-scheme: light)" From 3eecf2075613791f89150febb4e16d51f62fbc0a Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Sep 2024 21:53:37 +0200 Subject: [PATCH 34/46] docs(hw): Extend structure --- docs/hw/{common.md => commons.md} | 0 docs/hw/route_algos.md | 1 + docs/hw/{router.md => routers.md} | 0 docs/hw/tips.md | 1 + mkdocs.yml | 6 ++++-- 5 files changed, 6 insertions(+), 2 deletions(-) rename docs/hw/{common.md => commons.md} (100%) create mode 100644 docs/hw/route_algos.md rename docs/hw/{router.md => routers.md} (100%) create mode 100644 docs/hw/tips.md diff --git a/docs/hw/common.md b/docs/hw/commons.md similarity index 100% rename from docs/hw/common.md rename to docs/hw/commons.md diff --git a/docs/hw/route_algos.md b/docs/hw/route_algos.md new file mode 100644 index 00000000..8bc2f4de --- /dev/null +++ b/docs/hw/route_algos.md @@ -0,0 +1 @@ +# Routing Algorithms diff --git a/docs/hw/router.md b/docs/hw/routers.md similarity index 100% rename from docs/hw/router.md rename to docs/hw/routers.md diff --git a/docs/hw/tips.md b/docs/hw/tips.md new file mode 100644 index 00000000..a0c1a693 --- /dev/null +++ b/docs/hw/tips.md @@ -0,0 +1 @@ +# Tips & Tricks diff --git a/mkdocs.yml b/mkdocs.yml index 168463a8..9d21da61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,10 +70,12 @@ nav: - Hardware IPs: - Overview: hw/overview.md - Links: hw/links.md - - Router: hw/router.md + - Routing Algorithms: hw/route_algos.md - Network Interfaces: hw/chimneys.md - - Common IPs: hw/common.md + - Router: hw/routers.md + - Common IPs: hw/commons.md - Verification IPs: hw/vips.md + - Tips & Tricks: hw/tips.md - FlooGen: - Overview: floogen/overview.md - Routing & Topologies: floogen/routing.md From d0e556ff21142188f5fd165e7d32fbfbd6db956a Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 11 Sep 2024 21:53:47 +0200 Subject: [PATCH 35/46] docs(hw): Add overview --- docs/hw/overview.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/hw/overview.md b/docs/hw/overview.md index 299ac497..85544bc3 100644 --- a/docs/hw/overview.md +++ b/docs/hw/overview.md @@ -1,3 +1,19 @@ -# Overview of the Hardware Components +# Overview of the Hardware IPs -*TODO* +_FlooNoC_ is a collection of Network-on-Chip (NoC) IPs written in SystemVerilog that can used to assemble an NoC. In system architecture, there are a myriad of different considerations that go into the implementation of the on-chip network. From the topology of the network, the routing algorithm, flow-control, the use of virtual or physical channels, etc. This is why our goal was to make the _FlooNoC_ IPs as modular, configurable and extendible as possible, so that they can be easily integrated into any system. + +However, this also means that the hardware IPs are heavily parametrizable and the user has to make a lot of decisions when configuring the _FlooNoC_ IPs. This is what this documentation aims to help with. It will guide through all the available IPs, explain their architecture, and show how they need to be configured and what the trade-offs are. The documentation is structured as follows: + +1. **[Links](links.md)**: This section will explain the custom link-level protocol, which is used to connect the routers and network interfaces in the NoC. + +1. **[Routing Algorithms](route_algos.md)**: This section will explain the different routing algorithms that are available in _FlooNoC_ and how they can be configured. + +1. **[Network Interfaces](chimneys.md)**: This section will explain the different network interfaces which are used to convert to the custom link-level protocol of _FlooNoC_. + +1. **[Routers](routers.md)**: This section will explain the routers routers that are available in _FlooNoC_ and how they can be configured. + +1. **[Common IPs](commons.md)**: Apart from the two essential IPs, routers and network interfaces, there are also some common IPs that can be used to extend the functionality of the NoC. This section will explain these IPs. + +1. **[Verification IPs](vips.md)**: This section will explain the verification IPs that are available in _FlooNoC_ and how they can be used to verify the NoC. + +1. **[Tips & Tricks](tips.md)**: This section will give some tips and tricks on how to use the _FlooNoC_ IPs. From beefa63918310c8fa47c43c044d1ba6d15ba4089 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Thu, 12 Sep 2024 08:30:29 +0200 Subject: [PATCH 36/46] docs(hw): Start with link documentation --- docs/hw/links.md | 28 ++++++++++++++++++++++++++-- mkdocs.yml | 2 ++ 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/hw/links.md b/docs/hw/links.md index 19c67392..d5cb8999 100644 --- a/docs/hw/links.md +++ b/docs/hw/links.md @@ -1,3 +1,27 @@ -# Link-level protocol +# Link-Level transport -*TODO* +## Flits + +We start with the _flits_, also called flow control units, which is the smallest unit of data that is sent from node to another (e.g. from router to router, of network interface to router). Flits consists of two types of data: + +1. **Routing information**: Also called the header of the flit, this data is used by the routers to route the flit through the network. The header contains information such as the destination address, the source address, the flit type, etc. + +1. **Payload**: This is the actual data that is being sent from one node to another. Router do not look at the payload, they just forward it to the next hop. + +In traditional NoCs, the links have a fixed width (e.g. 32-bit). Usually, the payload and the information required for routing far exceeds this width. Therefore, the payload is split into multiple data flits and a header flit which encodes the routing information. Based on this information, routers in the network then know how to route the following data flits to the destination. + +In modern NoCs, this way of serializing payloads over the network is not very efficient anymore. With higher bandwidth requirements of the endpoints, the serialization becomes more and more a bottleneck, since the frequency of the links is limited. Further, serialization causes additional latency which is undesirable. Lastly, the overhead of the header flits is not negligible, especially when the payload is small. + +Therefore, In _FlooNoC_ and modern NoCs in general, another approach is taken, which differs in two ways: + +1. **Flit width**: The width of the flits is not fixed anymore. Instead, the flits can be as wide as the payload to send the payload in a single cycle resp. in a single flit. + +1. **Parallel header**: Instead of sending the header before the payload, the header is sent in parallel to the payload. This way, the link utilization is not degraded by header flits. + +!!! info "AMBA CHI" + + _FlooNoC_ is not the first NoC to use this approach. For example, the [AMBA CHI](https://developer.arm.com/documentation/ihi0050/latest/) protocol also encodes the entire payload (cachelines in this case) in a single flit including all the information required for routing. + +!!! tip "Wires are cheap now" + + You might wonder why this was not used in the first place. The reason is that wires were not as cheap as they are today. Modern technologies now have >10 metal layers which can fit >10000 wires/mm. A very good source on this topic, which has also influenced the design of _FlooNoC_ is the NOCS keynote [Reflections on 21 Years of NoCS](https://www.youtube.com/watch?v=Nk3oQm9NxcY) from Bill Dally, one of the pioneers in early NoC research. diff --git a/mkdocs.yml b/mkdocs.yml index 9d21da61..2c66c76e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,6 +59,8 @@ markdown_extensions: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - md_in_html + - admonition + - pymdownx.details nav: - Home: From 7762d5c83073c5979355005d614d104f8e60dafe Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 14 Sep 2024 21:42:59 +0200 Subject: [PATCH 37/46] docs(gs): Fix license box --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 433e4587..986fd92c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ _FlooNoC_, is a Network-on-Chip (NoC) research project, which is part of the [PU [:octicons-arrow-right-24: FlooGen](floogen/overview.md) -- :material-scale-balance:{ .lg .middle } __Open Source, MIT__ +- :material-scale-balance:{ .lg .middle } __License__ --- From e1b90fc7c36edcef8c5d3c26c80476ff68564ef4 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 14 Sep 2024 21:43:36 +0200 Subject: [PATCH 38/46] docs(hw): Rename to flits and add link page --- docs/hw/flits.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/hw/links.md | 28 +------------------ mkdocs.yml | 15 ++++++---- 3 files changed, 83 insertions(+), 33 deletions(-) create mode 100644 docs/hw/flits.md diff --git a/docs/hw/flits.md b/docs/hw/flits.md new file mode 100644 index 00000000..7633f3ed --- /dev/null +++ b/docs/hw/flits.md @@ -0,0 +1,73 @@ +# Flits + +We start with the _flits_, also called flow control units, which is the smallest unit of data that is sent from node to another (e.g. from router to router, of network interface to router). Flits consists of two types of data: + +1. **Routing information**: Also called the header of the flit, this data is used by the routers to route the flit through the network. The header contains information such as the destination address, the source address, the flit type, etc. + +1. **Payload**: This is the actual data that is being sent from one node to another. Router do not look at the payload, they just forward it to the next hop. + +In traditional NoCs, the links have a fixed width (e.g. 32-bit). Usually, the payload and the information required for routing far exceeds this width. Therefore, the payload is split into multiple data flits and a header flit which encodes the routing information. Based on this information, routers in the network then know how to route the following data flits to the destination. + +In modern NoCs, this way of serializing payloads over the network is not very efficient anymore. With higher bandwidth requirements of the endpoints, the serialization becomes more and more a bottleneck, since the frequency of the links is limited. Further, serialization causes additional latency which is undesirable. Lastly, the overhead of the header flits is not negligible, especially when the payload is small. + +Therefore, In _FlooNoC_ and modern NoCs in general[^1], another approach is taken, which differs in two ways: + +[^1]: The [AMBA CHI](https://developer.arm.com/documentation/ihi0050/latest/) protocol also encodes the entire payload (cachelines in this case) in a single flit including all the information required for routing. + +1. **Flit width**: The width of the flits is not fixed anymore. Instead, the flits can be as wide as the payload to send the payload in a single cycle resp. in a single flit. + +1. **Parallel header**: Instead of sending the header before the payload, the header is sent in parallel to the payload. This way, the link utilization is not degraded by header flits. + +!!! tip "Wires are cheap now" + + You might wonder why this was not used in the first place. The reason is that wires were not as cheap as they are today. Modern technologies now have >10 metal layers which can fit >10000 wires/mm. A very good source on this topic, which has also influenced the design of _FlooNoC_ is the NOCS keynote [Reflections on 21 Years of NoCS](https://www.youtube.com/watch?v=Nk3oQm9NxcY) from Bill Dally, one of the pioneers in early NoC research. + +Below, we will discuss the header and the payload in more detail. + +## Header + +In _FlooNoC_ the header consists of the following fields: + +| Field | Type | Required by | Description | +| ----------- | --------------- | ---------- | --------------------- | +| `dst_id` | `dst_t` or `route_t` | Router | The destination ID of the flit. In the case of source-based routing, it encodes the entire route from source to destination. | +| `src_id` | `dst_t` | Chimney | The source ID of the flit. Used by the Chimney to set the `dst_id` for the response | +| `last` | `logic` | Router | Can be used by the Chimneys that a burst of flits is not interleaved with other flits from other endpoints. If not set the router performs wormhole routing i.e. it locks the direction until flit with the `last` bit set has been sent. | +| `axi_ch` | `axi_ch_e`[^2] | Chimney | Used by the Chimney to encode the type of packet e.g. which AXI channel | +| `rob_req` | `logic` | Chimney | Flag to signal that the flit might need to be reordered in the Chimney | +| `rob_idx` | `rob_idx_t` | Chimney | The index into the reorder buffer of the Chimney | +| `atop` | `logic` | Chimney | Flag to signal that the flit is an ATOP flit and can bypass the reodering logic. | + +!!! info "Additional fields" + + Additional fields can be added to the header if needed. The routers just ignore those fields and forward them to the next router/Chimney. + +!!! example "SystemVerilog macros" + + _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the header fields such as `FLOO_TYPEDEF_HDR_T`. + +[^2]: The type is arbitrary and depends on the type of Chimney used but it is usually an `enum`. For instance, the single-AXI chimney encodes only 5 channels in `axi_ch_e`, while the narrow-wide AXI chimney encodes 10 channels in `nw_ch_e`. This can also be extended. + +## Payload + +The payload itself can be any data that needs to be sent from one node to another. The payload is not interpreted by the routers, they just forward it to the next hop. The payload can be of any width. Usually, the payload consists of an AXI request or response of one of the 5 channels. + +## Types of flits + +The entire flit is constructed by concatenating the header and the payload. One can define many types of flits i.e. one for every payload. The only requirement is that the flit includes the following fields: + +| Field | Type | Description | +| ----------- | --------------- | --------------------- | +| `hdr` | `hdr_t` | The header of the flit, which is identical across the whole network | +| `payload` | `payload_t`[^3] | The payload of the flit, which can be of any width | +| `rsvd` | `logic[x:0]` | Optional padding bits if the flit is smaller than the link width | + +[^3]: The payload type can be anything. For instance, sending an AXI AW is done by defining a `axi_aw_chan_t` struct for the payload type. + +!!! info "Additional fields" + + Again, additional fields can be added if needed. The only requirement is that the width of the flit matches exactly the width of the link. + +!!! example "SystemVerilog macros" + + _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the flits such as `FLOO_TYPEDEF_FLIT_T` for flits with the `rsvd` field and generic flits `FLOO_TYPEDEF_GENERIC_FLIT_T` without a `rsvd` field. diff --git a/docs/hw/links.md b/docs/hw/links.md index d5cb8999..17622ae0 100644 --- a/docs/hw/links.md +++ b/docs/hw/links.md @@ -1,27 +1 @@ -# Link-Level transport - -## Flits - -We start with the _flits_, also called flow control units, which is the smallest unit of data that is sent from node to another (e.g. from router to router, of network interface to router). Flits consists of two types of data: - -1. **Routing information**: Also called the header of the flit, this data is used by the routers to route the flit through the network. The header contains information such as the destination address, the source address, the flit type, etc. - -1. **Payload**: This is the actual data that is being sent from one node to another. Router do not look at the payload, they just forward it to the next hop. - -In traditional NoCs, the links have a fixed width (e.g. 32-bit). Usually, the payload and the information required for routing far exceeds this width. Therefore, the payload is split into multiple data flits and a header flit which encodes the routing information. Based on this information, routers in the network then know how to route the following data flits to the destination. - -In modern NoCs, this way of serializing payloads over the network is not very efficient anymore. With higher bandwidth requirements of the endpoints, the serialization becomes more and more a bottleneck, since the frequency of the links is limited. Further, serialization causes additional latency which is undesirable. Lastly, the overhead of the header flits is not negligible, especially when the payload is small. - -Therefore, In _FlooNoC_ and modern NoCs in general, another approach is taken, which differs in two ways: - -1. **Flit width**: The width of the flits is not fixed anymore. Instead, the flits can be as wide as the payload to send the payload in a single cycle resp. in a single flit. - -1. **Parallel header**: Instead of sending the header before the payload, the header is sent in parallel to the payload. This way, the link utilization is not degraded by header flits. - -!!! info "AMBA CHI" - - _FlooNoC_ is not the first NoC to use this approach. For example, the [AMBA CHI](https://developer.arm.com/documentation/ihi0050/latest/) protocol also encodes the entire payload (cachelines in this case) in a single flit including all the information required for routing. - -!!! tip "Wires are cheap now" - - You might wonder why this was not used in the first place. The reason is that wires were not as cheap as they are today. Modern technologies now have >10 metal layers which can fit >10000 wires/mm. A very good source on this topic, which has also influenced the design of _FlooNoC_ is the NOCS keynote [Reflections on 21 Years of NoCS](https://www.youtube.com/watch?v=Nk3oQm9NxcY) from Bill Dally, one of the pioneers in early NoC research. +# Links diff --git a/mkdocs.yml b/mkdocs.yml index 2c66c76e..fea9145a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,16 +51,18 @@ plugins: enable_creation_date: true markdown_extensions: - - pymdownx.superfences - - pymdownx.tabbed: - alternate_style: true + - admonition - attr_list + - footnotes + - md_in_html + - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg - - md_in_html - - admonition - - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - tables nav: - Home: @@ -71,6 +73,7 @@ nav: - Getting Started: getting_started.md - Hardware IPs: - Overview: hw/overview.md + - Flits: hw/flits.md - Links: hw/links.md - Routing Algorithms: hw/route_algos.md - Network Interfaces: hw/chimneys.md From 041670b88713770842ed3ca5ddaaf1db4da2ef78 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 14 Sep 2024 21:58:07 +0200 Subject: [PATCH 39/46] ci: Uncomment `main` branch trigger --- .github/workflows/publish-docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 7db9483c..6c3c5637 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -7,8 +7,9 @@ name: publish-docs on: - # push: - # branches: [ main ] + push: + branches: + - main workflow_dispatch: jobs: From 75c8a982102292eb94bd414dfe41ad306671d629 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 16 Sep 2024 22:49:49 +0200 Subject: [PATCH 40/46] docs(hw): Channels & Links update --- docs/hw/links.md | 28 +++++++++++++++++++++++++++- mkdocs.yml | 2 +- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/hw/links.md b/docs/hw/links.md index 17622ae0..31c36d55 100644 --- a/docs/hw/links.md +++ b/docs/hw/links.md @@ -1 +1,27 @@ -# Links +# Channels + +Now that we established flits -- the smallest unit of data that is sent -- we can discuss how a flit is sent from one node to another. As we have explained in the [flits](flits.md) section, there usually exist multiple types of flits, which differ in the payload they carry. For instance, the payload can be an AXI request, an AXI response, or any other data that needs to be sent from one node to another. For multiple reasons, it makes sense to send these different types of flits over different "channels", which we will discuss in this section. + +## Why use multiple channels? + +Channels are a way to separate different types of flits. For instance, one channel can be used to send AXI requests, another channel can be used to send AXI responses, and a third channel can be used to send other types of data. This separation has multiple advantages: + +1. **Message-Level deadlocks**: If all flits are sent over a single channel, it could happen that message-level deadlocks are introduced. For instance, if node A sends a request to node B, and node B sends a request to node A, both nodes both nodes might need to wait for their response before accepting a new request, which can lead to a deadlock. By separating the request and response channel, we can ensure forward progress. + +1. **Latency**: Different types of flits might have different priorities. For instance, some messages are very latency-sensitive (e.g. synchronization messages), while others are much more latency-tolerant (e.g. bulk data transfers). By separating the channels, we can ensure that the congestion can be kept low on the latency-sensitive channel, which in turn reduces the latency of these messages. + +1. **Bandwidth**: Different types of flits might have different bandwidth requirements. For instance, the data widths of AXI can reach up to 1024 bit, and AXI additionally supports burst transfers. Using wide links is the natural way to increase the bandwidth of the channel. However, smaller flits like AXI write responses are only a fraction of the link width and would waste bandwidth if sent over a wide link. + +## Virtual vs. Physical channels + +## _FlooNoC_ channels + +### `req` channel + +### `rsp` channel + +### `wide` + +## AXI Channel mapping + +## Links diff --git a/mkdocs.yml b/mkdocs.yml index fea9145a..001cea85 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,7 +74,7 @@ nav: - Hardware IPs: - Overview: hw/overview.md - Flits: hw/flits.md - - Links: hw/links.md + - Channels & Links: hw/links.md - Routing Algorithms: hw/route_algos.md - Network Interfaces: hw/chimneys.md - Router: hw/routers.md From c2d329679eadbd60be3f9fa06c0bff96bd6f8e3f Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Mon, 16 Sep 2024 22:50:08 +0200 Subject: [PATCH 41/46] docs(hw): Small update for flit table --- docs/hw/flits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hw/flits.md b/docs/hw/flits.md index 7633f3ed..6450715d 100644 --- a/docs/hw/flits.md +++ b/docs/hw/flits.md @@ -60,7 +60,7 @@ The entire flit is constructed by concatenating the header and the payload. One | ----------- | --------------- | --------------------- | | `hdr` | `hdr_t` | The header of the flit, which is identical across the whole network | | `payload` | `payload_t`[^3] | The payload of the flit, which can be of any width | -| `rsvd` | `logic[x:0]` | Optional padding bits if the flit is smaller than the link width | +| `rsvd` | `logic[RsvdBits-1:0]` | Optional padding bits if the flit is smaller than the link width | [^3]: The payload type can be anything. For instance, sending an AXI AW is done by defining a `axi_aw_chan_t` struct for the payload type. From 48e2b778b4d11a89bb54ef7a2768af4b97d90d4c Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Wed, 18 Sep 2024 22:57:48 +0200 Subject: [PATCH 42/46] docs(hw): Update channel and links --- docs/hw/flits.md | 4 --- docs/hw/links.md | 71 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 67 insertions(+), 8 deletions(-) diff --git a/docs/hw/flits.md b/docs/hw/flits.md index 6450715d..4cb9c996 100644 --- a/docs/hw/flits.md +++ b/docs/hw/flits.md @@ -18,10 +18,6 @@ Therefore, In _FlooNoC_ and modern NoCs in general[^1], another approach is take 1. **Parallel header**: Instead of sending the header before the payload, the header is sent in parallel to the payload. This way, the link utilization is not degraded by header flits. -!!! tip "Wires are cheap now" - - You might wonder why this was not used in the first place. The reason is that wires were not as cheap as they are today. Modern technologies now have >10 metal layers which can fit >10000 wires/mm. A very good source on this topic, which has also influenced the design of _FlooNoC_ is the NOCS keynote [Reflections on 21 Years of NoCS](https://www.youtube.com/watch?v=Nk3oQm9NxcY) from Bill Dally, one of the pioneers in early NoC research. - Below, we will discuss the header and the payload in more detail. ## Header diff --git a/docs/hw/links.md b/docs/hw/links.md index 31c36d55..679612ac 100644 --- a/docs/hw/links.md +++ b/docs/hw/links.md @@ -14,14 +14,77 @@ Channels are a way to separate different types of flits. For instance, one chann ## Virtual vs. Physical channels +There are essentially two different ways how to implement multiple channels: + +1. **Virtual channels**: Virtual channels are a way to multiplex multiple channels over a single physical channel. Virtual channel have the advantage that the physical channel can be used more efficiently, as it can be shared between multiple virtual channels. Moreover, message-level deadlocks can be prevented with virtual channels, as messages from different channels can be interleaved, resp. they can overtake each other. This is possible, since on the RX side of a virtual channel, every channel has its own buffers. So even if for instance the buffer for requests is full, responses can still be received. While virtual channels have its advantages, they also have some disadvantages. For instance, virtual channels require additional logic to multiplex and demultiplex the channels, which increases the complexity of the design. Furthermore, multiplexing onto a single physical channel limits the throughput of the channel. + +1. **Physical channels**: Physical channels on the other hand are _real_ physical channels in hardware. Effectively, physical channels result in multiple separate networks used to send different types of messages throught the network. The main advantage of physical channels is the throughpt of the channel, since it is not shared with other channels. Also, routers for physical channels can be streamlined, since they don't require multiplexing of virtual channels. One disadvantage of physical channels is that they require more routing resources, as each physical channel is implemented as a separate network. + +One of the main design principles of _FlooNoC_ is to use multiple physical channels instead of virtual channels. While the main drawback of physical channels is the increased routing resources, modern technologies come to rescue here. For instance, modern technologies usually can feature up to 20 metal layers and have routing resources of >10000 wires/mm that can be exploited to implement multiple physical channels. Not all of it is avaliable for routing of course, since some routing resources are used for cell connectivity and power distribution. However, the routing resources tend not to be the bottleneck in the design, especially not global wires on higher metal layers of the chip, which are primarly used for the routing of the physical links. + +!!! tip "Wires are cheap now" + + A very good source on this topic, which has also greatly influenced the use of physical channels during the development of _FlooNoC_ is the NOCS keynote [Reflections on 21 Years of NoCS](https://www.youtube.com/watch?v=Nk3oQm9NxcY) from Bill Dally, one of the pioneers in early NoC research. + ## _FlooNoC_ channels -### `req` channel +In _FlooNoC_, we use multiple physical channels to separate different types of traffic. The most basic form of _FlooNoC_ is to use two channels `req` and `rsp`, to send all request resp. responses. However, traffic in an SoC can be quite diverse, and comes with different requirements. For instance, synchronization messages are usually very small in the order of a few bytes, but are very latency-sensitive. On the other hand, bulk data transfers can be very large, but are usually more tolerant to latency, since they can be issued as multiple outstanding transactions. In some systems, this is the reason why mulitple AXI interfaces are used. A narrow one for configuration and synchronization messages and a wider one for bulk data transfers. In that case, _FlooNoC_ also featuers a `wide` channel to provide high bandwidth for bulk data transfers. + +## Channel Mapping + +### Single-AXI to `req`, `rsp` mapping + +If only a single AXI interface is used (e.g. with 32-bit address width and 64-bit data width), the AXI channels are mapped to the _FlooNoC_ channels as follows: + +| | `req` | `rsp` | primary payload | +| ----------------- | ---- | ---- | --- | +| `Aw` | :material-check: | - | `addr` (32-bit) | +| `Aw` | :material-check: | - | `addr` (32-bit) | +| `W` | :material-check: | - | `w_data` (64-bit) | +| `R` | - | :material-check: | `r_data` (64-bit) | +| `B` | - | :material-check: | `b_rsp` (2-bit) | + +The mapping is quite straightforward. Requests from AXI manager are sent over the `req` channel, while responses from AXI subordinates are sent over the `rsp` channel. Message-level deadlock are also avoided this way, since requests and responses are sent over different channels. + +## Narrow-Wide AXI to `req`, `rsp`, `wide` mapping + +In case two AXI interfaces are used, a narrow (e.g. 64-bit) and a wide one (e.g. 512-bit), the AXI channels are mapped to the _FlooNoC_ channels as follows: + +| | `req` | `rsp` | `wide` | primary payload | +| ----------------- | ---- | ---- | ---- | --- | +| `NarrowAw` | :material-check: | - | - | `addr` (32-bit) | +| `NarrowAr` | :material-check: | - | - | `addr` (32-bit) | +| `NarrowW` | :material-check: | - | - | `w_data` (64-bit) | +| `NarrowR` | - | :material-check: | - | `r_data` (64-bit) | +| `NarrowB` | - | :material-check: | - | `b_rsp` (2-bit) | +| `WideAw` | - | - | :material-check: | `addr` (32-bit) | +| `WideAr` | :material-check: | - | - | `addr` (32-bit) | +| `WideW` | - | - | :material-check: | `w_data` (512-bit) | +| `WideR` | - | - | :material-check: | `r_data` (512-bit) | +| `WideB` | - | :material-check: | - | `b_rsp` (2-bit) | + +In this case, the narrow AXI to `req`, `rsp` mapping is the same as in the single-AXI case. However, the wide AXI interface mapping is a different and requires some explanation. Unsurprisingly, the wide data channels `WideR` and `WideW` are mapped to the `wide` channel to make use of its high bandwidth. The AXI read request `WideAr` and the write response `WideB` are mapped to the `req` and `rsp` channel, respectively. Those are smaller messages and would underutilize the `wide` channel. The outlier here is the AXI write requests `WideAw`, which is mapped to the `wide` channel, eventhough it is a small message. The reason for this is related to the ordering of AXI transactions. + +??? info "AXI ordering for the curious" + + AXI supports out-of-order transactions by specifying transaction IDs (`txnID`). Transactions with the same `txnID` need to be ordered with respect to each other i.e. they cannot overtake each other. Transactions with different `txnID` however are free to do so. The `txnID` is specified in the initial requests and the corresponding read and write response also carries the same `txnID`. However, the write data is a bit different in this regard. The write data `W` does not feature any `txnID` and needs to be sent (and eventually arrive at the AXI subordinate) in the same order as the write requests `Aw`. This also needs to be guaranteed in systems with multiple AXI managers that send write requests to the same AXI subordinate. If the `Aw` and `W` are sent over different channels, it might be that the order of them is not preserved since those differnent channels might have different congestion levels. To avoid this, the `WideAw` and `WideW` are sent over the same channel, which is the `wide` channel in this case. Furthermore, it also needs to be guaranteed that `WideW` payloads from different AXI requesters are not interleaved in the network, since they cannot be distinguished when arriving at the destination (which would also very likely require large reorder buffers). The non-interleaving needs to be guaranteed by the routers as well, which will be discussed later in the [routers](routers.md) section. + + +_FlooNoC_ uses `unions` to represent the different types of flits that are sent over the same physical channel. For instance, the `req` channel for a single-AXI configuration is defined as follows: + +```verilog +typedef union packed { + floo_aw_flit_t axi_aw; + floo_w_flit_t axi_w; + floo_ar_flit_t axi_ar; + floo_generic_flit_t generic; +} floo_req_chan_t; +``` -### `rsp` channel +A `union` essentially allows to represent multiple types of data in the same number of bits. This is also why `rsvd` bits are used in the flits, to ensure that the flits sent over a channel all have the same size. The `generic` is not meant to represent a flit with an actual payload, but can be used to decode the type of flit from its header. -### `wide` +!!! example "SystemVerilog Macros" + Similar to the flits, _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the channel types such as `FLOO_TYPEDEF_AXI_CHAN_ALL` for a single-AXI configuration and `FLOO_TYPEDEF_AXI_CHAN_ALL` for a narrow-wide AXI configuration. -## AXI Channel mapping ## Links From 7a28f2413a356b2e05616b6f329f281cce8eb514 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 28 Sep 2024 21:03:49 +0200 Subject: [PATCH 43/46] docs(hw): Update links section --- docs/hw/links.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/hw/links.md b/docs/hw/links.md index 679612ac..002e28b1 100644 --- a/docs/hw/links.md +++ b/docs/hw/links.md @@ -84,7 +84,23 @@ typedef union packed { A `union` essentially allows to represent multiple types of data in the same number of bits. This is also why `rsvd` bits are used in the flits, to ensure that the flits sent over a channel all have the same size. The `generic` is not meant to represent a flit with an actual payload, but can be used to decode the type of flit from its header. !!! example "SystemVerilog Macros" - Similar to the flits, _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the channel types such as `FLOO_TYPEDEF_AXI_CHAN_ALL` for a single-AXI configuration and `FLOO_TYPEDEF_AXI_CHAN_ALL` for a narrow-wide AXI configuration. + Similar to the flits, _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the channel types such as `FLOO_TYPEDEF_AXI_CHAN_ALL` for a single-AXI configuration and `FLOO_TYPEDEF_NW_CHAN_ALL` for a narrow-wide AXI configuration. ## Links + +The links itself wraps a channel and additionally handles the flow control needed to send data from one node to another. _FlooNoC_ primarily uses valid-ready handshaking flow control, but also has some support for credit-based flow control (see routers section for more information). The link then looks as follows: + +```verilog + typedef struct packed { + logic valid; + logic ready; + floo_req_chan_t req; + } floo_req_t; +``` + +!!! info "Bidirectional links" + Currently, _FlooNoC_ only supports bidirectional links. This is why both `valid` and `ready` are encoded in the same link, eventhough they are separate from each other (i.e. the `ready` is an RX signal, while the `valid` is a TX signal). + +!!! example "SystemVerilog Macros" + Again, _FlooNoC_ provides System Verilog macros in `typedef.svh` to generate the flit types. For instance, `FLOO_TYPEDEF_AXI_LINK_ALL` for a single-AXI configuration and `FLOO_TYPEDEF_NW_LINK_ALL` for a narrow-wide AXI configuration. From 076cf0472eb067fc56daacda0853750b4efa057e Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 28 Sep 2024 21:52:55 +0200 Subject: [PATCH 44/46] docs(general): Add empty `CONTRIBUTING.md` --- docs/CONTRIBUTING.md | 3 +++ mkdocs.yml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..75cd854c --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Guide to Contributing + +TODO diff --git a/mkdocs.yml b/mkdocs.yml index 001cea85..eb54a8db 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,7 @@ nav: - index.md - Repository Structure: repository_structure.md - License: license.md - - Contributing: contributing.md + - Contributing: CONTRIBUTING.md - Getting Started: getting_started.md - Hardware IPs: - Overview: hw/overview.md From a243edde0e5ff43dfafb95c9da996a3ae44b880a Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Sat, 28 Sep 2024 22:40:52 +0200 Subject: [PATCH 45/46] docs(hw): Write route algos section --- docs/hw/route_algos.md | 78 +++++++++++++++++++++++++++++++++++++ docs/javascripts/mathjax.js | 19 +++++++++ mkdocs.yml | 6 +++ 3 files changed, 103 insertions(+) create mode 100644 docs/javascripts/mathjax.js diff --git a/docs/hw/route_algos.md b/docs/hw/route_algos.md index 8bc2f4de..9cf510c7 100644 --- a/docs/hw/route_algos.md +++ b/docs/hw/route_algos.md @@ -1 +1,79 @@ # Routing Algorithms + +One of the main design principles of _FlooNoC_ is that it is flexible and can support multiple routing algorithms as well as arbitrary topologies. Currently, _FlooNoC_ supports the following routing algorithms: + +1. **Dimension-ordered Routing (DOR)**: Also known as XY-Routing and arguably the most popular routingn algorithm used in 2D mesh networks, due to its simple implementation and guarantee of deadlock freedom. + +1. **Source-based routing**: A routing algorithm where the source specifies the entire route to the destination. + +1. **Table-based routing**: A routing algorithm where the selection of port is based on a table that is provided to the router. + +All of those routing algorithms are static respectively deterministic. While dynanmic routing algorithms might feature better performance since it can adapt to changing network conditions, they are also more complex to implement and might introduce deadlocks. Furthermore, _FlooNoC_ uses the deterministic routing assumption of the network to guarante the correct ordering of AXI transactions. For instance, _FlooNoC_ relies on the fact that flits from the same source and channel to the same destination remain ordered, which is not given in dynamic routing algorithms. + +## Dimension-ordered (DOR) + +Dimension-ordered routing is a simple routing algorithm that routes flits based on XY-coordinates, which is why it is commonly used in 2D mesh networks. In dimension ordered routing, a flit is always routed in one dimension and then in the other. Since this routing cannot introduce any cycles, it is deadlock-free by design. The implementation of DOR is also very simple, as it only requires the current and destination coordinates of the flit. Each router knows its own XY coordinates and compares them to the destination coordinates of the flit. The routing algorithm then is the following: + +$$ +Port = \begin{cases} +East & id_{dst, x} > id_{router, x} \\ +West & id_{dst, x} < id_{router, x} \\ +North & id_{dst, x} = id_{router, x} \land id_{dst, y} > id_{router, y} \\ +South & id_{dst, x} = id_{router, x} \land id_{dst, y} < id_{router, y} \\ +Eject & id_{dst, x} = id_{router, x} \land id_{dst, y} = id_{router, y} +\end{cases} +$$ + +Meaning, the flits is routed to either the east or west until it reaches the correct X-coordinate, after which it is routed to the north or south until. If both coordinates match, the flit is ejected from the network i.e. it is sent to (one of the) local port(s) of the router. + +### Advantages + +The DOR routing algorithm is very simple but effective and results in very low complexity in the hardware. Furthermore, it is deadlock-free by design since it cannot introduce any cycles. Also, XY-routing allows for some optimization in the router design. Since a flit is always routed first in X and then in Y, some connections in the router are illegal and can be disabled to reduce the number of connections in the router. For instance, the connection from north to east or west is not possible as this would imply that the flit was routed in the Y-dimension before the X-dimension. + +### Disadvantages + +The main disadvantage of DOR routing is that it only works in 2D meshes. Also, there are some corner cases where DOR routing can create problems. For instance, if nodes are attached to the boundary of the mesh, a flit entering from the north boundary cannot reach the east boundary, since it would have to change X and Y direction multiple times. + +## Source-based Routing + +Source-based routing is another simple routing algorithm where the entire route to the destination is specified by node which injects the flit into the network. The route is encoded in the header of the flit as an array of ports that each router should take. The size of the route encoding depends on the diameter of the network (the maximum number of hops) as well as the router radix (number of router ports). For instance, a route might be encoded like this in a 4x4 2D mesh network: + +```verilog + route_t route = '{3'b0, 3'b1, 3'b2, 3'b3, 3'b4, 3'b5, 3'b6}; +``` + +A router usually has 5 ports (4 for the cardinal directions and one local port), which can be encoded in 3 bits. Further, the maximum number of hops in a router is 7 (including the routers where the flit is injected and ejected), which results in a route encoding of 21 bits. This route encoding is part of the flit header and is checked by each router. + +??? example "Flit header differences" + The header of a flit is different for source-based routing compared to the other routing algorithms. Instead of encoding the destination id (`dst_id`) as a node ID (of type `id_t`), the destination id is encoded as a route (`route_t`). The source id (`src_id`) is still encoded as a node ID, since the source node generally does not know the route back to itself from the destination. Instead it provides the `src_id`, which can be translated back to a route by the destination node. + + +The implementation of this routing algorithm is also very simple, since every router _consumes_ a port from the route encoding, which means it simply shifts the route encoding by the number of bits that is required to encode the number of possible ports. This way, a router does not neet to be aware of how many hops a flit has already passed, since it can simply look at the first bits of the route encoding to determine the next port. + +### Advantages + +The main advantage of source-based routing is that it is very flexible and can be used in arbitrary topologies, that go beyond 2D meshes. The routes can also be optimized for instance to reduce congestion or to minimize the number of hops. Theoretically, source-based routing can also be dynamic, since the source can change the route encoding based on the network conditions. However, as mentioned before, _FlooNoC_ currently does not support dynamic routing algorithms. + +### Disadvantages + +The main disadvantage of source-based routing is that the bits required for encoding the route grows with the network diameter and at some point it becomes infeasible to encode the route in the flit header. Also, source-based routing is not inherently deadlock-free, if the routes are not carefully chosen. Lastly, the route encodings need to be provided to the source respectively the network interface, which can become quite large, since every destination requires its own route encoding. + +## Table-based Routing + +Table-based routing shifts the routing computation to the routers themselves. Each router has a table that specifies the output port for each destination. Instead of using actual tables, it is also possible to use address decoders which can reduce the number of entries in the table, since it allows to specify a range of destinations that are routed to the same port. An instance of such a routing table could look like the following: + +```verilog + localparam router_rule_t [NumRules-1:0] RouterTable = '{ + '{idx: 1, start_addr: 0, end_addr: 2}, // -> port 1 for destination 0, 1 + '{idx: 2, start_addr: 2, end_addr: 3}, // -> port 2 for destination 2 + '{idx: 3, start_addr: 3, end_addr: 10} // -> port 3 for destination 3 to 9 + }; +``` + +where `idx` is the port number and `start_addr` and `end_addr` is the range of destination node IDs that are routed to the port. + +### Advantages +Similar to source-routing, table-based routing can be used for any kind of topology and the routes respectively the routing tables can be optimized to avoid congestion etc., Also, table-based routing can be dynamic, since the routing tables could be updated dynamically (which is not supported by _FlooNoC_). + +### Disadvantages +Table-based routing has a similar problem as source-based routing, since the router tables grow with the number of destinations. Also, table-based routing is not inherently deadlock-free, if the routing tables are not carefully chosen. Lastly, the routing tables need to be provided to the routers, which can become quite large, since every destination requires its own routing table. diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 00000000..7e48906a --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,19 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.startup.output.clearCache() + MathJax.typesetClear() + MathJax.texReset() + MathJax.typesetPromise() +}) diff --git a/mkdocs.yml b/mkdocs.yml index eb54a8db..75a86ce7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,10 @@ site_name: FlooNoC extra_css: - stylesheets/extra.css +extra_javascript: + - javascripts/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + theme: logo: img/floo_noc_material_logo.png favicon: img/floo_noc_favicon_logo.png @@ -55,6 +59,8 @@ markdown_extensions: - attr_list - footnotes - md_in_html + - pymdownx.arithmatex: + generic: true - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji From 80a7f602023700352bcfb67d478b89f5533500b6 Mon Sep 17 00:00:00 2001 From: Tim Fischer Date: Tue, 22 Oct 2024 22:17:51 +0200 Subject: [PATCH 46/46] docs(hw): Update chimney section --- docs/hw/chimneys.md | 46 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/hw/chimneys.md b/docs/hw/chimneys.md index d71478be..506dc826 100644 --- a/docs/hw/chimneys.md +++ b/docs/hw/chimneys.md @@ -1,3 +1,47 @@ # Network interfaces (a.k.a. chimneys) -*TODO* +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