docs: Add first Occamy documentation

pulp-platform · Aug 19, 2023 · 17aabf9 · 17aabf9
1 parent 6a396d5
commit 17aabf9
Show file tree

Hide file tree

Showing 21 changed files with 154 additions and 0 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -7,6 +7,20 @@ name: ci
 on: [push, pull_request]
 jobs:
 
+  ########
+  # Docs #
+  ########
+
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-22.04
+    container:
+      image: ghcr.io/pulp-platform/occamy
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build docs
+        run: mkdocs build
+
   #######################
   # Build SW for Occamy #
   #######################

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -0,0 +1,20 @@
+# 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
+
+name: publish-docs
+on:
+  push:
+    branches: [init]
+  workflow_dispatch:
+jobs:
+  deploy:
+    name: Deploy documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs gh-deploy --force
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -34,6 +34,14 @@ before_script:
   - export PATH="$(pwd)/.tools/verible/bin:$PATH"
   # yamllint enable rule:line-length
 
+##############
+# Build docs #
+##############
+
+docs:
+  script:
+    - mkdocs build
+
 #########################
 # Build Occamy software #
 #########################

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,24 @@
+# Occamy
+
+The Occamy project is an open-source RISC-V hardware research project of ETH Zurich and University of Bologna targeting highest possible energy-efficiency. The system is designed around a cluster of versatile and small integer cores, which we call Snitch cluster. The system is designed to be highly parameterizable and suitable for many use-cases.
+
+## Getting Started
+
+See our dedicated [getting started guide](ug/getting_started.md).
+
+## Documentation
+
+The documentation is built from the latest master and hosted at github pages: [https://pulp-platform.github.io/occamy](https://pulp-platform.github.io/occamy).
+
+## About this Repository
+
+The original repository [https://github.com/pulp-platform/snitch](https://github.com/pulp-platform/snitch) was developed as a monorepo hosting both the base Snitch IPs and the Occamy system. For easier integration of the Snitch cluster IP into other systems, the original repo was split into two new repos:
+
+- the [Snitch cluster repository](https://github.com/pulp-platform/snitch_cluster) providing the Snitch cluster IP
+- [this repository](https://github.com/pulp-platform/occamy) hosting the Occamy system
+
+The dependency of the Occamy system on the Snitch cluster IP is handled behind the scenes with [Bender](https://github.com/pulp-platform/bender).
+
+## Licensing
+
+Occamy is made available under permissive open source licenses. See the `README.md` for a more detailed break-down.
diff --git a/docs/publications.md b/docs/publications.md
@@ -0,0 +1,9 @@
+# Publications
+
+If you use Occamy in your work, you can cite us:
+
+{%
+  include-markdown '../deps/snitch_cluster/docs/publications.md'
+  start="<!--start-publications-->"
+  end="<!--end-publications-->"
+%}
diff --git a/docs/occamy/1_overview.md → docs/rm/1_overview.md b/docs/occamy/1_overview.md → docs/rm/1_overview.md
diff --git a/docs/occamy/2_addrmap.md → docs/rm/2_addrmap.md b/docs/occamy/2_addrmap.md → docs/rm/2_addrmap.md
diff --git a/docs/occamy/3_system_components → docs/rm/3_system_components.md b/docs/occamy/3_system_components → docs/rm/3_system_components.md
diff --git a/docs/occamy/4_clocking.md → docs/rm/4_clocking.md b/docs/occamy/4_clocking.md → docs/rm/4_clocking.md
diff --git a/...ccamy/5_interrupts_and_synchronization.md → docs/rm/5_interrupts_and_synchronization.md b/...ccamy/5_interrupts_and_synchronization.md → docs/rm/5_interrupts_and_synchronization.md
diff --git a/docs/occamy/figures/cluster.drawio.png → docs/rm/figures/cluster.drawio.png b/docs/occamy/figures/cluster.drawio.png → docs/rm/figures/cluster.drawio.png
diff --git a/docs/occamy/figures/fpu_fma.drawio.png → docs/rm/figures/fpu_fma.drawio.png b/docs/occamy/figures/fpu_fma.drawio.png → docs/rm/figures/fpu_fma.drawio.png
diff --git a/docs/occamy/figures/fpu_sdotp.drawio.png → docs/rm/figures/fpu_sdotp.drawio.png b/docs/occamy/figures/fpu_sdotp.drawio.png → docs/rm/figures/fpu_sdotp.drawio.png
diff --git a/docs/occamy/figures/group.drawio.png → docs/rm/figures/group.drawio.png b/docs/occamy/figures/group.drawio.png → docs/rm/figures/group.drawio.png
diff --git a/docs/occamy/figures/occamy.drawio.png → docs/rm/figures/occamy.drawio.png b/docs/occamy/figures/occamy.drawio.png → docs/rm/figures/occamy.drawio.png
diff --git a/docs/occamy/figures/serial_link.png → docs/rm/figures/serial_link.png b/docs/occamy/figures/serial_link.png → docs/rm/figures/serial_link.png
diff --git a/docs/ug/documentation.md b/docs/ug/documentation.md
@@ -0,0 +1,3 @@
+{%
+  include-markdown '../../deps/snitch_cluster/docs/ug/documentation.md'
+%}
diff --git a/docs/ug/getting_started.md b/docs/ug/getting_started.md
@@ -0,0 +1,18 @@
+{%
+   include-markdown '../../deps/snitch_cluster/docs/ug/getting_started.md'
+   start="<!--start-section-1-->"
+   end="<!--end-section-1-->"
+%}
+
+{%
+   include-markdown '../../util/container/README.md'
+   start='<!--start-docs-->'
+%}
+
+{%
+   include-markdown '../../deps/snitch_cluster/docs/ug/getting_started.md'
+   start="<!--start-section-2-->"
+   end="<!--end-section-2-->"
+%}
+
+You will also have to install the GCC compiler toolchain for CVA6 and `verible`. You can use the commands in the `before_script` section of the [Gitlab CI file](https://github.com/pulp-platform/occamy/blob/{{ branch }}/.gitlab-ci.yml).
diff --git a/docs/ug/tutorial.md b/docs/ug/tutorial.md
@@ -0,0 +1,3 @@
+🚧 This section is a work in progress and will contain a software development tutorial specific for Occamy.
+
+In the meantime you can follow the [Snitch cluster tutorial](https://pulp-platform.github.io/snitch_cluster/ug/tutorial.html) as the two are heavily consistent.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,46 @@
+# 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: Occamy
+theme:
+  name: material
+
+  icon:
+    repo: fontawesome/brands/github
+
+repo_url: https://github.com/pulp-platform/occamy
+repo_name: pulp-platform/occamy
+
+markdown_extensions:
+  - admonition
+  - def_list
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+plugins:
+  - include-markdown
+  - macros
+use_directory_urls: false
+extra:
+  repo: occamy
+  branch: init
+nav:
+  - Home: index.md
+  - User Guide:
+      - Getting Started: ug/getting_started.md
+      # - Repository Structure: ug/directory_structure.md
+      - Tutorial: ug/tutorial.md
+      - Documentation: ug/documentation.md
+  - Reference Manual:
+      - Architecture:
+          - Overview: rm/1_overview.md
+          - Address Map: rm/2_addrmap.md
+          - System Components: rm/3_system_components.md
+          - Clocking: rm/4_clocking.md
+          - Interrupts and Synchronization: rm/5_interrupts_and_synchronization.md
+      - Schema: schema-doc/occamy.md
+  - Publications: publications.md
diff --git a/util/container/README.md b/util/container/README.md
@@ -0,0 +1,9 @@
+# Docker container
+
+This directory contains the [Docker file](Dockerfile) used to build the `occamy` Docker container.
+
+<!--start-docs-->
+
+The Occamy Docker container is based on the [latest Snitch cluster container image](https://github.com/pulp-platform/snitch_cluster/pkgs/container/snitch_cluster) and comes with all free development tools for Snitch/Occamy pre-installed. The environment is also already configured, such that no additional steps are required to work in the container after installation.
+
+Instructions to install the Snitch cluster container can be found in [this README](https://github.com/pulp-platform/snitch_cluster/blob/main/util/container/README.md) and are readily adapted to the Occamy container by replacing references to the Snitch container `ghcr.io/pulp-platform/snitch_cluster` with the Occamy container reference `ghcr.io/pulp-platform/occamy`.