-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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]>
- Loading branch information
Showing
21 changed files
with
2,659 additions
and
28 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,6 +11,9 @@ nonfree/ | |
# Dependency files | ||
.bender/ | ||
|
||
# Documentation site | ||
site/ | ||
|
||
# Software build files | ||
*.bin | ||
*.dump | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.