# heaplab/aspis architecture

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

- Interactive diagram: https://gitdiagram.com/heaplab/aspis
- Repository: https://github.com/heaplab/aspis

## Overview

ASPIS is an out-of-tree LLVM IR plugin for software-based fault detection. Its main workflow takes C/C++ through a frontend into LLVM IR, applies data-protection and control-flow-checking passes, then emits an executable whose fault paths call user-provided handlers. Users can run the built-in `aspis.sh` pipeline or assemble a custom pipeline with LLVM `opt`. The graph preserves the documented pass alternatives and ordering; unsampled pipeline wiring is based on the README rather than inspected implementation.

Main entry points: [`passes/Utils/Utils.cpp`](https://github.com/heaplab/aspis/blob/master/passes/Utils/Utils.cpp) (Pass utilities), [`passes/EDDI.cpp`](https://github.com/heaplab/aspis/blob/master/passes/EDDI.cpp) (EDDI duplication), [`aspis.sh`](https://github.com/heaplab/aspis/blob/master/aspis.sh) (Pipeline CLI), [`passes/FuncRetToRef.cpp`](https://github.com/heaplab/aspis/blob/master/passes/FuncRetToRef.cpp) (Return conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Compilation workflow"]
  node_frontend["Clang frontend"]
  node_ir["LLVM IR"]
  node_cli["Pipeline CLI<br/>[aspis.sh]"]
  node_opt["LLVM opt"]
  node_executable["Hardened executable"]
  node_handlers["Fault handlers"]
end

subgraph group_data["Data protection"]
  node_return_ref["Return conversion<br/>[FuncRetToRef.cpp]"]
  node_eddi["EDDI duplication<br/>[EDDI.cpp]"]
  node_globals["Global duplication"]
end

subgraph group_control["Control-flow checking"]
  node_cfcss["CFCSS checks<br/>[CFCSS.cpp]"]
  node_rasm["RASM checks<br/>[RASM.cpp]"]
  node_racfed["RACFED checks<br/>[RACFED.cpp]"]
end

subgraph group_support["Profiling and shared utilities"]
  node_profiler["Check profiler"]
  node_insert_profiler["Profiler instrumentation"]
  node_utils["Pass utilities<br/>[Utils.cpp]"]
  node_pass_api["Pass declarations<br/>[ASPIS.h]"]
end

node_developer(("Developer"))

node_developer -->|"compiles source"| node_frontend
node_frontend -->|"emits IR"| node_ir
node_developer -->|"runs pipeline"| node_cli
node_cli -->|"invokes compilation"| node_frontend
node_cli -->|"runs passes"| node_opt
node_developer -->|"builds custom pipeline"| node_opt
node_ir -->|"transforms IR"| node_opt
node_opt -->|"applies first"| node_return_ref
node_opt -->|"applies data pass"| node_eddi
node_opt -.->|"selects alternative"| node_cfcss
node_opt -.->|"selects alternative"| node_rasm
node_opt -.->|"selects alternative"| node_racfed
node_opt -->|"applies last"| node_globals
node_return_ref -->|"precedes"| node_eddi
node_eddi -->|"precedes"| node_globals
node_opt -->|"emits output"| node_executable
node_executable -->|"calls on fault"| node_handlers
node_developer -->|"provides"| node_handlers
node_opt -.->|"runs analysis"| node_profiler
node_opt -.->|"instruments checks"| node_insert_profiler
node_eddi -->|"uses helpers"| node_utils
node_cfcss -->|"uses helpers"| node_utils
node_rasm -.->|"uses helpers"| node_utils
node_racfed -->|"uses helpers"| node_utils
node_return_ref -.->|"uses helpers"| node_utils
node_globals -->|"uses helpers"| node_utils
node_profiler -.->|"uses helpers"| node_utils
node_insert_profiler -.->|"uses helpers"| node_utils
node_pass_api -->|"includes declarations"| node_utils

click node_cli "https://github.com/heaplab/aspis/blob/master/aspis.sh"
click node_return_ref "https://github.com/heaplab/aspis/blob/master/passes/FuncRetToRef.cpp"
click node_eddi "https://github.com/heaplab/aspis/blob/master/passes/EDDI.cpp"
click node_globals "https://github.com/heaplab/aspis/blob/master/passes/DuplicateGlobals.cpp"
click node_cfcss "https://github.com/heaplab/aspis/blob/master/passes/CFCSS.cpp"
click node_rasm "https://github.com/heaplab/aspis/blob/master/passes/RASM.cpp"
click node_racfed "https://github.com/heaplab/aspis/blob/master/passes/RACFED.cpp"
click node_profiler "https://github.com/heaplab/aspis/blob/master/passes/Profiling/ASPISCheckProfiler.cpp"
click node_insert_profiler "https://github.com/heaplab/aspis/blob/master/passes/Profiling/ASPISCheckProfiler.cpp"
click node_utils "https://github.com/heaplab/aspis/blob/master/passes/Utils/Utils.cpp"
click node_pass_api "https://github.com/heaplab/aspis/blob/master/passes/ASPIS.h"

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_frontend,node_ir,node_cli,node_opt,node_executable,node_handlers toneBlue
class node_return_ref,node_eddi,node_globals toneAmber
class node_cfcss,node_rasm,node_racfed toneMint
class node_profiler,node_insert_profiler,node_utils,node_pass_api toneRose
class node_developer toneIndigo
```

## Components

### Compilation workflow

- **Clang frontend**
- **LLVM IR**
- [Pipeline CLI](https://github.com/heaplab/aspis/blob/master/aspis.sh): `aspis.sh`
- **LLVM opt**
- **Hardened executable**
- **Fault handlers**

### Data protection

- [Return conversion](https://github.com/heaplab/aspis/blob/master/passes/FuncRetToRef.cpp): `passes/FuncRetToRef.cpp`
- [EDDI duplication](https://github.com/heaplab/aspis/blob/master/passes/EDDI.cpp): `passes/EDDI.cpp`
- [Global duplication](https://github.com/heaplab/aspis/blob/master/passes/DuplicateGlobals.cpp): `passes/DuplicateGlobals.cpp`

### Control-flow checking

- [CFCSS checks](https://github.com/heaplab/aspis/blob/master/passes/CFCSS.cpp): `passes/CFCSS.cpp`
- [RASM checks](https://github.com/heaplab/aspis/blob/master/passes/RASM.cpp): `passes/RASM.cpp`
- [RACFED checks](https://github.com/heaplab/aspis/blob/master/passes/RACFED.cpp): `passes/RACFED.cpp`

### Profiling and shared utilities

- [Check profiler](https://github.com/heaplab/aspis/blob/master/passes/Profiling/ASPISCheckProfiler.cpp): `passes/Profiling/ASPISCheckProfiler.cpp`
- [Profiler instrumentation](https://github.com/heaplab/aspis/blob/master/passes/Profiling/ASPISCheckProfiler.cpp): `passes/Profiling/ASPISCheckProfiler.cpp`
- [Pass utilities](https://github.com/heaplab/aspis/blob/master/passes/Utils/Utils.cpp): `passes/Utils/Utils.cpp`
- [Pass declarations](https://github.com/heaplab/aspis/blob/master/passes/ASPIS.h): `passes/ASPIS.h`

### Other components

- **Developer**

## Connections

- Developer → Clang frontend: compiles source (evidence: `README.md`)
- Clang frontend → LLVM IR: emits IR (evidence: `README.md`)
- Developer → Pipeline CLI: runs pipeline (evidence: `README.md`)
- Pipeline CLI → Clang frontend: invokes compilation (evidence: `README.md`)
- Pipeline CLI → LLVM opt: runs passes (evidence: `README.md`)
- Developer → LLVM opt: builds custom pipeline (evidence: `README.md`)
- LLVM IR → LLVM opt: transforms IR (evidence: `README.md`)
- LLVM opt → Return conversion: applies first (evidence: `README.md`)
- LLVM opt → EDDI duplication: applies data pass (evidence: `README.md`)
- LLVM opt → CFCSS checks: selects alternative (evidence: `README.md`)
- LLVM opt → RASM checks: selects alternative (evidence: `README.md`)
- LLVM opt → RACFED checks: selects alternative (evidence: `README.md`)
- LLVM opt → Global duplication: applies last (evidence: `README.md`)
- Return conversion → EDDI duplication: precedes (evidence: `README.md`)
- EDDI duplication → Global duplication: precedes (evidence: `README.md`)
- LLVM opt → Hardened executable: emits output (evidence: `README.md`)
- Hardened executable → Fault handlers: calls on fault (evidence: `README.md`)
- Developer → Fault handlers: provides (evidence: `README.md`)
- LLVM opt → Check profiler: runs analysis
- LLVM opt → Profiler instrumentation: instruments checks
- EDDI duplication → Pass utilities: uses helpers (evidence: `passes/EDDI.cpp`)
- CFCSS checks → Pass utilities: uses helpers (evidence: `passes/CFCSS.cpp`)
- RASM checks → Pass utilities: uses helpers
- RACFED checks → Pass utilities: uses helpers (evidence: `passes/RACFED.cpp`)
- Return conversion → Pass utilities: uses helpers
- Global duplication → Pass utilities: uses helpers (evidence: `passes/DuplicateGlobals.cpp`)
- Check profiler → Pass utilities: uses helpers
- Profiler instrumentation → Pass utilities: uses helpers
- Pass declarations → Pass utilities: includes declarations (evidence: `passes/ASPIS.h`)
