docs: Add mkdocs documentation (#12)

* Update README.md

* doc: First work on full documentation

* doc: More work on documentation

* treewide: Further work on doc, add CVA6 SDK submodule

* doc: More work on documentation

* doc: More work on documentation

* docs: Further work on docs

* docs: Repoint deployment branch to main

* docs: Some cleanup

---------

Co-authored-by: Paul Scheffler <[email protected]>

.github/workflows/build.yml

@@ -30,7 +30,7 @@ jobs:
           cache: pip
       -
         name: Install Python requirements
-        run: pip install -r .github/requirements.txt
+        run: pip install -r requirements.txt
       -
         name: Install RISC-V GCC toolchain
         uses: pulp-platform/pulp-actions/riscv-gcc-install@v2

.github/workflows/publish-docs.yml

@@ -0,0 +1,35 @@
+# 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
+
+# Author: Paul Scheffler <[email protected]>
+
+name: publish-docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+      -
+        name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+          cache: pip
+      -
+        name: Install Python requirements
+        run: pip install -r requirements.txt
+      -
+        name: Deploy Documentation
+        run: mkdocs gh-deploy --force

.gitignore

@@ -11,6 +11,9 @@ nonfree/
 # Dependency files
 .bender/
 
+# Documentation site
+site/
+
 # Software build files
 *.bin
 *.dump

.gitmodules

@@ -2,3 +2,6 @@
 	path = sw/deps/printf
 	url = https://github.com/mpaland/printf
 	ignore = dirty
+[submodule "sw/deps/cva6-sdk"]
+	path = sw/deps/cva6-sdk
+	url = [email protected]:pulp-platform/cva6-sdk.git

README.md

@@ -1,32 +1,42 @@
 # Cheshire
 
-This repository hosts the Cheshire SoC platform. Cheshire is a minimal Linux-capable SoC built around the RISC-V CVA6 core. It is developed as part of the PULP project, a joint effort between ETH Zurich and the University of Bologna.
+Cheshire is a minimal Linux-capable host platform built around the RISC-V [CVA6](https://github.com/openhwgroup/cva6) core. Its goal is to provide a *lightweight*, *configurable*, *autonomously booting* host to systems that need one, from minimal Linux-capable SoCs to manycore compute accelerators.
 
-## Disclaimer
+Cheshire is developed as part of the PULP project, a joint effort between ETH Zurich and the University of Bologna.
 
-This project is still considered to be in early development; some parts may not yet be functional, and existing interfaces and conventions may be broken without prior notice. We target a formal release in the very near future.
+## Quick Start
 
-## Build
+* To learn how to build and use Cheshire, see [Getting Started](https://pulp-platform.github.io/cheshire/gs/).
+* To learn about available simulation, FPGA, and ASIC targets, see [Targets](https://pulp-platform.github.io/cheshire/tg).
+* For detailed information on Cheshire's inner workings, consult the [User Manual](https://pulp-platform.github.io/cheshire/um/).
 
-To build different parts of the project, run `make` followed by these targets:
-
-* `hw-all`: generated hardware, including IPs and boot ROM
-* `sw-all`: software running on our hardware
-* `sim-all`(†): scripts and external models for simulation
-* `xilinx-all`: scripts for Xilinx FPGA implementation
-
-† *`sim-all` will download externally provided peripheral simulation models, some proprietary and with non-free license terms, from their publically accessible sources; see `Makefile` for details. By running `sim-all` or the default target `all`, you accept this.*
-
-Running `hw-all` is *required* at least once to correctly configure IPs we depend on. On reconfiguring any generated hardware or changing IP versions, `hw-all` should be rerun.
-
-To run all build targets above (†):
+If you are impatient and have all needed [dependencies](https://pulp-platform.github.io/cheshire/gs/#dependencies), you can run `make all`, then start QuestaSim in `target/sim/vsim` and run a [simulation](https://pulp-platform.github.io/cheshire/tg/sim) by typing:
 
 ```
-make all
+set BINARY ../../../sw/tests/helloworld.spm.elf
+source compile.tcl
+source start.cheshire_soc.tcl
+run -all
 ```
 
-If you have access to our internal servers, you can run `make nonfree-init` to fetch additional resources we cannot make publically accessible. Note that these are *not required* to use anything provided in this repository.
-
 ## License
 
 Unless specified otherwise in the respective file headers, all code checked into this repository is made available under a permissive license. All hardware sources and tool scripts are licensed under the Solderpad Hardware License 0.51 (see `LICENSE`) with the exception of generated register file code (e.g. `hw/regs/*.sv`), which is generated by a fork of lowRISC's [`regtool`](https://github.com/lowRISC/opentitan/blob/master/util/regtool.py) and licensed under Apache 2.0. All software sources are licensed under Apache 2.0.
+
+
+## Publication
+
+If you use Cheshire in your work, you can cite us:
+
+```
+@misc{ottaviano2023cheshire,
+      title         = {Cheshire: A Lightweight, Linux-Capable RISC-V Host
+                       Platform for Domain-Specific Accelerator Plug-In},
+      author        = {Alessandro Ottaviano and Thomas Benz and
+                       Paul Scheffler and Luca Benini},
+      year          = {2023},
+      eprint        = {2305.04760},
+      archivePrefix = {arXiv},
+      primaryClass  = {cs.AR}
+}
+```

docs/gs.md

@@ -0,0 +1,63 @@
+# Getting Started
+
+We first discuss the Cheshire's project structure, its dependencies, and how to build it.
+
+## Repository structure
+
+The project is structured as follows:
+
+| Directory | Description                              | Documentation              |
+| --------- | ---------------------------------------- | ---------------------------|
+| `hw`      | Hardware sources as SystemVerilog RTL    | [Architecture](um/arch.md) |
+| `sw`      | Software stack, build setup, and tests   | [Software Stack](um/sw.md) |
+| `target`  | Simulation, FPGA, and ASIC target setups | [Targets](tg/index.md)     |
+| `util`    | Utility scripts                          |                            |
+| `doc`     | Documentation                            | [Home](index.md)           |
+
+
+## Dependencies
+
+To *build* Cheshire, you will need:
+
+- GNU Make `>= 3.82`
+- Python `>= 3.9`
+- Bender `>= 0.27.1`
+- RISCV GCC `>= 11.2.0`
+- Python packages in `requirements.txt`
+
+We use [Bender](https://github.com/pulp-platform/bender) for hardware IP and dependency management; for more information on using Bender, please see its documentation. You can install Bender directly through the Rust package manager Cargo:
+
+```
+cargo install bender
+```
+
+Depending on your desired target, additional dependencies may be needed.
+
+## Building Cheshire
+
+To build different parts of Cheshire, run `make` followed by these targets:
+
+- `hw-all`: generated hardware, including IPs and boot ROM
+- `sw-all`: software running on our hardware
+- `sim-all`(†): scripts and external models for simulation
+- `xilinx-all`: scripts for Xilinx FPGA implementation
+
+† *`sim-all` will download externally provided peripheral simulation models, some proprietary and with non-free license terms, from their publically accessible sources; see `Makefile` for details. By running `sim-all` or the default target `all`, you accept this.*
+
+Running `hw-all` is *required* at least once to correctly configure IPs we depend on. On reconfiguring any generated hardware or changing IP versions, `hw-all` should be rerun.
+
+To run all build targets above (†):
+
+```
+make all
+```
+
+The following additional targets are not invoked by the above, but also available:
+
+- `bootrom-all`: Rebuilds the boot ROM. This is not done by default as reproducible builds (as checked by CI) can only be guaranteed for fixed compiler versions.
+- `nonfree-init`: Clones our internal repository with nonfree resources we cannot release, including our internal CI. *This is not necessary to use Cheshire*.
+- `clean-deps`: Removes checked-out bender dependencies and submodules. This is useful when references to dependencies are updated.
+
+## Targets
+
+A *target* is an end use for Cheshire. Each target requires different steps from here; read the page for your desired target in the following [Targets](tg/index.md) chapter.