Merge pull request #237 from pulp-platform/aottaviano/docs

Add documentation and rework tree structure

.github/workflows/publish-docs.yml

@@ -0,0 +1,35 @@
+# 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:
+    branches: [ main ]
+  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

.gitignore

@@ -1,19 +1,16 @@
 .bender
 cheshire
 spatz
-modelsim.ini
-scripts/carfield_compile.tcl
-tb/hyp_vip
-transcript
-work/
 *.log
 *.wlf
 /.venv/
 /logs/
 /working_dir/
-/uart
 /stdout
 
+# Documentation site
+site/
+
 # sw auto-generated
 sw/tests/bare-metal/safed/*.h
 sw/tests/bare-metal/pulpd/*.h
@@ -155,7 +152,6 @@ celerybeat.pid
 # Environments
 .env
 .venv
-env/
 venv/
 ENV/
 env.bak/

Bender.yml

@@ -28,7 +28,6 @@ dependencies:
   pulp-ethernet:      { git: https://github.com/pulp-platform/pulp-ethernet.git,        rev: bdc8031ab270a49da28df269266ce9ab9a133636 } # branch: carfield
   riscv-dbg:          { git: https://github.com/pulp-platform/riscv-dbg.git,            version: =0.8.0                               }
 
-
 workspace:
   package_links:
     cheshire: cheshire
@@ -55,18 +54,18 @@ sources:
 
   - target: test
     files:
-      - tb/hyp_vip/s27ks0641.v
-      - tb/vip_carfield_soc.sv
-      - tb/carfield_fix.sv
-      - tb/carfield_tb.sv
+      - target/sim/src/hyp_vip/s27ks0641.v
+      - target/sim/src/vip_carfield_soc.sv
+      - target/sim/src/carfield_fix.sv
+      - target/sim/src/carfield_tb.sv
 
   - target: spyglass
     files:
-      - scripts/spyglass/src/carfield_wrap.sv
+      - utils/lint/spyglass/src/carfield_wrap.sv
 
   - target: all(synthesis, not(fpga))
     files:
-      - target/synth/carfield_synth_wrap.sv
+      - target/synth/src/carfield_synth_wrap.sv
 
   - target: all(xilinx, fpga, xilinx_vanilla)
     files:

README.md

@@ -1,122 +1,68 @@
 # 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
-the University of Bologna.
+Carfield is an open-research heterogeneous platform for safety, resilient and time-predictable systems. Originally conceived as automotive-oriented SoC, the high configurability of the platform makes it tunable to target a broader class of mixed-criticality applications' domains, such as automotive, space or industry.
 
-## Disclaimer
+Carfield 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.
+## Motivation
 
-## Dependencies
-To handle project dependencies, you can use
-[bender](https://github.com/pulp-platform/bender).
+The rapid evolution of AI algorithms and the massive amount of sensed data across
+application-domains such as Automotive, Space and Cyber-Physical embedded systems (CPSs), call for a
+*paradigm shift* in the design of **next generation of mixed-criticality systems (MCSs)**, from
+simple micro-controllers towards powerful and heterogeneous edge computers.
 
-## Carfield Initialization
-To initialize Carfield, do the following:
-* Execute the command:
+These must not only deliver outstanding performance and energy efficiency but also ensure steadfast
+safety, resilience, and security.
 
-   ```
-   make car-init
-   ```
+The Carfield platform aims to tackle these architectural challenges establishing itself as a
+pre-competitive heterogeneous platform for MCSs, underpinned by **fully open-source Intellectual
+Properties (IPs)**.
 
-   It will take care of:
+Carfield showcases pioneering hardware solutions, addressing challenges related to time-predictable
+on/off-chip communication, robust fault recovery mechanisms, secure boot processes, cryptographic
+acceleration services, hardware-assisted virtualization, and accelerated computation for both
+floating-point and integer workloads.
 
-   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.
+## Quick Start
 
-* Check that you have a RISCV toolchain for both RV64 and RV32 ISAs. For ETH, type:
-   ```
-   source scripts/env-iis.sh
-   ```
+* To learn how to build and use Carfield, see [Getting
+  Started](https://pulp-platform.github.io/carfield/gs/).
+* To learn about available simulation, FPGA, and ASIC targets, see
+  [Targets](https://pulp-platform.github.io/carfield/tg).
+* For detailed information on Carfield's inner workings, consult the [User
+  Manual](https://pulp-platform.github.io/carfield/um/).
 
-## 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
+If you are impatient and have all needed
+[dependencies](https://pulp-platform.github.io/carfield/gs/#dependencies), type:
 
 ```
-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>
+make car-all
 ```
 
-* For cheshire in autonomous bootmode (`CHS_BOOTMODE` = {1,2,3}), set `CHS_IMAGE` for Cheshire
+and then run a [simulation](https://pulp-platform.github.io/carfield/tg/sim) with Questasim by
+typing:
 
+```tcl
+make car-vsim-sim-build
+make car-vsim-sim-run CHS_BINARY=./sw/tests/bare-metal/hostd/helloworld.car.l2.elf
 ```
-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
+---
+
+To display the main *Make* build targets and their usage, from the root repository type:
+
+```tcl
+make help
+```
 
-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.
+The Make files are autodocumented.
 
 ## 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.
+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.