-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #242 from pulp-platform/cykoenig/docs
docs: Add FPGA
- Loading branch information
Showing
6 changed files
with
556 additions
and
97 deletions.
There are no files selected for viewing
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 |
|---|---|---|
| @@ -1 +1,104 @@ | ||
| # TODO | ||
| # Getting Started | ||
|
|
||
| We first discuss the Carfield's project structure, its dependencies, and how to | ||
| build it. | ||
|
|
||
| ## Cheshire documentation | ||
|
|
||
| Carfield relies on Cheshire, our 64-bit RISC-V host SoC. Please follow the | ||
| [Cheshire documentation](https://pulp-platform.github.io/cheshire/gs/) for more | ||
| details concerning the host and Linux. | ||
|
|
||
| ## Repository structure | ||
|
|
||
| The project is structured as follows: | ||
|
|
||
| | Directory | Description | Documentation | | ||
| | --------- | ------------------------------------------ | --------------------- | | ||
| | `doc` | Documentation | [Home](index.md) | | ||
| | `hw` | Hardware sources as SystemVerilog RTL | todo | | ||
| | `scripts` | Some helper scripts for bash and EDA tools | | | ||
| | `sw` | Software stack, build setup, and tests | todo | | ||
| | `target` | Simulation, FPGA, and ASIC target setups | [Targets](tg/index.md) | | ||
| | `tb` | Testbench sources as SystemVerilog RTL | | | ||
| | `utils` | Utility scripts | | | ||
|
|
||
| ## Dependencies | ||
|
|
||
| To *build* Carfield, 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 Carfield | ||
|
|
||
| You first need to fetch and generate software and hardware sources for all the | ||
| IPs. | ||
| Run the following command: | ||
|
|
||
| ```bash | ||
| make car-init | ||
| ``` | ||
|
|
||
| It will take care of: | ||
|
|
||
| 1. Clone all the Carfield dependencies; | ||
| 2. Initialize the [Cheshire SoC](https://github.com/pulp-platform/cheshire). | ||
| This can be done separately by running `make chs-init` | ||
| 3. Downloads the Hyperram models from the iis-gitlab. If you don't have access | ||
| to it, you can also download the freely-available Hyperram models from | ||
| [here](https://www.cypress.com/documentation/models/verilog/s27kl0641-s27ks0641- | ||
| verilog) and unzip them according to the bender. | ||
| 4. Create the following symbolic links to the main IPs local repositories : | ||
| `cheshire`, `pulp_cluster`, `safety-island` and `spatz`, | ||
|
|
||
|
|
||
| Check that you have a RISCV toolchain for both RV64 and RV32 ISAs. For ETH, | ||
| type: | ||
| ``` | ||
| source scripts/env-iis.sh | ||
| ``` | ||
|
|
||
| Running `car-init` is *required* at least once to correctly configure IPs we | ||
| depend on. On reconfiguring any generated hardware or changing IP versions, | ||
| `car-init` should be rerun. | ||
|
|
||
| To build different parts of Carfield, the `carfield.mk` Makefile defines the | ||
| following targets (example usages will be given in [Targets](tg/index.md)): | ||
|
|
||
| - `car-hw-build` - generated hardware, including IPs and boot ROM | ||
| - `car-sw-build` - all the software target all the islands | ||
| - `car-hw-sim` - scripts and external models for simulation | ||
| - `car-xil-all` - build FPGA bitstream | ||
|
|
||
| The following additional targets are not invoked by the above, but also | ||
| available: | ||
|
|
||
| - `chs-bootrom-all` - rebuilds Cheshire's boot ROM. This is not done by default | ||
| as reproducible builds (as checked by CI) can only be guaranteed for fixed | ||
| compiler versions. | ||
| - *Note that all the host related targets are available with chs-\* and | ||
| documented in Cheshire's documentation.* | ||
| - `nonfree-init` - clones our internal repository with nonfree resources we | ||
| cannot release, including our internal CI. *This is not necessary to use | ||
| Carfield*. | ||
|
|
||
| ## Targets | ||
|
|
||
| A *target* is an end use for Carfield. Each target requires different steps | ||
| from here; read the page for your desired target in the following | ||
| [Targets](tg/index.md) chapter. |
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,17 @@ | ||
| # Targets | ||
|
|
||
| A *target* refers to an end use of Carfield. This could be a simulation setup, | ||
| an FPGA or ASIC implementation, or the integration into other SoCs. | ||
|
|
||
| Target setups can either be *included* in this repository or live in an | ||
| *external* repository and use Cheshire as a dependency. | ||
|
|
||
| ## Included Targets | ||
|
|
||
| Included target setups live in the `target` directory. The associated make | ||
| targets `<target>-all` set up necessary resources and scripts before use. | ||
|
|
||
| Each included target has a *documentation page* in this chapter: | ||
|
|
||
| - [Simulation](sim.md) | ||
| - [Xilinx FPGAs](xilinx.md) |
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,85 @@ | ||
| # Simulation | ||
|
|
||
| This page describes how to simulate Carfield to execute baremetal programs. | ||
| Please first read [Getting Started](../gs.md) to make sure have all the | ||
| dependencies and initialized your repository. | ||
|
|
||
| ### Compile HW and SW | ||
|
|
||
| * Generate the compile scripts for Questasim and compile Carfield. | ||
|
|
||
| ``` | ||
| make car-hw-build | ||
| ``` | ||
|
|
||
| It is also possible to run `make -B scripts/carfield_compile.tcl` to | ||
| re-generate the compile script after hardware modfications. | ||
|
|
||
| * Compile tests for Carfield. Tests resides in `sw/tests`. | ||
|
|
||
| ``` | ||
| make car-sw-build | ||
| ``` | ||
|
|
||
| The latter commands: | ||
| * Compiles safety island and pulp cluster standalone tests | ||
| * Compiles CVA6 standalone and offloading tests | ||
|
|
||
| ### System bootmodes | ||
|
|
||
| * The current supported bootmodes from Cheshire are: | ||
|
|
||
| | `CHS_BOOTMODE` | `CHS_PRELMODE` | Action | | ||
| | --- | --- | --- | | ||
| | 0 | 0 | Passive bootmode, JTAG preload | | ||
| | 0 | 1 | Passive bootmode, Serial Link preload | | ||
| | 0 | 2 | Passive bootmode, UART preload | | ||
| | 0 | 3 | Passive bootmode, Secure Boot from SECD | | ||
| | 1 | - | Autonomous bootmode, SPI SD card | | ||
| | 2 | - | Autonomous bootmode, SPI flash | | ||
| | 3 | - | Autonomous bootmode, I2C EEPROM | | ||
|
|
||
| `Bootmode` indicates the available bootmodes in Cheshire, while `Preload | ||
| mode` indicates the type | ||
| of preload, if any is needed. For RTL simulation, bootmodes 0, 2 and 3 are | ||
| supported. SPI SD card | ||
| bootmode is supported on FPGA emulation. | ||
|
|
||
| * The current supported bootmodes for the Safety Island are: | ||
|
|
||
| | `SAFED_BOOTMODE` | Action | | ||
| | --- | --- | | ||
| | 0 | Passive bootmode, JTAG preload | | ||
| | 1 | Passive bootmode, Serial Link preload | | ||
|
|
||
| ### Simulation | ||
|
|
||
| To launch an RTL simulation with the selected boot/preload modes for the island | ||
| of choice, type: | ||
|
|
||
|
|
||
| * For cheshire in passive bootmode (`CHS_BOOTMODE=0`), set `CHS_BINARY` for | ||
| Cheshire | ||
|
|
||
| ``` | ||
| make car-hw-sim CHS_BOOTMODE=<chs_bootmode> CHS_PRELMODE=<chs_prelmode> | ||
| CHS_BINARY=<chs_binary_path>.car.elf PULPCL_BINARY=<pulpcl_binary> | ||
| SPATZCL_BINARY=<spatzcl_binary> SECD_BINARY=<secd_binary_path> | ||
| SAFED_BOOTMODE=<safed_bootmode> SAFED_BINARY=<safed_binary_path> | ||
| ``` | ||
|
|
||
| * For cheshire in autonomous bootmode (`CHS_BOOTMODE` = {1,2,3}), set | ||
| `CHS_IMAGE` for Cheshire | ||
|
|
||
| ``` | ||
| make car-hw-sim CHS_BOOTMODE=<chs_bootmode> CHS_PRELMODE=<chs_prelmode> | ||
| CHS_IMAGE=<chs_binary_path>.car.memh PULPCL_BINARY=<pulpcl_binary> | ||
| SPATZCL_BINARY=<spatzcl_binary> SECD_BINARY=<secd_binary_path> | ||
| SAFED_BOOTMODE=<safed_bootmode> SAFED_BINARY=<safed_binary_path> | ||
| ``` | ||
|
|
||
| ### Debugging | ||
|
|
||
| Per default, Questasim compilation is performance-optimised and simulation | ||
| logging is disabled. To enable full visibility, logging, and the Questa GUI, | ||
| set `DEBUG=1` when executing the steps above. |
Oops, something went wrong.