doc: More work on documentation

README.md

@@ -1,6 +1,6 @@
 # Cheshire
 
-Cheshire is a minimal Linux-capable host platform built around the RISC-V [CVA6]() core. Its goal is to provide a *lightweight*, *configurable*, *autonomously booting* host to systems that need one, from minimal Linux-capable SoCs to manycore compute accelerators.
+Cheshire is a minimal Linux-capable host platform built around the RISC-V [CVA6](https://github.com/openhwgroup/cva6) core. Its goal is to provide a *lightweight*, *configurable*, *autonomously booting* host to systems that need one, from minimal Linux-capable SoCs to manycore compute accelerators.
 
 Cheshire is developed as part of the PULP project, a joint effort between ETH Zurich and the University of Bologna.
 

docs/gs.md

@@ -9,7 +9,7 @@ The project is structured as follows:
 | Directory | Description                              | Documentation              |
 | --------- | ---------------------------------------- | ---------------------------|
 | `hw`      | Hardware sources as SystemVerilog RTL    | [Architecture](um/arch.md) |
-| `sw`      | Software stack, build setup, and tests   | [Software](um/sw.md)       |
+| `sw`      | Software stack, build setup, and tests   | [Software Stack](um/sw.md) |
 | `target`  | Simulation, FPGA, and ASIC target setups | [Targets](tg/index.md)     |
 | `util`    | Utility scripts                          |                            |
 | `doc`     | Documentation                            | [Home](index.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.
 
@@ -50,7 +50,7 @@ The following additional targets are not invoked by the above, but also availabl
 
 - `bootrom-all`: Rebuilds the boot ROM. This is not done by default as reproducible builds (as checked by CI) can only be guaranteed for fixed compiler versions.
 - `nonfree-init`: Clones our internal repository with nonfree resources we cannot release, including our internal CI. *This is not necessary to use Cheshire*.
-- `clean-deps`: Removes checked-out bender dependencies and submodules. This is useful if references to dependencies are updated.
+- `clean-deps`: Removes checked-out bender dependencies and submodules. This is useful when references to dependencies are updated.
 
 ## Targets
 

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,64 @@ 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/sw.md#boot-rom).
+
+Note that a reference clock, a sufficiently fast and stable system clock, correctly set-up IOs, and an accessible scratchpad memory are *required* for Cheshire's built-in boot modes. Platforms which do not inherently fulfill these criteria on boot ROM entry and want to use the built-in boot methods *must* provide a platform ROM.
+
+The platform ROM can be also used to extend and customize the boot chain. This may include adding further boot modes, suspending Cheshire boot until a given time, or implementing security features.

docs/tg/sim.md

@@ -1,6 +1,6 @@
 # Simulation
 
-This page describes how to simulate Cheshire to *execute baremetal code*. Please first read [Getting Started](../gs.md) to make sure to make sure have all dependencies and built the hardware, software, and simulation scripts.
+This page describes how to simulate Cheshire to *execute baremetal programs*. Please first read [Getting Started](../gs.md) to make sure to make sure have all dependencies and built the hardware, software, and simulation scripts.
 
 We currently provide working setups for:
 
@@ -10,18 +10,18 @@ We plan on supporting more simulators in the future. If your situation requires
 
 ## Testbench
 
-We provide a SystemVerilog testbench for `cheshire_soc` running baremetal code. This code is either preloaded through simulated interface drivers or read from external memory models by the boot ROM and then executed, depending on how the  `PRELMODE` and `BOOTMODE` variables are set:
+We provide a SystemVerilog testbench for `cheshire_soc` running baremetal programs. This code is either preloaded through simulated interface drivers or read from external memory models by the boot ROM and then executed, depending on how the  `PRELMODE` and `BOOTMODE` variables are set:
 
-  | `BOOTMODE` | `PRELMODE` | Action                                   |
-  | ---- | - | ------------------------------------------------------- |
-  | 0    | 0 | Preload through JTAG                                    |
-  | 0    | 1 | Preload through serial link                             |
-  | 0    | 2 | Preload through UART                                    |
-  | 1-3  | - | Autonomous boot, see [Boot ROM](../um/arch.md#boot-rom) |
+  | `BOOTMODE` | `PRELMODE` | Action                                                |
+  | ---------- | ---------- | ----------------------------------------------------- |
+  | 0          | 0          | Preload through JTAG                                  |
+  | 0          | 1          | Preload through serial link                           |
+  | 0          | 2          | Preload through UART                                  |
+  | 1-3        | -          | Autonomous boot, see [Boot ROM](../um/sw.md#boot-rom) |
 
-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).
+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 Stack](../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
 

docs/tg/xilinx.md

@@ -1,6 +1,6 @@
 # Xilinx FGPAs
 
-This page describes how to map Cheshire on Xilinx FPGAs to *execute baremetal code* or *boot CVA6 Linux*. Please first read [Getting Started](../gs.md) to make sure have all dependencies and built the hardware, software, and Xilinx FPGA scripts. Additionally, for on-chip debugging you need:
+This page describes how to map Cheshire on Xilinx FPGAs to *execute baremetal programs* or *boot CVA6 Linux*. Please first read [Getting Started](../gs.md) to make sure have all dependencies and built the hardware, software, and Xilinx FPGA scripts. Additionally, for on-chip debugging you need:
 
 - OpenOCD `>= 0.10.0`
 
@@ -25,11 +25,11 @@ make -C target/xilinx
 Before flashing the bitstream to your device, take note of the position of onboard switches, which control important functionality:
 
 
-  | Switch | Function                                          |
-  | ------ | ------------------------------------------------- |
-  | 1 .. 0 | Boot mode; see [Boot ROM](../um/arch.md#boot-rom) |
-  | 5 .. 2 | Fan level; *do not* keep at 0                     |
-  | 7      | Test mode; *leave at zero*                        |
+  | Switch | Function                                        |
+  | ------ | ------------------------------------------------|
+  | 1 .. 0 | Boot mode; see [Boot ROM](../um/sw.md#boot-rom) |
+  | 5 .. 2 | Fan level; *do not* keep at 0                   |
+  | 7      | Test mode; *leave at zero*                      |
 
 The reset, JTAG TAP, UART, I2C, and VGA are all connected to their onboard logic or ports. The UART has *no flow control*. The microSD slot is connected to chip select 0 of the SPI host peripheral. Serial link and GPIOs are currently not available.
 
@@ -65,7 +65,7 @@ minicom -cD /dev/ttyUSBX
 
 Make sure that hardware flow control matches your board's setup (usually *off*).
 
-In the following examples, we will use the `helloworld` test. As in simulation, you can replace this with any baremetal program of your choosing or design; see [Baremetal Programming](../um/sw#baremetal-programming).
+In the following examples, we will use the `helloworld` test. As in simulation, you can replace this with any baremetal program of your choosing or design; see [Baremetal Programs](../um/sw.md#baremetal-programs).
 
 ### JTAG Preloading
 
@@ -110,7 +110,7 @@ make -C sw/deps/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.
 
-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.
+In this case, OpenSBI is loaded by a regular baremetal program called the [Zero-Stage Loader](../um/sw.md#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: