doc: More work on documentation

pulp-platform · Aug 30, 2023 · 1e4f644 · 1e4f644
1 parent 9477023
commit 1e4f644
Show file tree

Hide file tree

Showing 8 changed files with 475 additions and 335 deletions.
diff --git a/docs/gs.md b/docs/gs.md
@@ -22,8 +22,8 @@ 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`
+- Python packages in `requirements.txt`
 
 Depending on your desired target, additional dependencies may be needed.
 

diff --git a/docs/img/arch.svg b/docs/img/arch.svg
diff --git a/docs/tg/integr.md b/docs/tg/integr.md
@@ -1,6 +1,6 @@
 # SoC Integration
 
-Cheshire is designed to be *highly configurable* and provide host and interconnect infrastructure for systems on various scales. Examples of SoCs integrating Cheshire are:
+Cheshire is designed to be *highly configurable* and provide host and interconnect infrastructure for systems on various scales. Examples of SoCs integrating Cheshire as a host are:
 
 - [Iguana](https://github.com/pulp-platform/iguana), an minimal end-to-end open-source Linux-capable SoC built with open tools.
 - [Carfield](https://github.com/pulp-platform/carfield), a mixed-criticality SoC targeting the automotive domain.
@@ -9,7 +9,7 @@ Cheshire is designed to be *highly configurable* and provide host and interconne
 
 As for internal targets, Cheshire *must be built* before use in external projects. We aim to simplify this as much as possible with a portable *make fragment*.
 
-If you use GNU Make to build your project and Bender to handle dependencies, you can include the Cheshire build system into your own Makefile with:
+If you use GNU Make to build your project and Bender to handle dependencies, you can include the Cheshire build system into your own makefile with:
 
 ```make
 include $(shell bender path cheshire)/cheshire.mk
@@ -21,4 +21,62 @@ You can leverage this to ensure your Cheshire build is up to date and rebuild ha
 
 ## Instantiating Cheshire
 
