doc: More work on documentation

README.md

@@ -6,11 +6,11 @@ Cheshire is developed as part of the PULP project, a joint effort between ETH Zu
 
 ## Getting started
 
-* To learn how to build and use Cheshire, see [Getting Started](gs.md).
-* To learn about available simulation, FPGA, and ASIC targets, see [Targets](tg/index.md).
-* For detailed information on Cheshire's inner workings, consult the [User Manual](um/index.md).
+* To learn how to build and use Cheshire, see [Getting Started](https://pulp-platform.github.io/cheshire/gs/).
+* To learn about available simulation, FPGA, and ASIC targets, see [Targets](https://pulp-platform.github.io/cheshire/tg).
+* For detailed information on Cheshire's inner workings, consult the [User Manual](https://pulp-platform.github.io/cheshire/um/).
 
-If you are impatient and have all needed [dependencies](gs.md#Dependencies), you can run `make all`, then start QuestaSim in `target/sim/vsim` and run:
+If you are impatient and have all needed [dependencies](https://pulp-platform.github.io/cheshire/gs/#dependencies), you can run `make all`, then start QuestaSim in `target/sim/vsim` and run:
 
 ```
 set BINARY ../../../sw/tests/helloworld.spm.elf

docs/gs.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-First, we discuss the Cheshire's project structure, its build dependencies, and how to build different parts of it.
+We first discuss the Cheshire's project structure, its dependencies, and how to build it.
 
 ## Repository structure
 
@@ -54,5 +54,4 @@ The following additional targets are not invoked by the above, but also availabl
 
 ## Targets
 
-A *target* refers to an end use of Cheshire, be it in simulation, FPGA implementation, or ASIC integration. Your next steps will depend on your desired target; see the [Targets](tg/index.md) chapter for more information.
-
+A *target* is an end use for Cheshire. Each target requires different steps from here; read the page for your desired target in the following [Targets](tg/index.md) chapter.

docs/tg/index.md

@@ -1,3 +1,20 @@
 # Targets
 
-bla
+A *target* refers to an end use of Cheshire. 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)
+
+## External Targets
+
+For integration into other SoCs, Cheshire may be included either as a Bender dependency or Git submodule. The use of Bender for dependency management is strongly encouraged.
+
+For further information and best pratices, see [SoC Integration](integr.md).

docs/tg/integr.md

@@ -0,0 +1,22 @@
+# 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:
+
+- [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.
+
+## Using Cheshire In Your Project
+
+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:
+
+```make
+include $(shell bender path cheshire)/cheshire.mk
+```
+
+All of Cheshire's build targets are now available with the prefix `chs-`. You can leverage this to ensure your Cheshire build is up to date and rebuild hardware and software whenever necessary. You can change the default value of any build parameter, replace source files to adapt Cheshire, or reuse parts of its build system, such as the software stack or the register and ROM generators.
+
+
+## Instantiating Cheshire
+

docs/tg/sim.md

@@ -1,36 +1,34 @@
 # Simulation
 
-This page describes how to simulate Cheshire. Please first read [Getting Started](../gs.md) and make sure you built the hardware, software, and simulation scripts.
+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.
 
-In terms of simulators, we currently support:
+We currently provide working setups for:
 
 - Questa Advanced Simulator (QuestaSim) `>= 2022.3`
 
 We plan on supporting more simulators in the future. If your situation requires it, simulating Cheshire on other setups should be straightforward.
 
 ## Testbench
 
-We provide a SystemVerilog testbench for `cheshire_soc` running bare-metal 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 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:
 
-  | `BOOTMODE` | `PRELMODE` | Action          |
-  | - | - | --------------------------------- |
-  | 0 | 0 | Preload through JTAG              |
-  | 0 | 1 | Preload through Serial Link       |
-  | 0 | 2 | Preload through UART              |
-  | 1 | - | Autonomous boot from SPI SD card  |
-  | 2 | - | Autonomous boot from SPI flash    |
-  | 3 | - | Autonomous boot from I2C EEPROM   |
+  | `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) |
 
-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 Cheshire boots, see [Boot Flow](../um/sw.md#Boot%20flow).
+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 IP and its interfaces.
+For simulation of Cheshire in other designs, we provide the module `cheshire_vip` encapsulating all verification IPs and their interfaces.
 
 ## QuestaSim
 
 After building Cheshire, start QuestaSim in `target/sim/vsim` and run:
 
 ```tcl
-# We want to preload `helloworld` through serial link
+# Preload `helloworld.spm.elf` through serial link
 set BINARY ../../../sw/tests/helloworld.spm.elf
 set BOOTMODE 0
 set PRELMODE 1