docs: Add peripheral registers (#37)

* docs: Add peripheral registers and catch CI build errors * docs: Clarify some of the performance counters * ci: Reset to use Docker container from main branch
pulp-platform · Sep 15, 2023 · a5af779 · a5af779
1 parent 49adab2
commit a5af779
Show file tree

Hide file tree

Showing 10 changed files with 73 additions and 29 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -15,11 +15,11 @@ jobs:
     name: Build documentation
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/pulp-platform/snitch_cluster:ipc-verification
+      image: ghcr.io/pulp-platform/snitch_cluster:main
     steps:
       - uses: actions/checkout@v2
       - name: Build docs
-        run: mkdocs build
+        run: make docs
 
   ##############################################
   # Simulate SW on Snitch Cluster w/ Verilator #
@@ -29,7 +29,7 @@ jobs:
     name: Simulate SW on Snitch Cluster w/ Verilator
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/pulp-platform/snitch_cluster:ipc-verification
+      image: ghcr.io/pulp-platform/snitch_cluster:main
     steps:
       - uses: actions/checkout@v2
         with:
@@ -54,7 +54,7 @@ jobs:
     name: Simulate SW on Snitch Cluster w/ Banshee
     runs-on: ubuntu-22.04
     container:
-      image: ghcr.io/pulp-platform/snitch_cluster:ipc-verification
+      image: ghcr.io/pulp-platform/snitch_cluster:main
     steps:
       - uses: actions/checkout@v2
         with:

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -18,7 +18,13 @@ jobs:
       - uses: mattnotmitt/doxygen-action@v1
         with:
           working-directory: sw/
-      - name: Generate Runtime Documentation
+      - name: bender install
+        uses: pulp-platform/pulp-actions/bender-install@v2
+        with:
+          version: 0.27.1
+      - name: Install Python requirements
+        run: pip install -r python-requirements.txt
+      - name: Generate runtime documentation
         # yamllint disable rule:line-length
         run: |
           mkdir doxybook2; cd doxybook2
@@ -29,5 +35,7 @@ jobs:
           ./doxybook2/bin/doxybook2 --input sw/doxygen/xml --output docs/runtime --config docs/doxybook2.json
           rm -rf doxybook2
         # yamllint enable rule:line-length
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --force
+      - name: Generate documentation sources
+        run: make doc-srcs
+      - name: Build and deploy documentation
+        run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,4 @@ gmon.out
 
 // Docs
 /site/
+/docs/generated/
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -29,7 +29,7 @@ before_script:
 
 docs:
   script:
-    - mkdocs build
+    - make docs
 
 #################################
 # Build Snitch cluster software #

diff --git a/Bender.yml b/Bender.yml
@@ -23,12 +23,10 @@ dependencies:
   axi_riscv_atomics:  { git: https://github.com/pulp-platform/axi_riscv_atomics,  version:  0.6.0   }
   common_cells:       { git: https://github.com/pulp-platform/common_cells,       version:  1.28.0  }
   FPnew:              { git: https://github.com/openhwgroup/cvfpu,                rev:      1202ca3 }  # TODO: feature branch `feature/expanding_sdotp`; get merged!
-  register_interface: { git: https://github.com/pulp-platform/register_interface, version:  0.3.3   }
+  register_interface: { git: https://github.com/pulp-platform/register_interface, version:  0.4.2   }
   tech_cells_generic: { git: https://github.com/pulp-platform/tech_cells_generic, version:  0.2.11  }
   riscv-dbg:          { git: https://github.com/pulp-platform/riscv-dbg,          version:  0.8.0   }
 
-# Note: used to vendor-in the musl sources, but cannot be used consistently
-#       until this issue is solved https://github.com/pulp-platform/bender/issues/133
 vendor_package:
   - name: musl
     target_dir: sw/math

diff --git a/Makefile b/Makefile
@@ -0,0 +1,30 @@
+# Copyright 2023 ETH Zurich and University of Bologna.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+REGGEN = $(shell bender path register_interface)/vendor/lowrisc_opentitan/util/regtool.py
+
+GENERATED_DOCS_DIR = docs/generated
+GENERATED_DOC_SRCS = $(GENERATED_DOCS_DIR)/peripherals.md
+
+.PHONY: all doc-srcs docs
+.PHONY: clean clean-docs
+
+all: docs
+clean: clean-docs
+
+doc-srcs: $(GENERATED_DOC_SRCS)
+
+docs: doc-srcs
+	@if mkdocs build | grep -q "ERROR"; then \
+		exit 1; \
+	fi
+
+clean-docs:
+	rm -rf $(GENERATED_DOCS_DIR)
+
+$(GENERATED_DOCS_DIR):
+	mkdir -p $@
+
+$(GENERATED_DOCS_DIR)/peripherals.md: hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson | $(GENERATED_DOCS_DIR)
+	$(REGGEN) -d $< > $@
diff --git a/docs/rm/peripherals.md b/docs/rm/peripherals.md
@@ -0,0 +1,5 @@
+# Snitch Cluster peripherals
+
+This section documents the registers exposed by the Snitch cluster to interface with various cluster-level peripherals, including the performance counters.
+
+{% include-markdown '../generated/peripherals.md' %}
diff --git a/docs/ug/documentation.md b/docs/ug/documentation.md
@@ -10,20 +10,11 @@ documentation, make sure you have the required dependencies installed:
 pip install -r docs/requirements.txt
 ```
 
-After everything is installed, you can build and serve a local copy by
+After everything is installed, you can build a static copy of the `html` documentation by
 executing (in the root directory):
 
 ```shell
-mkdocs serve
-```
-
-This opens a local webserver listening on
-[http://127.0.0.1:8000/](http://127.0.0.1:8000/).
-
-Alternatively, you can build a static copy of the `html` documentation:
-
-```shell
-mkdocs build
+make docs
 ```
 
 ## Organization

diff --git a/hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson b/hw/snitch_cluster/src/snitch_cluster_peripheral/snitch_cluster_peripheral_reg.hjson
@@ -39,7 +39,7 @@
                 desc: '''
                         Increased whenever the TCDM is accessed. Each individual access is tracked,
                         so if `n` cores access the TCDM, `n` will be added. Accesses are tracked at the TCDM,
-                        so it doesn't matter whether the cores or the for example the SSR hardware accesses
+                        so it doesn't matter whether the cores or for example the SSR hardware accesses
                         the TCDM. _This is a cluster-global signal._
                         '''
             },
@@ -48,8 +48,8 @@
                 resval: "0",
                 name: "TCDM_CONGESTED"
                 desc: '''
-                        Incremented whenever an access twoards the TCDM is made but the arbitration
-                        logic didn't grant the access (due to congestion). Is strictly less than TCDM_ACCESSED.
+                        Incremented whenever an access towards the TCDM is made but the arbitration
+                        logic didn't grant the access (due to congestion). It's strictly less than TCDM_ACCESSED.
                         _This is a cluster-global signal._
                         '''
             },
@@ -58,7 +58,10 @@
                 resval: "0",
                 name: "ISSUE_FPU"
                 desc: '''
-                        Core operations performed in the FPU. _This is a hart-local signal._
+                        Operations performed in the FPU. Includes both operations initiated by the
+                        sequencer and by the core. When the Xfrep extension is available, this counter is
+                        equivalent to ISSUE_FPU_SEQ (see description of ISSUE_FPU_SEQ). If the Xfrep extension
+                        is not supported, then it is equivalent to ISSUE_CORE_TO_FPU. _This is a hart-local signal._
                         '''
             },
             {
@@ -67,7 +70,11 @@
                 name: "ISSUE_FPU_SEQ"
                 desc: '''
                         Incremented whenever the FPU Sequencer issues an FPU instruction.
-                        Might be non available if the hardware doesn't support FREP.
+                        Might not be available if the hardware doesn't support FREP.
+                        Note that all FP instructions offloaded by the core to the FPU are routed
+                        through the sequencer (although not necessarily buffered) and thus are also counted.
+                        The instructions issued independently by the FPU sequencer could thus be
+                        calculated as ISSUE_FPU_SEQ_PROPER = ISSUE_FPU_SEQ - ISSUE_CORE_TO_FPU.
                         _This is a hart-local signal._
                         '''
             },
@@ -83,7 +90,9 @@
                 resval: "0",
                 name: "RETIRED_INSTR"
                 desc: '''
-                        Instructions retired by the core. _This is a hart-local signal._
+                        Instructions retired by the core, both offloaded and not. Does not
+                        count instructions issued independently by the FPU sequencer.
+                        _This is a hart-local signal._
                         '''
             },
             {

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,7 +22,8 @@ markdown_extensions:
       emoji_generator: !!python/name:materialx.emoji.to_svg
 plugins:
   - include-markdown
-  - macros
+  - macros:
+      on_error_fail: true
 use_directory_urls: false
 extra:
   branch: main
@@ -41,6 +42,7 @@ nav:
           - Snitch: rm/snitch.md
           - Snitch Cluster:
               - Overview: rm/snitch_cluster.md
+              - Peripherals: rm/peripherals.md
               - Schema: schema-doc/snitch_cluster.md
           - Reqrsp Interface: rm/reqrsp_interface.md
           - Custom Instructions: rm/custom_instructions.md