-Almost all features of Cheshire can be included/excluded or scaled through parameterization. We empose an internal memory map and reasonable constraints on all parameters, but within these constraints, Cheshire can scale to fit numerous scenarios.
+Almost all features of Cheshire can be included, excluded, or scaled through parameterization. We impose an internal memory map and reasonable constraints on all parameters, but within these constraints, Cheshire can scale to fit numerous scenarios.
+
+We provide a SystemVerilog macros header in `hw/include/cheshire/typedef.svh` that simplifies defining necessary interface types for Cheshire. To define a configuration struct for Cheshire, we recommend defining a *function* in a system package that starts from the default configuration `DefaultCfg` in `cheshire_pkg` and changes only necessary parameters.
+
+Unused inputs and inputs of zero effective width should be tied so as to initiate data transfers or handshakes (usually `'0`).
+
+A minimal clean instantiation would look as follows:
+
+```systemverilog
+`include "cheshire/typedef.svh"
+
+// Define function to derive configuration from defaults.
+// This could also (preferrably) be done in a system package.
+function automatic cheshire_pkg::cheshire_cfg_t gen_cheshire_cfg();
+  cheshire_pkg::cheshire_cfg_t ret = cheshire_pkg::DefaultCfg;
+  // Make overriding changes. Here, we add two AXI manager ports
+  ret.AxiExtNumMst = 2;
+  return ret;
+endfunction
+
+localparam cheshire_cfg_t CheshireCfg = gen_cheshire_cfg();
+
+// Generate interface types prefixed by `csh_` from our configuration.
+`CHESHIRE_TYPEDEF_ALL(csh_, CheshireCfg)
+
+// Instantiate Cheshire with our configuration and interface types.
+cheshire_soc #(
+  .Cfg                ( CheshireCfg ),
+  .ExtHartinfo        ( '0 ), // Tie iff there are no external harts.
+  .axi_ext_llc_req_t  ( csh_axi_llc_req_t ),
+  .axi_ext_llc_rsp_t  ( csh_axi_llc_rsp_t ),
+  .axi_ext_mst_req_t  ( csh_axi_mst_req_t ),
+  .axi_ext_mst_rsp_t  ( csh_axi_mst_rsp_t ),
+  .axi_ext_slv_req_t  ( csh_axi_slv_req_t ),
+  .axi_ext_slv_rsp_t  ( csh_axi_slv_rsp_t ),
+  .reg_ext_req_t      ( csh_reg_req_t ),
+  .reg_ext_rsp_t      ( csh_reg_rsp_t )
+) dut (
+  // ... IOs here ...
+);
+```
+
+## Verifying Cheshire In-System
+
+To simplify the simulation and verification of Cheshire in other systems, we provide a monolithic block of verification IPs called `cheshire_vip`. This includes:
+
+* ELF binary preloading tasks over JTAG, serial link, and UART.
+* External AXI manager ports accessing the chip through the serial link.
+* A UART receiver printing to standard output.
+* Serial link and LLC subordinate memories.
+* Preloadable I2C EEPROM and SPI NOR Flash models (used to simulate boot).
+
+Additionally, we provide a module `cheshire_vip_tristate` which adapts the unidirectional IO of this module to bidirectional IOs which may be interfaced with pads where necessary.
+
+## Platform ROM
+
+To set up boot-critical resources in the surrounding system (clock sources, IO pads, memories, PHYs, ...) or fork off execution from the built-in boot ROM, Cheshire can invoke an external *Platform ROM* before external interaction if configured accordingly; see [Boot ROM](../um/arch.md#boot-rom).
+
+Note that a reference clock, sufficiently fast and stable system clock, correctly set-up IOs, and accessible scratchpad memory are *required* for Cheshire's built-in active boot modes.
diff --git a/docs/tg/sim.md b/docs/tg/sim.md
@@ -21,7 +21,7 @@ We provide a SystemVerilog testbench for `cheshire_soc` running baremetal code.
 
 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 to build software for Cheshire and its boot process, see [Software](../um/sw.md).
 
-For simulation of Cheshire in other designs, we provide the module `cheshire_vip` encapsulating all verification IPs and their interfaces.
+For simulation of Cheshire in other designs, we provide the module `cheshire_vip` encapsulating all verification IPs and their interfaces. For details, see [Verifying Cheshire In-System](integr.md#verifying-cheshire-in-system).
 
 ## QuestaSim
 

diff --git a/docs/um/arch.md b/docs/um/arch.md
@@ -24,68 +24,106 @@ Cheshire is highly configurable; available features and resources depend on its
     * Core-local (CLINT *and* CLIC) and platform (PLIC) interrupt controllers
     * Dynamic interrupt routing from and to internal and external targets.
 
-## Parameterization
+## Memory Map
 
-Except for external hart info and interface types (see [Instantiating Cheshire](../tg/integr.md#instantiating_cheshire)), Cheshire is fully parameterized through the `Cfg` struct. We will first define SoC-wide parameters, then discuss device-specific parameters for each device.
+Cheshire's internal memory map is *static*. While device instantiation and layout may vary, each device is provided an address space of *fixed* location and size. For this, Cheshire *reserves* the address space from `0x0` to `0x2000_0000`, which is currently allocated as follows:
 
++--------------------+-------------------+---------------+------+-------+
+| Block              | Device            | Start         | Size | Flags |
++====================+===================+===============+======+=======+
+| 256K periphs @ AXI | Debug ROM         | `0x0000_0000` | 256K | E     |
++--------------------+-------------------+---------------+------+-------+
+| 4K periphs @ AXI   | AXI DMA (Cfg)     | `0x0100_0000` | 4K   |       |
++--------------------+-------------------+---------------+------+-------+
+| 256K periphs @ Reg | Boot ROM          | `0x0200_0000` | 256K | E     |
+|                    +-------------------+---------------+------+-------+
+|                    | CLINT             | `0x0204_0000` | 256K |       |
+|                    +-------------------+---------------+------+-------+
+|                    | IRQ router        | `0x0208_0000` | 256K |       |
++--------------------+-------------------+---------------+------+-------+
+| 4K periphs @ Reg   | SoC Regs          | `0x0300_0000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | LLC (Cfg)         | `0x0300_1000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | UART              | `0x0300_2000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | I2C               | `0x0300_3000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | SPI Host          | `0x0300_4000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | GPIO              | `0x0300_5000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | Serial Link (Cfg) | `0x0300_6000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | VGA (Cfg)         | `0x0300_7000` | 4K   |       |
+|                    +-------------------+---------------+------+-------+
+|                    | AXI RT (Cfg)      | `0x0300_8000` | 4K   |       |
++--------------------+-------------------+---------------+------+-------+
+| INTCs @ Reg        | PLIC              | `0x0400_0000` | 64M  |       |
+|                    +-------------------+---------------+------+-------+
+|                    | CLICs             | `0x0800_0000` | 64M  |       |
++--------------------+-------------------+---------------+------+-------+
+| LLC SPM @ AXI      | cached            | `0x1000_0000` | 64M  | CIE   |
+|                    +-------------------+---------------+------+-------+
+|                    | uncached          | `0x1400_0000` | 64M  | IE    |
++--------------------+-------------------+---------------+------+-------+
 
+The flags are defined as follows:
 
-## Memory Map
+* **C***acheable*: Accessed data may be cached in the L1 or LLC caches
+* **I***dempotent*: Multiple identical or composing accesses are equivalent to one access
+* **E***xecutable*: Data in this region may be executed.
 
-Cheshire's internal memory map is *static*. While device instantiation and layout may vary, each device is provided an address space of *fixed* location and size. For this, Cheshire *reserves* the address space from `0x0` to `0x2000_0000`, which is currently allocated as follows:
+Additionally, Cheshire assumes the following parameterized layout for external resources:
 
-+--------------------+-------------------+-------------+------+-------+
-| Block              | Device            | Start       | Size | Flags |
-+====================+===================+=============+======+=======+
-| 256K periphs @ AXI | Debug ROM         | 0x0000_0000 | 256K | E     |
-+--------------------+-------------------+-------------+------+-------+
-| 4K periphs @ AXI   | AXI DMA (Cfg)     | 0x0100_0000 | 4K   |       |
-+--------------------+-------------------+-------------+------+-------+
-| 256K periphs @ Reg | Boot ROM          | 0x0200_0000 | 256K | E     |
-|                    +-------------------+-------------+------+-------+
-|                    | CLINT             | 0x0204_0000 | 256K |       |
-|                    +-------------------+-------------+------+-------+
-|                    | IRQ router        | 0x0208_0000 | 256K |       |
-+--------------------+-------------------+-------------+------+-------+
-| 4K periphs @ Reg   | SoC Regs          | 0x0300_0000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | LLC (Cfg)         | 0x0300_1000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | UART              | 0x0300_2000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | I2C               | 0x0300_3000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | SPI Host          | 0x0300_4000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | GPIO              | 0x0300_5000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | Serial Link (Cfg) | 0x0300_6000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | VGA (Cfg)         | 0x0300_7000 | 4K   |       |
-|                    +-------------------+-------------+------+-------+
-|                    | AXI RT (Cfg)      | 0x0300_8000 | 4K   |       |
-+--------------------+-------------------+-------------+------+-------+
-| INTCs @ Reg        | PLIC              | 0x0400_0000 | 64M  |       |
-|                    +-------------------+-------------+------+-------+
-|                    | CLICs             | 0x0800_0000 | 64M  |       |
-+--------------------+-------------------+-------------+------+-------+
-| SPM @ AXI          | cached            | 0x1000_0000 | 64M  | CIE   |
-|                    +-------------------+-------------+------+-------+
-|                    | uncached          | 0x1400_0000 | 64M  | IE    |
-+--------------------+-------------------+-------------+------+-------+
++--------------------+---------------------+-------------------+-------+
+| Block              | Start               | End               | Flags |
++====================+=====================+===================+=======+
+| External on-chip   | `0x2000_0000`       | `0x8000_0000`     |   ?   |
++--------------------+---------------------+-------------------+-------+
+| LLC out (DRAM)     | `LlcOutRegionStart` | `LlcOutRegionEnd` | CIE   |
++--------------------+---------------------+-------------------+-------+
+| Serial Link        | `SlinkRegionStart`  | `SlinkRegionEnd`  |       |
++--------------------+---------------------+-------------------+-------+
+
+The *external on-chip* region is split into a region with full `CIE` flags and one without flags to minimize parameterization complexity. The parameters `Cva6ExtCieOnTop` and `Cva6ExtCieLength` control the order and partitioning of these two regions.
+
+The *LLC out* region must not collide with any other regions and defaults on starting at the lowest available address, `0x8000_0000`. The *Serial Link* region defaults on starting at `0x1_0000_0000` and configures the `SlinkTxAddrMask` and `SlinkTxAddrDomain` parameters to mirror the lower 32-bit space of another identical chip from this address base.
+
+
+## Devices and Parameters
+
+Except for external hart info and interface types (see [Instantiating Cheshire](../tg/integr.md#instantiating-cheshire)), Cheshire is fully parameterized through the `Cfg` struct. We will first describe global parameters, then discuss the functionality and parameterization of each device individually.
+
+For defaults of any parameters, `cheshire_pkg::DefaultCfg` is the *single source of truth*. Note, however, that this does *not* mean `DefaultCfg` parameters are suitable for your system or usecase; please carefully consider and choose all parameters.
+
+The following global parameters control basic functionality and features and can be read by software in the *SoC Registers*:
+
+| Parameter     | Type / Range | Description                                        |
+| ------------- | ------------ | -------------------------------------------------- |
+| `RtcFreq`     | `word_bt`    | Frequency (Hz) configured for RTC                  |
+| `PlatformRom` | `word_bt`    | Address of platform ROM; see [Boot ROM](#boot-rom) |
+| `Bootrom`     | `bit`        | Whether boot ROM is available                      |
+| `Llc`         | `bit`        | Whether LLC is available                           |
+| `Uart`        | `bit`        | Whether UART is available                          |
+| `I2c`         | `bit`        | Whether I2C host is available                      |
+| `SpiHost`     | `bit`        | Whether SPI is available                           |
+| `Gpio`        | `bit`        | Whether GPIO is available                          |
+| `Dma`         | `bit`        | Whether DMA is available                           |
+| `SerialLink`  | `bit`        | Whether serial link is available                   |
+| `Vga`         | `bit`        | Whether VGA is available                           |
+| `AxiRt`       | `bit`        | Whether AXI RT is available                        |
+| `Clic`        | `bit`        | Whether CLIC is available                          |
+| `IrqRouter`   | `bit`        | Whether IRQ Router is available                    |
+
+### CVA6 Cores
+
+| Parameter     | Type / Range | Description                                        |
+| ------------- | ------------ | -------------------------------------------------- |
+| `NumCores`    | `1..15`      | Number of instantiated CVA6 cores                  |
 
-The flags are defined as follows:
 
-* **C***acheable*: accessed data may be cached in the L1 or LLC caches
-* **I***dempotent*:
-* **E***xecutable*:
 
-+--------------------+-------------------+-------------+------+-------+
-| External           | CIE               | 0x2000_0000 | 512M | CIE   |
-|                    +-------------------+-------------+------+-------+
-|                    | non-CIE           | 0x4000_0000 | 1G   |       |
-+--------------------+-------------------+-------------+------+-------+
-| LLC out (DRAM)     |                   | 0x8000_0000 |      | CIE   |
-+--------------------+-------------------+-------------+------+-------+
+### Interconnect
 
-## Boot ROM
+### Boot ROM
diff --git a/docs/um/index.md b/docs/um/index.md
@@ -1 +1,6 @@
 # User Manual
+
+The *user manual* provides detailed reference information on Cheshire. It currently comprises the following chapters:
+
+* [Architecture](arch.md): Describes the hardware design, features, and configuration of Cheshire.
+* [Software Stack](sw.md): Describes how to run code on Cheshire and its Linux boot flow.
diff --git a/docs/um/sw.md b/docs/um/sw.md
@@ -1,8 +1,7 @@
 # Software
 
+## Baremetal programming
+
 ## Boot Flow
 
 ## Linux
-
-
-## Baremetal programming
diff --git a/hw/regs/cheshire_regs.hjson b/hw/regs/cheshire_regs.hjson
@@ -83,7 +83,7 @@
         { bits: "2",  name: "uart",         desc: "Whether UART is available"         }
         { bits: "3",  name: "spi_host",     desc: "Whether SPI host is available"     }
         { bits: "4",  name: "i2c",          desc: "Whether I2C is available"          }
-        { bits: "5",  name: "gpio",         desc: "Whether I2C is available"          }
+        { bits: "5",  name: "gpio",         desc: "Whether GPIO is available"         }
         { bits: "6",  name: "dma",          desc: "Whether DMA is available"          }
         { bits: "7",  name: "serial_link",  desc: "Whether serial link is available"  }
         { bits: "8",  name: "vga",          desc: "Whether VGA is available"          }