From a4b64e647f9f03c7e029d4b367c398c95635d78e Mon Sep 17 00:00:00 2001 From: Cyril Koenig Date: Wed, 6 Dec 2023 15:23:31 +0100 Subject: [PATCH] docs: Added skeleton and FPGA targets --- README.md | 106 +------------------- docs/gs.md | 72 ++++++++++++++ docs/img/arch.svg | 0 docs/index.md | 1 + docs/tg/index.md | 14 +++ docs/tg/sim.md | 95 ++++++++++++++++++ docs/tg/xilinx.md | 249 ++++++++++++++++++++++++++++++++++++++++++++++ docs/um/arch.md | 7 ++ docs/um/index.md | 6 ++ docs/um/sw.md | 1 + mkdocs.yml | 38 +++++++ 11 files changed, 487 insertions(+), 102 deletions(-) create mode 100644 docs/gs.md create mode 100644 docs/img/arch.svg create mode 120000 docs/index.md create mode 100644 docs/tg/index.md create mode 100644 docs/tg/sim.md create mode 100644 docs/tg/xilinx.md create mode 100644 docs/um/arch.md create mode 100644 docs/um/index.md create mode 100644 docs/um/sw.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 2212f3aee..90ad515d2 100644 --- 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_PRELMODE= CHS_BINARY=.car.elf PULPCL_BINARY= SPATZCL_BINARY= SECD_BINARY= SAFED_BOOTMODE= SAFED_BINARY= -``` - -* For cheshire in autonomous bootmode (`CHS_BOOTMODE` = {1,2,3}), set `CHS_IMAGE` for Cheshire - -``` -make car-hw-sim CHS_BOOTMODE= CHS_PRELMODE= CHS_IMAGE=.car.memh PULPCL_BINARY= SPATZCL_BINARY= SECD_BINARY= SAFED_BOOTMODE= SAFED_BINARY= -``` - -### 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 new file mode 100644 index 000000000..7df106e76 --- /dev/null +++ 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 new file mode 100644 index 000000000..e69de29bb diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 000000000..32d46ee88 --- /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 000000000..72179f870 --- /dev/null +++ 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 `-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 new file mode 100644 index 000000000..34cc29de5 --- /dev/null +++ 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_PRELMODE= CHS_BINARY=.car.elf PULPCL_BINARY= SPATZCL_BINARY= SECD_BINARY= SAFED_BOOTMODE= SAFED_BINARY= +``` + +* For cheshire in autonomous bootmode (`CHS_BOOTMODE` = {1,2,3}), set `CHS_IMAGE` for Cheshire + +``` +make car-hw-sim CHS_BOOTMODE= CHS_PRELMODE= CHS_IMAGE=.car.memh PULPCL_BINARY= SPATZCL_BINARY= SECD_BINARY= SAFED_BOOTMODE= SAFED_BINARY= +``` + +### 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. \ No newline at end of file diff --git a/docs/tg/xilinx.md b/docs/tg/xilinx.md new file mode 100644 index 000000000..44efcfa1b --- /dev/null +++ b/docs/tg/xilinx.md @@ -0,0 +1,249 @@ +# Xilinx FGPAs + +This page describes how to map Carfield on Xilinx FPGAs to *execute baremetal programs* or *boot CVA6 Linux*. Please first read [Getting Started](../gs.md) to make sure have all dependencies. Additionally, for on-chip debugging you need: + +- OpenOCD `>= 0.10.0` + +We currently provide working setups for: + +- Xilinx VCU128 with Vivado `>= 2020.2` + +We are working on support for more boards in the future. + +The Carfield bitstreams are divided in two flavors at the moment. The `flavor_vanilla` and the `flavor_bd`. + +- `flavor_vanilla` - The hardware to be mapped on the FPGA is fully described in System Verilog. This flow is lightweight, easily reproducible, and self contained. As each IP is integrated by hand in the RTL, only the Xilinx DDR, Xilinx VIO and Xilinx clock wizard are available (at the moment). +- `flavor_bd` - In order to allow for more complex top level, this flow relies on the Vivado block design flow to link Carfield with external IPs. This flow is less human readable but allows integrating more complex IPs as Xilinx Ethernet. *Note that this may require you to own the respective licenses.* + +## Building the vanilla bistream + +Due to the structure of the Makefile flow. All the following commands are to be executed at the root of the Carfield repository. If you want to see the Makefiles that you will be using, you can find the generic FPGA rules in `target/xilinx/xilinx.mk` and the vanilla specific rules in `target/xilinx/flavor_vanilla/flavor_vanilla.mk`. + +First, make sure that you have fetch and generated all the RTL: + +```bash +make car-init +``` + +Generate the bitstream in `target/xilinx/out/` by running: + +```bash +make car-xil-all XILINX_FLAVOR=vanilla [VIVADO=version] [VIVADO_MODE={batch,gui}] [XILINX_BOARD={vcu128}] [NO_HYPERBUS={0,1}] [GEN_EXT_JTAG={0,1}] [GEN_PULP_CLUSTER={0,1}] [GEN_SAFETY_ISLAND={0,1}] [GEN_SPATZ_CLUSTER={0,1}] [GEN_OPEN_TITAN={0,1}] +``` + +See the argument list below: + +| Argument | Relevance | Description | +|----------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------| +| VIVADO | all | Vivado command to use | +| XILINX_BOARD | all | `vcu128` | +| NO_HYPERBUS | all | `0` Use the hyperram controller inside `carfield.sv`
`1` Use the Xilinx DDR controller | +| GEN_EXT_JTAG | vcu128 | `0` Connect the JTAG debugger to the board's JTAG (see [vcu128](#xilinx-vcu128))
`1` Connect the JTAG debugger to an external JTAG chain | +| GEN_*[IP]* | all | `0` Replace the IP with an AXI error slave
`1` Instanciate the IP | +| VIVADO_MODE | all | `batch` Compile in Vivado shell
`gui` Compile in Vivado gui | + +See below some typical building time for reference: + +| IPs | Board | Duration | +|-------------------|--------|------------| +| PULP | vcu128 | xxhxxmin | +| SAFETY | vcu128 | xxhxxmin | +| SPATZ | vcu128 | xxhxxmin | +| PULP + SAFETY | vcu128 | xxhxxmin | + +You can find which sources are used by looking at `Bender.yml` (target `all(xilinx, fpga, xilinx_vanilla)`). This file is used by bender to generate `target/xilinx/flavor_vanilla/scripts/add_sources.tcl`. You can open this file to see all the file list of the project. (Note that even if you disable an IP, its files will still needed by Vivado and added to the `add_sources.tcl`). + +Note that the `make` command above will first compile the Xilinx ips located in `target/xilinx/xilinx_ips` before compiling the bitstream. + +## Building the bd (block design) bistream + +Please read and try to compile a vanilla bitstream first to identify potential issues. + +You can find the bd specific rules in `target/xilinx/flavor_vanilla/flavor_bd.mk`. + +Again, make sure that you have fetched and generated all the RTL: + +```bash +make car-init +``` + +Generate the bitstream in `target/xilinx/out/` by running: + +```bash +make car-xil-all XILINX_FLAVOR=bd [VIVADO=version] [VIVADO_MODE={batch,gui}] [XILINX_BOARD={vcu128}] [NO_HYPERBUS={0,1}] [GEN_EXT_JTAG={0,1}] [GEN_PULP_CLUSTER={0,1}] [GEN_SAFETY_ISLAND={0,1}] [GEN_SPATZ_CLUSTER={0,1}] [GEN_OPEN_TITAN={0,1}] +``` + +See the argument list below: + +| Argument | Relevance | Description | +|----------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------| +| VIVADO | all | Vivado command to use | +| XILINX_BOARD | all | `vcu128` | +| NO_HYPERBUS | all | `0` Use the hyperram controller inside `carfield.sv`
`1` Use the Xilinx DDR controller | +| GEN_EXT_JTAG | vcu128 | `0` Connect the JTAG debugger to the board's JTAG (see [vcu128](#xilinx-vcu128))
`1` Connect the JTAG debugger to an external JTAG chain | +| GEN_*[IP]* | all | `0` Replace the IP with an AXI error slave
`1` Instanciate the IP | +| VIVADO_MODE | all | `batch` Compile in Vivado shell
`gui` Compile in Vivado gui | + +See below some typical building time for reference: + +| IPs | Board | Duration | +|-------------------|--------|------------| +| PULP | vcu128 | xxhxxmin | +| SAFETY | vcu128 | xxhxxmin | +| SPATZ | vcu128 | xxhxxmin | +| PULP + SAFETY | vcu128 | xxhxxmin | + +You can find which sources are used by looking at `Bender.yml` (target `all(xilinx, fpga, xilinx_bd)`). This file is used by bender to generate `target/xilinx/flavor_bd/scripts/add_sources.tcl`. You can open this file to see all the file list of the project. (Note that even if you disable an IP, its files will still needed by Vivado and added to the `add_sources.tcl`). + +Note that the `make` command above will first package a Carfield ip before compiling the bitstream. + +## Board specificities + +### Xilinx VCU128 +> #### Bootmodes and VIOs +> +> As there are no switches on this board, the CVA6 bootmode (see [Cheshire bootrom](https://pulp-platform.github.io/cheshire/um/sw/#boot-rom)) is selected by Xilinx VIOs that can be set in the Vivado GUI (see [Using Vivado GUI](#bringup_vivado_gui)). +> +> #### External JTAG chain +> +> The VCU128 development board only provides one JTAG chain, used by Vivado to program the bitstream, and interact with certain Xilinx IPs (ILAs, VIOs, ...). The RV64 requires access to a JTAG chain to connect GDB to the debug-module in the bitstream. + +> When using `EXT_JTAG=0` it is possible to connect the debug module to the internal FPGA's JTAG by using the Xilinx BSCANE macro. With this, you will only need the normal Xilinx USB cable to interact with CVA6. Note that it means that Vivado and OpenOCD can not use the same cable at the same time. +>**WARNING: this setup (with `EXT_JTAG=0`) will only work for designs containing the host only** as it is not possible to chain multiple devices on the BSCANE macro. If you need to use `EXT_JTAG=0` consider modifying the RTL to remove the debug modules of the IPs. + +> When using `EXT_JTAG=1` we add an external JTAG chain for the RV64 host and other island through the FPGA's GPIOs. Since the VCU128 does not have GPIOs we use we use a Digilent JTAG-HS2 cable connected to the Xilinx XM105 FMC debug card. See the connections in `vcu128.xdc`. + +## Bare-metal bringup + +### Programming the FPGA + +#### Using Vivado GUI + +If you have closed Vivado, or compiled in batch mode, you can open the Vivado GUI: + +```bash +# Find your project +find . -name "*.xpr" +# Open it in gui +vitis-2020.2 vivado project.xpr +``` + +You can now open the Hardware Manager and program the FPGA. Once done, Vivado will give you access the to Virtual Inputs Outputs (VIOs). You can now assert the following signals (on Cheshire top level). + + | VIO | Function | + | ----------------- | ----------------------------------------------------------------| + | vio_reset | Positive edge-sensitive reset for the whole system | + | vio_boot_mode | Override the boot-mode switches described above | + | vio_boot_mode_sel | Select between 0: using boot mode switches 1: use boot mode VIO | + +#### Using command line + +A script `program.tcl` is available to flash the bitstream without opening Vivado GUI. You will need to give the following variable to access your board (see `target/xilinx/xilinx.mk`). + +- `XILINX_PORT` - Vivado opened port (default **3121**) +- `FPGA_PATH` - Vivado path to your FPGA (default **xilinx_tcf/Xilinx/[serial_id]**) +- `XILINX_HOST` - Path to your Vivado server (default **localhost**) + +Change the values to the appropriate ones (they be found in the Hardware Manager in Vivado GUI) and program the board: + +```bash +make chs-xil-program VIVADO_MODE=batch XILINX_BOARD=vcu128 XILINX_FLAVOR=flavor +``` + +### Loading binary and debugging with OpenOCD + +Tbd + +## Running Baremetal Code + +Tbd + +### JTAG Preloading + +Tbd + +## Booting Linux + +To boot Linux, we must load the *OpenSBI* firmware, which takes over M mode and launches the U-boot bootloader. U-boot then loads Linux. For more details, see [Boot Flow](../um/sw.md#boot-flow). + +Clone the `carfield` branch of CVA6 SDK at the root of this repository and build the firmware (OpenSBI + U-boot) and Linux images (*this will take about 30 minutes*): + +```bash +git clone https://github.com/pulp-platform/cva6-sdk.git --branch carfield +make -C cva6-sdk images +``` + +In principle, we can boot Linux through JTAG by loading all images into memory, launching OpenSBI, and instructing U-boot to load the kernel directly from memory. Here, we focus on autonomous boot from SD card or SPI flash. + +In this case, OpenSBI is loaded by a regular baremetal program called the Zero-Stage Loader (ZSL). The boot ROM loads the ZSL from SD card, which then loads the device tree and firmware from other SD card partitions into memory and launches OpenSBI. + +To create a full Linux disk image from the ZSL, device tree, firmware, and Linux, run: + +```bash +# Place the cva6-sdk where they are expected: +ln -s cva6-sdk/install64 sw/boot/install64 +# Optional: Pre-uild explicitely the image +make CAR_ROOT=. sw/boot/linux_carfield_bd_vcu128.gpt.bin +``` + +You can now recompile the board, it should start booting automatically! + +### Xilinx VCU128 +> +> This board does not offer a SD card reader. We need to load the image in the integrated flash: +> +> ``` +> make chs-xil-flash VIVADO_MODE=batch XILINX_BOARD=vcu128 XILINX_FLAVOR=flavor +> ``` +> +> Use the parameters defined in [Using command line](#bringup_vivado_cli) (defaults are in `target/xilinx/xilinx.mk`) to select your board: +> +> This script will erase your bitstream, once the flash has been written (c.a. 10min) you will need to re-program the bitstream on the board. + +## Add your own board + +If you wish to add a flow for a new FPGA board, please do the following steps: +_Please consider opening a pull request containing the necessary changes to integrate your new board (:_ + +### Makefile + +Add your board on top of `target/xilinx/xilinx.mk`, in particular `xilinx_part` and `xilinx_board_long` are identifying the FPGA chip and board (can be found in VIvado GUI). The parameters identifying your personal device `XILINX_PORT`, `XILINX_FPGA_PATH`, `XILINX_HOST` can be left empty for now. + +### Vanilla flow +> +> #### Re-arametrize existing IPs +> +> Carfield's emulation requires a few Vivado IPs to work properly. They are defined and pre-compiled in `target/xilinx/xilinx_ips/*`. +> If you add a new board, you will need to reconfigure your IPs for this board. For instance, to use the _Vivado MIG DDR4 controller_, modify `target/xilinx/xilinx_ips/xlnx_mig_ddr4/run.tcl`. There, add the relevant `$::env(XILINX_BOARD)` entry with your configuration. +> To know which configuration to use your board, you can open a blank project in Vivado GUI, create a blank block design, and instanciate the MIG DDR4 IP there. The Vivado TCL console should write the default parameters for your FPGA. You can later re-configure the IP in the block design and Vivado will print to the tcl console the modified parameters. Then you can copy these tcl lines to the `run.tcl` file. Make sure that you added your ip to `target/xilinx/flavor_vanilla/flavor_vanilla.mk` under "xilinx_ips_names_vanilla_**your_board**". +> +> #### Add a new IP +> +> If your board require a new IP that has not been integrated already do the following : +> +> - Add a new folder `target/xilinx/xilinx_ips/[your_ip]` taking the example of the `xlnx_mig_ddr4`. +> - Modify `target/xilinx/xilinx_ips/[your_ip]/tcl/run.tcl` and `target/xilinx/xilinx_ips/[your_ip]/Makefile` accordingly. +> - Add your IP to `target/flavor_vanilla/flavor_vanilla.mk` under "xilinx_ips_names_vanilla_**your_board**". +> +> #### Instantiate your IP +> +> Connect it's top module in the top-level: `target/xilinx/flavor_vanilla/src/cheshire_top_xilinx.sv`. If your IP is a DDR controller, please add it to `target/xilinx/src/dram_wrapper_xilinx.sv`. Note that this file contains a pipeline to resize AXI transactions from Cheshire to your controller. +> +> Add the relevant macro parameters to `target/xilinx/flavor_vanilla/src/phy_definitions.sv` in order to disable your IP for non-relevant boards. +> +> #### Add a new device tree +> +> Each board is defined by a device-tree, when adding a new board, please add a device tree in `sw/boot` for each supported flavors. +> +> #### Debug +> +> It is possible to use ILA (Integrated Logic Analyzers) in order to debug some signals on the running FPGA. Add the following before declaring your signals: +> +> ```verilog +> // Indicate that you need to debug a signal +> (* dont_touch = "yes" *) (* mark_debug = "true" *) logic signal_d0; +> // You can also use the following macro from phy_definitions.svh +> `ila(ila_signal_d0, signal_d0) +> ``` +> +> Then, re-build your bitstream. diff --git a/docs/um/arch.md b/docs/um/arch.md new file mode 100644 index 000000000..ccc904cff --- /dev/null +++ b/docs/um/arch.md @@ -0,0 +1,7 @@ +# Architecture + +Lorem ipsum. + +## Memory Map + +Lorem ipsum. \ No newline at end of file diff --git a/docs/um/index.md b/docs/um/index.md new file mode 100644 index 000000000..462b6d784 --- /dev/null +++ b/docs/um/index.md @@ -0,0 +1,6 @@ +# User Manual + +The *user manual* provides detailed reference information on Carfield: + +- [Architecture](arch.md): Describes the hardware design, features, and configuration of Carfield. +- [Software Stack](sw.md): Describes how to run code on Carfield. diff --git a/docs/um/sw.md b/docs/um/sw.md new file mode 100644 index 000000000..ab6200c12 --- /dev/null +++ b/docs/um/sw.md @@ -0,0 +1 @@ +# Software Stack diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..6a607b98d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,38 @@ +# 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: Carfield +theme: + name: material + icon: + repo: fontawesome/brands/github + features: + - navigation.expand + - navigation.tracking + - navigation.sections + - navigation.indexes + - navigation.footer + +markdown_extensions: + - markdown_grid_tables: + - toc: + toc_depth: 3 + +repo_url: https://github.com/pulp-platform/carfield +repo_name: pulp-platform/carfield + +nav: +- Home: + - index.md + - Getting Started: gs.md +- Targets: + - tg/index.md + - Simulation: tg/sim.md + - Xilinx FPGAs: tg/xilinx.md + - SoC Integration: tg/integr.md +- User Manual: + - um/index.md + - Architecture: um/arch.md + - Software Stack: um/sw.md +