# pulp-platform/cheshire architecture

> Architecture diagram of the GitHub repository pulp-platform/cheshire, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulp-platform/cheshire
- Repository: https://github.com/pulp-platform/cheshire

## Overview

Cheshire is a configurable, minimal Linux-capable RISC-V host platform built around CVA6, intended to boot autonomously and serve as a host for accelerator systems. The principal software path is boot ROM selection of a boot source, loading a zero-stage loader, then loading and launching firmware (and a device tree for GPT disk boot). Hardware sources define the SoC and register map; software includes device interfaces and flash utilities. The README documents simulation and target support, but most hardware composition and target wiring were not shown in the sampled source.

Main entry points: [`hw/bootrom/cheshire_bootrom.c`](https://github.com/pulp-platform/cheshire/blob/main/hw/bootrom/cheshire_bootrom.c) (Boot ROM), [`sw/boot/zsl.c`](https://github.com/pulp-platform/cheshire/blob/main/sw/boot/zsl.c) (Zero-stage loader), [`sw/boot/flash.c`](https://github.com/pulp-platform/cheshire/blob/main/sw/boot/flash.c) (Disk flasher), [`hw/cheshire_soc.sv`](https://github.com/pulp-platform/cheshire/blob/main/hw/cheshire_soc.sv) (Cheshire SoC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["SoC Platform"]
  node_cheshire["Cheshire SoC<br/>[cheshire_soc.sv]"]
  node_addrmap["SoC address map<br/>[cheshire.rdl]"]
  node_regsv["Generated SoC registers"]
end

subgraph group_boot["Boot and Storage"]
  node_bootrom["Boot ROM<br/>[cheshire_bootrom.c]"]
  node_gpt["GPT boot logic<br/>[gpt.c]"]
  node_zsl["Zero-stage loader<br/>[zsl.c]"]
  node_flash["Disk flasher<br/>[flash.c]"]
end

subgraph group_interfaces["Software Interfaces"]
  node_sdcard["SD card HAL<br/>[spi_sdcard.c]"]
  node_spi_flash["SPI flash HAL<br/>[spi_s25fs512s.c]"]
  node_i2c_eeprom["I2C EEPROM HAL<br/>[i2c_24fc1025.c]"]
  node_uart["UART interface<br/>[uart.c]"]
  node_clint["Timer interface<br/>[clint.c]"]
  node_regs_header["Register definitions<br/>[cheshire.h]"]
end

subgraph group_targets["Execution Targets"]
  node_sim["Simulation target<br/>[tb_cheshire_soc.sv]"]
  node_xilinx["Xilinx FPGA target"]
end

node_host(("System host"))
node_firmware["Firmware payload"]
node_boot_media[("Boot media")]

node_host -->|"hosts"| node_cheshire
node_bootrom -->|"boots via GPT"| node_gpt
node_bootrom -->|"reads SD"| node_sdcard
node_bootrom -->|"reads flash"| node_spi_flash
node_bootrom -->|"reads EEPROM"| node_i2c_eeprom
node_bootrom -->|"serves debug"| node_uart
node_bootrom -->|"measures clock"| node_clint
node_bootrom -->|"reads boot config"| node_regs_header
node_gpt -.->|"reads partitions"| node_boot_media
node_zsl -->|"finds partitions"| node_gpt
node_zsl -->|"initializes console"| node_uart
node_zsl -->|"measures clock"| node_clint
node_zsl -->|"reads boot config"| node_regs_header
node_zsl -->|"loads and launches"| node_firmware
node_flash -->|"writes blocks"| node_sdcard
node_flash -->|"flashes sectors"| node_spi_flash
node_flash -->|"writes EEPROM"| node_i2c_eeprom
node_cheshire -->|"simulated by"| node_sim
node_cheshire -.->|"target implementation"| node_xilinx

click node_cheshire "https://github.com/pulp-platform/cheshire/blob/main/hw/cheshire_soc.sv"
click node_addrmap "https://github.com/pulp-platform/cheshire/blob/main/hw/cheshire.rdl"
click node_regsv "https://github.com/pulp-platform/cheshire/blob/main/hw/regs/cheshire_soc_regs.sv"
click node_bootrom "https://github.com/pulp-platform/cheshire/blob/main/hw/bootrom/cheshire_bootrom.c"
click node_gpt "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/gpt.c"
click node_zsl "https://github.com/pulp-platform/cheshire/blob/main/sw/boot/zsl.c"
click node_flash "https://github.com/pulp-platform/cheshire/blob/main/sw/boot/flash.c"
click node_sdcard "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/spi_sdcard.c"
click node_spi_flash "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/spi_s25fs512s.c"
click node_i2c_eeprom "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/i2c_24fc1025.c"
click node_uart "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/dif/uart.c"
click node_clint "https://github.com/pulp-platform/cheshire/blob/main/sw/lib/dif/clint.c"
click node_regs_header "https://github.com/pulp-platform/cheshire/blob/main/sw/include/regs/cheshire.h"
click node_sim "https://github.com/pulp-platform/cheshire/blob/main/target/sim/src/tb_cheshire_soc.sv"
click node_xilinx "https://github.com/pulp-platform/cheshire/blob/main/target/xilinx/src/cheshire_top_xilinx.sv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cheshire,node_addrmap,node_regsv toneBlue
class node_bootrom,node_gpt,node_zsl,node_flash,node_boot_media toneAmber
class node_sdcard,node_spi_flash,node_i2c_eeprom,node_uart,node_clint,node_regs_header toneMint
class node_sim,node_xilinx toneRose
class node_host,node_firmware toneIndigo
```

## Components

### SoC Platform

- [Cheshire SoC](https://github.com/pulp-platform/cheshire/blob/main/hw/cheshire_soc.sv): `hw/cheshire_soc.sv`
- [SoC address map](https://github.com/pulp-platform/cheshire/blob/main/hw/cheshire.rdl): `hw/cheshire.rdl`
- [Generated SoC registers](https://github.com/pulp-platform/cheshire/blob/main/hw/regs/cheshire_soc_regs.sv): `hw/regs/cheshire_soc_regs.sv`

### Boot and Storage

- [Boot ROM](https://github.com/pulp-platform/cheshire/blob/main/hw/bootrom/cheshire_bootrom.c): `hw/bootrom/cheshire_bootrom.c`
- [GPT boot logic](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/gpt.c): `sw/lib/gpt.c`
- [Zero-stage loader](https://github.com/pulp-platform/cheshire/blob/main/sw/boot/zsl.c): `sw/boot/zsl.c`
- [Disk flasher](https://github.com/pulp-platform/cheshire/blob/main/sw/boot/flash.c): `sw/boot/flash.c`

### Software Interfaces

- [SD card HAL](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/spi_sdcard.c): `sw/lib/hal/spi_sdcard.c`
- [SPI flash HAL](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/spi_s25fs512s.c): `sw/lib/hal/spi_s25fs512s.c`
- [I2C EEPROM HAL](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/hal/i2c_24fc1025.c): `sw/lib/hal/i2c_24fc1025.c`
- [UART interface](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/dif/uart.c): `sw/lib/dif/uart.c`
- [Timer interface](https://github.com/pulp-platform/cheshire/blob/main/sw/lib/dif/clint.c): `sw/lib/dif/clint.c`
- [Register definitions](https://github.com/pulp-platform/cheshire/blob/main/sw/include/regs/cheshire.h): `sw/include/regs/cheshire.h`

### Execution Targets

- [Simulation target](https://github.com/pulp-platform/cheshire/blob/main/target/sim/src/tb_cheshire_soc.sv): `target/sim/src/tb_cheshire_soc.sv`
- [Xilinx FPGA target](https://github.com/pulp-platform/cheshire/blob/main/target/xilinx/src/cheshire_top_xilinx.sv): `target/xilinx/src/cheshire_top_xilinx.sv`

### Other components

- **System host**
- **Firmware payload**
- **Boot media**

## Connections

- System host → Cheshire SoC: hosts (evidence: `README.md`)
- Boot ROM → GPT boot logic: boots via GPT (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → SD card HAL: reads SD (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → SPI flash HAL: reads flash (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → I2C EEPROM HAL: reads EEPROM (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → UART interface: serves debug (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → Timer interface: measures clock (evidence: `hw/bootrom/cheshire_bootrom.c`)
- Boot ROM → Register definitions: reads boot config (evidence: `hw/bootrom/cheshire_bootrom.c`)
- GPT boot logic → Boot media: reads partitions
- Zero-stage loader → GPT boot logic: finds partitions (evidence: `sw/boot/zsl.c`)
- Zero-stage loader → UART interface: initializes console (evidence: `sw/boot/zsl.c`)
- Zero-stage loader → Timer interface: measures clock (evidence: `sw/boot/zsl.c`)
- Zero-stage loader → Register definitions: reads boot config (evidence: `sw/boot/zsl.c`)
- Zero-stage loader → Firmware payload: loads and launches (evidence: `sw/boot/zsl.c`)
- Disk flasher → SD card HAL: writes blocks (evidence: `sw/boot/flash.c`)
- Disk flasher → SPI flash HAL: flashes sectors (evidence: `sw/boot/flash.c`)
- Disk flasher → I2C EEPROM HAL: writes EEPROM (evidence: `sw/boot/flash.c`)
- Cheshire SoC → Simulation target: simulated by (evidence: `README.md`)
- Cheshire SoC → Xilinx FPGA target: target implementation