# hichat-fog/interclus architecture

> Architecture diagram of the GitHub repository hichat-fog/interclus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hichat-fog/interclus
- Repository: https://github.com/hichat-fog/interclus

## Overview

Interclus is embedded firmware that runs eBPF policies inside RISC-V PMP compartments. The principal workflow is: the machine-mode supervisor validates and loads a policy, prepares packet and swarm inputs, schedules the monitor, and records verdicts; compartment faults are captured and the faulty lifetime is evicted. Separate capabilities include native attacker and measurement modules, UART program transport, the PMP probe, and a QEMU reproduction path. Edges are limited to relationships visible in the supplied excerpts or README; several implementation details are unsampled.

Main entry points: [`modules/supervisor.c`](https://github.com/hichat-fog/interclus/blob/master/modules/supervisor.c) (Supervisor), [`modules/monitor.c`](https://github.com/hichat-fog/interclus/blob/master/modules/monitor.c) (Policy monitor), [`core/compartment.c`](https://github.com/hichat-fog/interclus/blob/master/core/compartment.c) (PMP compartments), [`qemu/main_qemu.c`](https://github.com/hichat-fog/interclus/blob/master/qemu/main_qemu.c) (QEMU runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Supervisor and Isolation"]
  node_supervisor["Supervisor<br/>[supervisor.c]"]
  node_compartments["PMP compartments<br/>[compartment.c]"]
  node_contract["Module contract<br/>[contract.h]"]
  node_platform["Platform map<br/>[platform.h]"]
  node_trap["Fault capture<br/>[trap.S]"]
end

subgraph group_policy["Policy Execution"]
  node_monitor["Policy monitor<br/>[monitor.c]"]
  node_interpreter["eBPF interpreter<br/>[ebpf.c]"]
  node_helpers["Map helpers<br/>[helpers.c]"]
  node_mavlink["MAVLink policy<br/>[mavlink.h]"]
  node_screening["Grid screening<br/>[screening.h]"]
end

subgraph group_input["Loading and Inputs"]
  node_loader["Program gate<br/>[loader.c]"]
  node_description["Compartment specs<br/>[demo.h]"]
  node_uart["UART transport<br/>[uart.c]"]
end

subgraph group_evidence["Experiments and Evidence"]
  node_attacker["Attack probe<br/>[attacker.c]"]
  node_measure["Measurement module<br/>[measure.c]"]
  node_pmp_probe["PMP probe<br/>[pmp_probe.c]"]
  node_qemu["QEMU runtime<br/>[main_qemu.c]"]
  node_fixtures["Capacity fixtures<br/>[fixture.h]"]
  node_report["QEMU evidence report<br/>[report.c]"]
end

node_engineer(("Firmware operator"))
node_device{{"CH32V307 board"}}
node_debugger{{"WCH-LinkE"}}

node_engineer -->|"boots firmware"| node_supervisor
node_supervisor -->|"gates programs"| node_loader
node_supervisor -->|"uses specs"| node_description
node_supervisor -->|"schedules compartments"| node_compartments
node_supervisor -->|"schedules filtering"| node_monitor
node_supervisor -->|"receives frames"| node_uart
node_monitor -->|"runs programs"| node_interpreter
node_monitor -->|"uses helpers"| node_helpers
node_monitor -->|"selects policy"| node_mavlink
node_monitor -->|"selects policy"| node_screening
node_compartments -->|"implements interface"| node_contract
node_supervisor -->|"checks contract"| node_contract
node_supervisor -->|"uses address map"| node_platform
node_compartments -->|"maps PMP regions"| node_platform
node_compartments -->|"captures faults"| node_trap
node_supervisor -->|"schedules attacks"| node_attacker
node_supervisor -.->|"runs measurements"| node_measure
node_engineer -->|"loads swarm"| node_debugger
node_debugger -->|"writes mailbox"| node_supervisor
node_engineer -->|"flashes firmware"| node_device
node_engineer -->|"runs experiment"| node_qemu
node_qemu -->|"loads fixtures"| node_fixtures
node_qemu -.->|"reports results"| node_report
node_engineer -->|"runs probe firmware"| node_pmp_probe

click node_supervisor "https://github.com/hichat-fog/interclus/blob/master/modules/supervisor.c"
click node_compartments "https://github.com/hichat-fog/interclus/blob/master/core/compartment.c"
click node_contract "https://github.com/hichat-fog/interclus/blob/master/core/contract.h"
click node_platform "https://github.com/hichat-fog/interclus/blob/master/core/platform.h"
click node_trap "https://github.com/hichat-fog/interclus/blob/master/core/trap.S"
click node_monitor "https://github.com/hichat-fog/interclus/blob/master/modules/monitor.c"
click node_interpreter "https://github.com/hichat-fog/interclus/blob/master/core/ebpf.c"
click node_helpers "https://github.com/hichat-fog/interclus/blob/master/core/helpers.c"
click node_mavlink "https://github.com/hichat-fog/interclus/blob/master/modules/policies/mavlink.h"
click node_screening "https://github.com/hichat-fog/interclus/blob/master/modules/policies/screening.h"
click node_loader "https://github.com/hichat-fog/interclus/blob/master/core/loader.c"
click node_description "https://github.com/hichat-fog/interclus/blob/master/descriptions/demo.h"
click node_uart "https://github.com/hichat-fog/interclus/blob/master/core/uart.c"
click node_attacker "https://github.com/hichat-fog/interclus/blob/master/modules/attacker.c"
click node_measure "https://github.com/hichat-fog/interclus/blob/master/modules/measure.c"
click node_pmp_probe "https://github.com/hichat-fog/interclus/blob/master/modules/pmp_probe.c"
click node_qemu "https://github.com/hichat-fog/interclus/blob/master/qemu/main_qemu.c"
click node_fixtures "https://github.com/hichat-fog/interclus/blob/master/qemu/fixture.h"
click node_report "https://github.com/hichat-fog/interclus/blob/master/qemu/report.c"

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_supervisor,node_compartments,node_contract,node_platform,node_trap toneBlue
class node_monitor,node_interpreter,node_helpers,node_mavlink,node_screening toneAmber
class node_loader,node_description,node_uart toneMint
class node_attacker,node_measure,node_pmp_probe,node_qemu,node_fixtures,node_report toneRose
class node_engineer,node_device,node_debugger toneIndigo
```

## Components

### Supervisor and Isolation

- [Supervisor](https://github.com/hichat-fog/interclus/blob/master/modules/supervisor.c): `modules/supervisor.c`
- [PMP compartments](https://github.com/hichat-fog/interclus/blob/master/core/compartment.c): `core/compartment.c`
- [Module contract](https://github.com/hichat-fog/interclus/blob/master/core/contract.h): `core/contract.h`
- [Platform map](https://github.com/hichat-fog/interclus/blob/master/core/platform.h): `core/platform.h`
- [Fault capture](https://github.com/hichat-fog/interclus/blob/master/core/trap.S): `core/trap.S`

### Policy Execution

- [Policy monitor](https://github.com/hichat-fog/interclus/blob/master/modules/monitor.c): `modules/monitor.c`
- [eBPF interpreter](https://github.com/hichat-fog/interclus/blob/master/core/ebpf.c): `core/ebpf.c`
- [Map helpers](https://github.com/hichat-fog/interclus/blob/master/core/helpers.c): `core/helpers.c`
- [MAVLink policy](https://github.com/hichat-fog/interclus/blob/master/modules/policies/mavlink.h): `modules/policies/mavlink.h`
- [Grid screening](https://github.com/hichat-fog/interclus/blob/master/modules/policies/screening.h): `modules/policies/screening.h`

### Loading and Inputs

- [Program gate](https://github.com/hichat-fog/interclus/blob/master/core/loader.c): `core/loader.c`
- [Compartment specs](https://github.com/hichat-fog/interclus/blob/master/descriptions/demo.h): `descriptions/demo.h`
- [UART transport](https://github.com/hichat-fog/interclus/blob/master/core/uart.c): `core/uart.c`

### Experiments and Evidence

- [Attack probe](https://github.com/hichat-fog/interclus/blob/master/modules/attacker.c): `modules/attacker.c`
- [Measurement module](https://github.com/hichat-fog/interclus/blob/master/modules/measure.c): `modules/measure.c`
- [PMP probe](https://github.com/hichat-fog/interclus/blob/master/modules/pmp_probe.c): `modules/pmp_probe.c`
- [QEMU runtime](https://github.com/hichat-fog/interclus/blob/master/qemu/main_qemu.c): `qemu/main_qemu.c`
- [Capacity fixtures](https://github.com/hichat-fog/interclus/blob/master/qemu/fixture.h): `qemu/fixture.h`
- [QEMU evidence report](https://github.com/hichat-fog/interclus/blob/master/qemu/report.c): `qemu/report.c`

### Other components

- **Firmware operator**
- **CH32V307 board**
- **WCH-LinkE**

## Connections

- Firmware operator → Supervisor: boots firmware (evidence: `README.md`)
- Supervisor → Program gate: gates programs (evidence: `README.md`)
- Supervisor → Compartment specs: uses specs (evidence: `modules/supervisor.c`)
- Supervisor → PMP compartments: schedules compartments (evidence: `modules/supervisor.c`)
- Supervisor → Policy monitor: schedules filtering (evidence: `README.md`)
- Supervisor → UART transport: receives frames (evidence: `README.md`)
- Policy monitor → eBPF interpreter: runs programs (evidence: `modules/monitor.c`)
- Policy monitor → Map helpers: uses helpers (evidence: `modules/monitor.c`)
- Policy monitor → MAVLink policy: selects policy (evidence: `modules/monitor.c`)
- Policy monitor → Grid screening: selects policy (evidence: `modules/monitor.c`)
- PMP compartments → Module contract: implements interface
- Supervisor → Module contract: checks contract (evidence: `modules/supervisor.c`)
- Supervisor → Platform map: uses address map (evidence: `modules/supervisor.c`)
- PMP compartments → Platform map: maps PMP regions (evidence: `core/compartment.c`)
- PMP compartments → Fault capture: captures faults (evidence: `README.md`)
- Supervisor → Attack probe: schedules attacks (evidence: `modules/supervisor.c`)
- Supervisor → Measurement module: runs measurements
- Firmware operator → WCH-LinkE: loads swarm (evidence: `README.md`)
- WCH-LinkE → Supervisor: writes mailbox (evidence: `README.md`)
- Firmware operator → CH32V307 board: flashes firmware (evidence: `README.md`)
- Firmware operator → QEMU runtime: runs experiment (evidence: `README.md`)
- QEMU runtime → Capacity fixtures: loads fixtures (evidence: `qemu/main_qemu.c`)
- QEMU runtime → QEMU evidence report: reports results
- Firmware operator → PMP probe: runs probe firmware (evidence: `README.md`)
