Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add peripheral registers #37

Merged
merged 3 commits into from
Sep 15, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 #
Expand All @@ -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:
Expand All @@ -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:
Expand Down
14 changes: 11 additions & 3 deletions .github/workflows/publish-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ gmon.out

// Docs
/site/
/docs/generated/
2 changes: 1 addition & 1 deletion .gitlab-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ before_script:

docs:
script:
- mkdocs build
- make docs

#################################
# Build Snitch cluster software #
Expand Down
4 changes: 1 addition & 3 deletions Bender.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 30 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -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 $< > $@
5 changes: 5 additions & 0 deletions docs/rm/peripherals.md
Original file line number Diff line number Diff line change
@@ -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' %}
13 changes: 2 additions & 11 deletions docs/ug/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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._
'''
},
Expand All @@ -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._
'''
},
Expand All @@ -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._
'''
},
{
Expand All @@ -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._
'''
},
Expand All @@ -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._
'''
},
{
Expand Down
4 changes: 3 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading