docs: Added skeleton and FPGA targets

pulp-platform · Dec 6, 2023 · a4b64e6 · a4b64e6
1 parent bb9e8ac
commit a4b64e6
Show file tree

Hide file tree

Showing 11 changed files with 487 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # Carfield
 
-This repository hosts the Carfield SoC platform, a mixed-criticality SoC
-targeting the automotive domain. It uses
-[`Cheshire`](https://github.com/pulp-platform/cheshire) as main host domain. It
-is developed as part of the PULP project, a joint effort between ETH Zurich and
+This repository contains the RTL of the Carfield SoC platform, a mixed-criticality SoC
+targeting the automotive domain. It uses [`Cheshire`](https://github.com/pulp-platform/cheshire)
+as main host domain.
+Carfiel has been developed as part of the PULP project, a joint effort between ETH Zurich and
 the University of Bologna.
 
 ## Disclaimer
@@ -12,104 +12,6 @@ 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.
 
-## Dependencies
-To handle project dependencies, you can use
-[bender](https://github.com/pulp-platform/bender).
-
-## Carfield Initialization
-To initialize Carfield, do the following:
-* Execute the command:
-
-   ```
-   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.
-
-* Check that you have a RISCV toolchain for both RV64 and RV32 ISAs. For ETH, type:
-   ```
-   source scripts/env-iis.sh
-   ```
-
-## Simulation
-
-Follow these steps to launch a Carfield simulation:
-
-### 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.
-
 ## License
 
 Unless specified otherwise in the respective file headers, all code checked into

diff --git a/docs/gs.md b/docs/gs.md
@@ -0,0 +1,72 @@
+# 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
+```
+
+*Note: `car-init` 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 `car-init` or the default target `all`, you accept this.*
+
+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.
+
+
+This will create the following symbolic links to the main IPs local repositories : `cheshire`, `pulp_cluster`, `safety-island` and `spatz`,
+
+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.
diff --git a/docs/img/arch.svg b/docs/img/arch.svg
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/tg/index.md b/docs/tg/index.md
@@ -0,0 +1,14 @@
+# 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)
diff --git a/docs/tg/sim.md b/docs/tg/sim.md
@@ -0,0 +1,95 @@
+# Simulation
+
+## Carfield Initialization
+To initialize Carfield, do the following:
+* Execute the command:
+
+   ```
+   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.
+
+* Check that you have a RISCV toolchain for both RV64 and RV32 ISAs. For ETH, type:
+   ```
+   source scripts/env-iis.sh
+   ```
+
+## Simulation
+
+Follow these steps to launch a Carfield simulation:
+
+### 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.