diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index dd9557c8..691d5878 100644 --- a/.github/workflows/build.yml +++ b/.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 diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 00000000..a28a3235 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -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 + +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 diff --git a/.gitignore b/.gitignore index 05d7eeb2..6ff6a9bf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,9 @@ nonfree/ # Dependency files .bender/ +# Documentation site +site/ + # Software build files *.bin *.dump diff --git a/README.md b/README.md index 1b066eea..893c5c45 100644 --- a/README.md +++ b/README.md @@ -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=/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/ -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 -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. diff --git a/docs/STUFF.md b/docs/STUFF.md new file mode 100644 index 00000000..f8baec53 --- /dev/null +++ b/docs/STUFF.md @@ -0,0 +1,205 @@ +# 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. + + +## Build + +We rely on [`bender`](https://github.com/pulp-platform/bender) as IP and dependency tool. Please refer to its repository for more information. + +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=/bin:$PATH +``` + +If you have access to our internal servers, you can use: + +``` +export PATH=/usr/pack/riscv-1.0-kgf/riscv64-gcc-11.2.0/bin:$PATH +``` + +[^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/ +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" +``` + +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: + +``` +minicom -D /dev/ttyUSBX +``` + +Where `X` is the USB port of your local machine. + +You are now ready to preload code in GDB and have fun. From the GDB shell (the +second of the three you opened) + +``` +gdb> load +gdb> continue +``` + +### 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. diff --git a/docs/gs.md b/docs/gs.md new file mode 100644 index 00000000..5499a938 --- /dev/null +++ b/docs/gs.md @@ -0,0 +1,58 @@ +# Getting Started + +First, we discuss the Cheshire's project structure, its build dependencies, and how to build different parts of 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](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` +- Bender `>= 0.27.1` +- Python `>= 3.9` +- Python packages in `requirements.txt` +- RISCV GCC `>= 11.2.0` + +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 if references to dependencies are updated. + +## Targets + +A *target* refers to an end use of Cheshire, be it in simulation, FPGA implementation, or ASIC integration. Your next steps will depend on your desired target; see the [Targets](tg/index.md) chapter for more information. + diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/tg/index.md b/docs/tg/index.md new file mode 100644 index 00000000..c46d918f --- /dev/null +++ b/docs/tg/index.md @@ -0,0 +1,3 @@ +# Targets + +bla diff --git a/docs/tg/sim.md b/docs/tg/sim.md new file mode 100644 index 00000000..ac17f739 --- /dev/null +++ b/docs/tg/sim.md @@ -0,0 +1,46 @@ +# Simulation + +This page describes how to simulate Cheshire. Please first read [Getting Started](../gs.md) and make sure you built the hardware, software, and simulation scripts. + +In terms of simulators, we currently support: + +- Questa Advanced Simulator (QuestaSim) `>= 2022.3` + +We plan on supporting more simulators in the future. If your situation requires it, simulating Cheshire on other setups should be straightforward. + +## Testbench + +We provide a SystemVerilog testbench for `cheshire_soc` running bare-metal code. This code is either preloaded through simulated interface drivers or read from external memory models by the boot ROM and then executed, depending on how the `PRELMODE` and `BOOTMODE` variables are set: + + | `BOOTMODE` | `PRELMODE` | Action | + | - | - | --------------------------------- | + | 0 | 0 | Preload through JTAG | + | 0 | 1 | Preload through Serial Link | + | 0 | 2 | Preload through UART | + | 1 | - | Autonomous boot from SPI SD card | + | 2 | - | Autonomous boot from SPI flash | + | 3 | - | Autonomous boot from I2C EEPROM | + +Preloading boot modes expect an ELF executable to be passed through `BINARY`, while autonomous boot modes expect a disk image (GPT formatted or raw code) to be passed through `IMAGE`. For more information on how Cheshire boots, see [Boot Flow](../um/sw.md#Boot%20flow). + +For simulation of Cheshire in other designs, we provide the module `cheshire_vip` encapsulating all verification IP and its interfaces. + +## QuestaSim + +After building Cheshire, start QuestaSim in `target/sim/vsim` and run: + +```tcl +# We want to preload `helloworld` through serial link +set BINARY ../../../sw/tests/helloworld.spm.elf +set BOOTMODE 0 +set PRELMODE 1 + +# Compile design +source compile.tcl + +# Start and run simulation +source start.cheshire_soc.tcl +run -all +``` + +The design needs to be recompiled only when hardware is changed. The simulation can be restarted by re-sourcing `start.cheshire_soc.tcl`, allowing binary (or image) and load method changes beforehand. diff --git a/docs/tg/xilinx.md b/docs/tg/xilinx.md new file mode 100644 index 00000000..345ed8d5 --- /dev/null +++ b/docs/tg/xilinx.md @@ -0,0 +1,9 @@ +# Xilinx FGPAs + + + + + +For *FPGA emulation*, we currently support: + +- Digilent Genesys 2 with Vivado `>= 2020.2` diff --git a/docs/um/arch.md b/docs/um/arch.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/docs/um/arch.md @@ -0,0 +1 @@ +# Architecture diff --git a/docs/um/index.md b/docs/um/index.md new file mode 100644 index 00000000..ff2daf1e --- /dev/null +++ b/docs/um/index.md @@ -0,0 +1 @@ +# User Manual diff --git a/docs/um/sw.md b/docs/um/sw.md new file mode 100644 index 00000000..8766f267 --- /dev/null +++ b/docs/um/sw.md @@ -0,0 +1,5 @@ +# Software + +## Boot Flow + +## Linux diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..06390c74 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,31 @@ +# 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: Cheshire +theme: + name: material + icon: + repo: fontawesome/brands/github + features: + - navigation.expand + - navigation.tracking + #- navigation.tabs + - navigation.sections + - navigation.indexes + - navigation.footer + +repo_url: https://github.com/pulp-platform/cheshire +repo_name: pulp-platform/cheshire + +nav: +- Home: + - index.md + - Getting Started: gs.md +- Targets: + - tg/index.md + - Simulation: tg/sim.md + - Xilinx FPGAs: tg/xilinx.md +- User Manual: + - um/index.md + - Architecture: um/arch.md + - Software Stack: um/sw.md diff --git a/.github/requirements.txt b/requirements.txt similarity index 64% rename from .github/requirements.txt rename to requirements.txt index f9ccc251..06716f50 100644 --- a/.github/requirements.txt +++ b/requirements.txt @@ -4,3 +4,5 @@ mako pyyaml tabulate yapf +mkdocs +mkdocs-material