Skip to content

Commit

Permalink
doc: First work on full documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@paulsc96
paulsc96 committed Jul 20, 2023
1 parent 306acf4 commit c07a151
Show file tree
Hide file tree
Showing 15 changed files with 427 additions and 199 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
36 changes: 36 additions & 0 deletions .github/workflows/publish-docs.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# 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:
# TODO: set this to main
branches: [ aottaviano/update-readme ]
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
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ nonfree/
# Dependency files
.bender/

# Documentation site
site/

# Software build files
*.bin
*.dump
Expand Down
223 changes: 25 additions & 198 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,215 +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 started in 2013.
Cheshire is a minimal Linux-capable host platform built around the RISC-V [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.
## Getting started

## Build the platform
* To learn how to build and use Cheshire, see [Getting Started](gs.md).
* To learn about available simulation, FPGA, and ASIC targets, see [Targets](tg/index.md).
* For detailed information on Cheshire's inner workings, consult the [User Manual](um/index.md).

We rely on [`bender`](https://github.com/pulp-platform/bender) as IP dependency
tool. Please follow the instructions in the `bender` repository for instalation
guidelines.

To build different parts of the project, run `make` followed by these targets:

* `hw-all`: generated hardware IPs. 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.
* `bootrom-all`[^1]: generated boot ROM
* `sw-all`[^1]: software running on our hardware
* `sim-all`[^2]: scripts and external models for simulation
* `xilinx-all`: scripts for Xilinx FPGA implementation

[^1] `bootrom-all` and `sw-all` demand RV64 gcc compiler, and is required to add
it to the `PATH` variable:

```
export PATH=<path_to_your_rv64_gcc_compiler>/bin:$PATH
```

If you have access to our internal servers, you can use:
If you are impatient and have all needed [dependencies](gs.md#Dependencies), you can run `make all`, then start QuestaSim in `target/sim/vsim` and run:

```
export PATH=/usr/pack/riscv-1.0-kgf/riscv64-gcc-11.2.0/bin:$PATH
set BINARY ../../../sw/tests/helloworld.spm.elf
source compile.tcl
source start.cheshire_soc.tcl
run -all
```

[^2] `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.*


To run all build targets above:

```
make 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.


## Add your own C/C++ code

Cheshire is a general-purpose system in its minimal single-core configuration.
The steps described below allows you to add your own code in embedded C/C++ and
compile it for the Cheshire platform.

From the root of the repository, go in the `sw/tests` directory.

`cd sw/tests`

Add the C/C++ sources of your application.

Compile the code from the root of the repository (remember to set the compiler path as explained in [^1]):

`make sw-all`

This will create the executable (`.elf`) and disassembly (`.dump`) of your code
in the `sw/tests` directory. The executable serves as input for both the RTL-
and FPGA-based simulations, as explained below.

### Caveat: Compiling for RTL or FPGA simulations

Currently, an application code requires to differentiate the baudrate of the
UART to display characters between RTL to FPGA simulation.

When compiling code for RTL simulation, in your C file use:

`init_uart(200000000, 115200);`

While for FPGA simulation, use

`init_uart(50000000, 115200);`

## Start an RTL simulation

Cycle-accurate RTL simulation of bare-metal user code in C is currently
performed with Mentor Questasim as default simulation target. Cheshire is
instantiated as Device Under Test (DUT) in a testbench environment. The
testbench controls the preloading of user executable you compiled in the
previous step in Cheshire's on-chip SRAM memory through chip-like IO interfaces,
such as JTAG or the faster Serial Link. Subsequently, the testbench drives the
booting process and monitors a specific memory-mapped register in the SoC (end
of computation register, EOC), which stores the return value of the user code
and signals the end of the execution.

From the root of the repository, type:

```
cd target/sim/vsim
vsim &
```

From the Questasim GUI, type:

```
vsim> source ./compile.cheshire_soc.tcl
vsim> set BINARY ../../../sw/tests/<your_binary.elf>
vsim> set TESTBENCH tb_cheshire_soc
vsim> source ./start.cheshire_soc.tcl`
```

## FPGA prototyping

FPGA mapping of the SoC for both bare-metal and Linux-driven operation modes
currently targets `Xilinx Genesys II` with `Xilinx Vivado`. We rely on
`Vitis-2022.1`, but other versions can be used.

### FPGA synthesis and implementation

To synthesize and implement the design for the target board, from the root of the repository type:

```
make -C target/xilinx
```

This will generate the bitstream of the Cheshire SoC with `Xilinx Vivado` in batch
mode.

### FPGA user code simulation

We distinguish between simple bare-metal and Linux-driven simulations. The
former allows code inspection and debugging with GDB, but is restricted to user
(U) and machine (M) privilege modes of the CVA6. The second relies on OpenSBI to
boot Linux and enjoy full kernel-space control of the platform.

#### Bare-metal simulation

Similarly to what described for the RTL simulation, we preload Cheshire's
on-chip SRAM with the executable code. We rely on GDB and OpenOCD to bridge the
JTAG IO interface of the SoC with the user.

#### Program the FPGA with Cheshire SoC

Connect the board to your local machine and open the Vivado project generated
when synthesizing and implementing the platform on the FPGA. From the root of
the repository:

```
cd target/xilinx
vitis-2022.1 vivado cheshire.xpr -nojournal -mode batch -source scripts/pragram.tcl
```

#### Connect GDB to the board with OpenOCD

Set the OpenOCD bridge. Open a new terminal and type:

```
openocd -f $(bender path ariane)/corev_apu/fpga/ariane.cfg
```

Connect GDB through OpenOCD. Open a second terminal and make sure the cRV64 gcc
compiler is still in your `PATH` as in [^1]. Type:

```
riscv64-unknown-elf-gdb -ex "target extended-remote localhost:3333"
```
## License

Display Cheshire's UART stdout through the UART/USB interface. Connect the
UART/USB of the board (e.g., the `Digilent Genesys II`) to a USB port of your
local machine. Then open a third terminal and type:
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.

```
minicom -D /dev/ttyUSBX
```

Where `X` is the USB port of your local machine.
## Publication

You are now ready to preload code in GDB and have fun. From the GDB shell (the
second of the three you opened)
If you use Cheshire in your work, you can cite us:

```
gdb> load <path to your .elf executable>
gdb> continue
@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}
}
```

### Repository structure

The root repository is structured as follows:

| Directory | Description | Documentation |
| --- | --- | --- |
| `hw` | Contains the hardware top-level sources in SystemVerilog. | [hw/README.md](http://./hw) |
| `sw` | Contains the main dependencies of the software stack, the CVA6 SDK (as a submodule), and user tests. | [sw/README.md](http://./sw) |
| `target` | Contains simulation, FPGA and ASIC targets. | [target/README.md](http://./target) |
| `util` | Contains several utilities such as bootrom generation script, linters and licence checkers. | [util/README.md](http://./util) |

## 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.
Loading

0 comments on commit c07a151

Please sign in to comment.