From a5af779fb56b5abb59841ceeeb9784f41a0a4b3b Mon Sep 17 00:00:00 2001 From: Luca Colagrande Date: Fri, 15 Sep 2023 17:24:35 +0200 Subject: [PATCH] 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 --- .github/workflows/ci.yml | 8 ++--- .github/workflows/publish-docs.yml | 14 +++++++-- .gitignore | 1 + .gitlab-ci.yml | 2 +- Bender.yml | 4 +-- Makefile | 30 +++++++++++++++++++ docs/rm/peripherals.md | 5 ++++ docs/ug/documentation.md | 13 ++------ .../snitch_cluster_peripheral_reg.hjson | 21 +++++++++---- mkdocs.yml | 4 ++- 10 files changed, 73 insertions(+), 29 deletions(-) create mode 100644 Makefile create mode 100644 docs/rm/peripherals.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9c06e779..71fdc8eaa 100644 --- 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 index d9fadf460..188512ec6 100644 --- 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 index aafebe879..05bab5ff2 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,4 @@ gmon.out // Docs /site/ +/docs/generated/ \ No newline at end of file diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7847d0a44..811c82856 100644 --- 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 index 5d96cafc9..732788d0d 100644 --- 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 new file mode 100644 index 000000000..06a1c662f --- /dev/null +++ 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 new file mode 100644 index 000000000..98ff1063e --- /dev/null +++ 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 index b1179e70e..de61ab105 100644 --- 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 index 729967c1c..e3a0c485c 100644 --- 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 index 0140a15f8..b817649fd 100644 --- 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