From 8a199651d4229e4e9334cfda07bc1ebb12a5fb18 Mon Sep 17 00:00:00 2001 From: Luca Colagrande Date: Sat, 19 Aug 2023 13:09:02 +0200 Subject: [PATCH] docs: Add first Occamy documentation --- .github/workflows/ci.yml | 14 ++++++ .github/workflows/publish-docs.yml | 21 ++++++++ .gitlab-ci.yml | 8 +++ docs/index.md | 24 +++++++++ docs/publications.md | 9 ++++ docs/{occamy => rm}/1_overview.md | 0 docs/{occamy => rm}/2_addrmap.md | 0 .../3_system_components.md} | 0 docs/{occamy => rm}/4_clocking.md | 0 .../5_interrupts_and_synchronization.md | 0 .../{occamy => rm}/figures/cluster.drawio.png | Bin .../{occamy => rm}/figures/fpu_fma.drawio.png | Bin .../figures/fpu_sdotp.drawio.png | Bin docs/{occamy => rm}/figures/group.drawio.png | Bin docs/{occamy => rm}/figures/occamy.drawio.png | Bin docs/{occamy => rm}/figures/serial_link.png | Bin docs/ug/documentation.md | 3 ++ docs/ug/getting_started.md | 18 +++++++ docs/ug/tutorial.md | 3 ++ mkdocs.yml | 46 ++++++++++++++++++ util/container/README.md | 9 ++++ 21 files changed, 155 insertions(+) create mode 100644 .github/workflows/publish-docs.yml create mode 100644 docs/index.md create mode 100644 docs/publications.md rename docs/{occamy => rm}/1_overview.md (100%) rename docs/{occamy => rm}/2_addrmap.md (100%) rename docs/{occamy/3_system_components => rm/3_system_components.md} (100%) rename docs/{occamy => rm}/4_clocking.md (100%) rename docs/{occamy => rm}/5_interrupts_and_synchronization.md (100%) rename docs/{occamy => rm}/figures/cluster.drawio.png (100%) rename docs/{occamy => rm}/figures/fpu_fma.drawio.png (100%) rename docs/{occamy => rm}/figures/fpu_sdotp.drawio.png (100%) rename docs/{occamy => rm}/figures/group.drawio.png (100%) rename docs/{occamy => rm}/figures/occamy.drawio.png (100%) rename docs/{occamy => rm}/figures/serial_link.png (100%) create mode 100644 docs/ug/documentation.md create mode 100644 docs/ug/getting_started.md create mode 100644 docs/ug/tutorial.md create mode 100644 mkdocs.yml create mode 100644 util/container/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9155e0dd9..51490b7c7 100644 --- 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 new file mode 100644 index 000000000..749546451 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,21 @@ +# 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: bender update + - run: pip install -r python-requirements.txt + - run: mkdocs gh-deploy --force diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 1a006d5eb..cd151c46c 100644 --- 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 new file mode 100644 index 000000000..b7e0bbb39 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/publications.md b/docs/publications.md new file mode 100644 index 000000000..f8cfbe8c4 --- /dev/null +++ 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="" + end="" +%} diff --git a/docs/occamy/1_overview.md b/docs/rm/1_overview.md similarity index 100% rename from docs/occamy/1_overview.md rename to docs/rm/1_overview.md diff --git a/docs/occamy/2_addrmap.md b/docs/rm/2_addrmap.md similarity index 100% rename from docs/occamy/2_addrmap.md rename to docs/rm/2_addrmap.md diff --git a/docs/occamy/3_system_components b/docs/rm/3_system_components.md similarity index 100% rename from docs/occamy/3_system_components rename to docs/rm/3_system_components.md diff --git a/docs/occamy/4_clocking.md b/docs/rm/4_clocking.md similarity index 100% rename from docs/occamy/4_clocking.md rename to docs/rm/4_clocking.md diff --git a/docs/occamy/5_interrupts_and_synchronization.md b/docs/rm/5_interrupts_and_synchronization.md similarity index 100% rename from docs/occamy/5_interrupts_and_synchronization.md rename to docs/rm/5_interrupts_and_synchronization.md diff --git a/docs/occamy/figures/cluster.drawio.png b/docs/rm/figures/cluster.drawio.png similarity index 100% rename from docs/occamy/figures/cluster.drawio.png rename to docs/rm/figures/cluster.drawio.png diff --git a/docs/occamy/figures/fpu_fma.drawio.png b/docs/rm/figures/fpu_fma.drawio.png similarity index 100% rename from docs/occamy/figures/fpu_fma.drawio.png rename to docs/rm/figures/fpu_fma.drawio.png diff --git a/docs/occamy/figures/fpu_sdotp.drawio.png b/docs/rm/figures/fpu_sdotp.drawio.png similarity index 100% rename from docs/occamy/figures/fpu_sdotp.drawio.png rename to docs/rm/figures/fpu_sdotp.drawio.png diff --git a/docs/occamy/figures/group.drawio.png b/docs/rm/figures/group.drawio.png similarity index 100% rename from docs/occamy/figures/group.drawio.png rename to docs/rm/figures/group.drawio.png diff --git a/docs/occamy/figures/occamy.drawio.png b/docs/rm/figures/occamy.drawio.png similarity index 100% rename from docs/occamy/figures/occamy.drawio.png rename to docs/rm/figures/occamy.drawio.png diff --git a/docs/occamy/figures/serial_link.png b/docs/rm/figures/serial_link.png similarity index 100% rename from docs/occamy/figures/serial_link.png rename to docs/rm/figures/serial_link.png diff --git a/docs/ug/documentation.md b/docs/ug/documentation.md new file mode 100644 index 000000000..899bf2a06 --- /dev/null +++ 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 new file mode 100644 index 000000000..4fecceb90 --- /dev/null +++ b/docs/ug/getting_started.md @@ -0,0 +1,18 @@ +{% + include-markdown '../../deps/snitch_cluster/docs/ug/getting_started.md' + start="" + end="" +%} + +{% + include-markdown '../../util/container/README.md' + start='' +%} + +{% + include-markdown '../../deps/snitch_cluster/docs/ug/getting_started.md' + start="" + end="" +%} + +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). \ No newline at end of file diff --git a/docs/ug/tutorial.md b/docs/ug/tutorial.md new file mode 100644 index 000000000..65b0d7806 --- /dev/null +++ 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. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..78aa4936e --- /dev/null +++ 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 new file mode 100644 index 000000000..d1176ed48 --- /dev/null +++ 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. + + + +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`.