# systems-nuts/unifico architecture

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

- Interactive diagram: https://gitdiagram.com/systems-nuts/unifico
- Repository: https://github.com/systems-nuts/unifico

## Overview

Unifico is a research toolkit for unified address spaces and stack-layout transformation, combining an LLVM/musl-based compilation environment with metadata tools, alignment utilities, runtime tracing experiments, and benchmark analysis. A typical workflow is to build binaries with the documented Unifico LLVM configuration, post-process ELF stack maps into transformation metadata, then run benchmarks or inspect stack behavior. The tree also contains call-site and stack-slot alignment tools and Pin/DynamoRIO tracing experiments. Several subsystems are represented by directory paths because their implementation was not sampled; their internal wiring is therefore left unspecified.

Main entry points: [`stack-metadata/src/main.c`](https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/main.c) (Metadata generator), [`npb/runs`](https://github.com/systems-nuts/unifico/tree/main/npb/runs) (NPB runner), [`layout/callsites/align`](https://github.com/systems-nuts/unifico/tree/main/layout/callsites/align) (Symbol alignment), [`exploration/pin_tools`](https://github.com/systems-nuts/unifico/tree/main/exploration/pin_tools) (Pin tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler integration"]
  node_llvm["Unifico LLVM"]
  node_musl["Modified musl"]
  node_alignment["Symbol alignment"]
end

subgraph group_metadata["Stack metadata"]
  node_stackmeta["Metadata generator<br/>[main.c]"]
  node_elf["ELF binary"]
  node_stackmap["LLVM stack maps<br/>[stackmap.c]"]
  node_metadatawrite["Metadata sections<br/>[write.c]"]
  node_callsitealign["Call-site alignment"]
  node_slotalign["Stack-slot alignment"]
end

subgraph group_instrumentation["Tracing tools"]
  node_dynamorio["DynamoRIO clients"]
  node_pintools["Pin tools"]
  node_pinpost["Pin postprocessing<br/>[plot_accesses.py]"]
end

subgraph group_benchmarks["Benchmarks"]
  node_npb["NPB benchmarks"]
  node_olden["Olden benchmarks"]
  node_bfs["BFS benchmarks"]
  node_npbrunner["NPB runner"]
  node_specrunner["SPEC runner<br/>[run_spec.py]"]
  node_parsecrunner["PARSEC runner<br/>[run_parsec.py]"]
end

subgraph group_analysis["Analysis utilities"]
  node_resultanalysis["Benchmark analysis<br/>[process_results.py]"]
  node_stackplots["Stack-depth plots<br/>[main.py]"]
  node_stackascii["Stack assembly view"]
  node_pressure["Register pressure"]
end

node_engineer(("Researcher"))

node_engineer -.->|"builds with"| node_llvm
node_engineer -.->|"selects runtime"| node_musl
node_llvm -.->|"emits binary"| node_elf
node_llvm -.->|"emits maps"| node_stackmap
node_engineer -.->|"aligns symbols"| node_alignment
node_alignment -.->|"precedes processing"| node_stackmeta
node_engineer -->|"runs postprocessor"| node_stackmeta
node_stackmeta -->|"opens and updates"| node_elf
node_stackmeta -->|"loads maps"| node_stackmap
node_stackmeta -->|"adds sections"| node_metadatawrite
node_engineer -.->|"uses alignment tools"| node_callsitealign
node_engineer -.->|"uses alignment tools"| node_slotalign
node_engineer -.->|"runs tracing client"| node_dynamorio
node_engineer -.->|"runs instrumentation"| node_pintools
node_pintools -.->|"produces access data"| node_pinpost
node_engineer -.->|"runs benchmarks"| node_npbrunner
node_engineer -.->|"runs benchmarks"| node_specrunner
node_engineer -.->|"runs benchmarks"| node_parsecrunner
node_npbrunner -.->|"runs workloads"| node_npb
node_specrunner -.->|"executes binaries"| node_elf
node_parsecrunner -.->|"executes binaries"| node_elf
node_engineer -.->|"runs workloads"| node_olden
node_engineer -.->|"runs workloads"| node_bfs
node_npbrunner -.->|"provides results"| node_resultanalysis
node_engineer -.->|"analyzes stack profiles"| node_stackplots
node_engineer -.->|"inspects assembly"| node_stackascii
node_engineer -.->|"analyzes register use"| node_pressure

click node_alignment "https://github.com/systems-nuts/unifico/tree/main/layout/callsites/align"
click node_stackmeta "https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/main.c"
click node_stackmap "https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/stackmap.c"
click node_metadatawrite "https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/write.c"
click node_callsitealign "https://github.com/systems-nuts/unifico/tree/main/layout/callsites/align"
click node_slotalign "https://github.com/systems-nuts/unifico/tree/main/layout/slots/align"
click node_dynamorio "https://github.com/systems-nuts/unifico/blob/main/exploration/dynamorio_clients/register-loads-stores/register_loads_stores.cpp"
click node_pintools "https://github.com/systems-nuts/unifico/tree/main/exploration/pin_tools"
click node_pinpost "https://github.com/systems-nuts/unifico/blob/main/exploration/pin_postprocess/plot_accesses.py"
click node_npb "https://github.com/systems-nuts/unifico/tree/main/layout/npb"
click node_olden "https://github.com/systems-nuts/unifico/tree/main/layout/olden"
click node_bfs "https://github.com/systems-nuts/unifico/tree/main/layout/prim/bfs"
click node_npbrunner "https://github.com/systems-nuts/unifico/tree/main/npb/runs"
click node_specrunner "https://github.com/systems-nuts/unifico/blob/main/spec2017/run_spec.py"
click node_parsecrunner "https://github.com/systems-nuts/unifico/blob/main/parsec/run_parsec.py"
click node_resultanalysis "https://github.com/systems-nuts/unifico/blob/main/npb/process_results.py"
click node_stackplots "https://github.com/systems-nuts/unifico/blob/main/plots/stack-depth-and-size/main.py"
click node_stackascii "https://github.com/systems-nuts/unifico/blob/main/stack_ascii_printer/print_ascii_stack.py"
click node_pressure "https://github.com/systems-nuts/unifico/tree/main/register-pressure"

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_llvm,node_musl,node_alignment toneBlue
class node_stackmeta,node_elf,node_stackmap,node_metadatawrite,node_callsitealign,node_slotalign toneAmber
class node_dynamorio,node_pintools,node_pinpost toneMint
class node_npb,node_olden,node_bfs,node_npbrunner,node_specrunner,node_parsecrunner toneRose
class node_resultanalysis,node_stackplots,node_stackascii,node_pressure,node_engineer toneIndigo
```

## Components

### Compiler integration

- **Unifico LLVM**
- **Modified musl**
- [Symbol alignment](https://github.com/systems-nuts/unifico/tree/main/layout/callsites/align): `layout/callsites/align`

### Stack metadata

- [Metadata generator](https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/main.c): `stack-metadata/src/main.c`
- **ELF binary**
- [LLVM stack maps](https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/stackmap.c): `stack-metadata/src/stackmap.c`
- [Metadata sections](https://github.com/systems-nuts/unifico/blob/main/stack-metadata/src/write.c): `stack-metadata/src/write.c`
- [Call-site alignment](https://github.com/systems-nuts/unifico/tree/main/layout/callsites/align): `layout/callsites/align`
- [Stack-slot alignment](https://github.com/systems-nuts/unifico/tree/main/layout/slots/align): `layout/slots/align`

### Tracing tools

- [DynamoRIO clients](https://github.com/systems-nuts/unifico/blob/main/exploration/dynamorio_clients/register-loads-stores/register_loads_stores.cpp): `exploration/dynamorio_clients/register-loads-stores/register_loads_stores.cpp`
- [Pin tools](https://github.com/systems-nuts/unifico/tree/main/exploration/pin_tools): `exploration/pin_tools`
- [Pin postprocessing](https://github.com/systems-nuts/unifico/blob/main/exploration/pin_postprocess/plot_accesses.py): `exploration/pin_postprocess/plot_accesses.py`

### Benchmarks

- [NPB benchmarks](https://github.com/systems-nuts/unifico/tree/main/layout/npb): `layout/npb`
- [Olden benchmarks](https://github.com/systems-nuts/unifico/tree/main/layout/olden): `layout/olden`
- [BFS benchmarks](https://github.com/systems-nuts/unifico/tree/main/layout/prim/bfs): `layout/prim/bfs`
- [NPB runner](https://github.com/systems-nuts/unifico/tree/main/npb/runs): `npb/runs`
- [SPEC runner](https://github.com/systems-nuts/unifico/blob/main/spec2017/run_spec.py): `spec2017/run_spec.py`
- [PARSEC runner](https://github.com/systems-nuts/unifico/blob/main/parsec/run_parsec.py): `parsec/run_parsec.py`

### Analysis utilities

- [Benchmark analysis](https://github.com/systems-nuts/unifico/blob/main/npb/process_results.py): `npb/process_results.py`
- [Stack-depth plots](https://github.com/systems-nuts/unifico/blob/main/plots/stack-depth-and-size/main.py): `plots/stack-depth-and-size/main.py`
- [Stack assembly view](https://github.com/systems-nuts/unifico/blob/main/stack_ascii_printer/print_ascii_stack.py): `stack_ascii_printer/print_ascii_stack.py`
- [Register pressure](https://github.com/systems-nuts/unifico/tree/main/register-pressure): `register-pressure`

### Other components

- **Researcher**

## Connections

- Researcher → Unifico LLVM: builds with
- Researcher → Modified musl: selects runtime
- Unifico LLVM → ELF binary: emits binary
- Unifico LLVM → LLVM stack maps: emits maps
- Researcher → Symbol alignment: aligns symbols
- Symbol alignment → Metadata generator: precedes processing
- Researcher → Metadata generator: runs postprocessor
- Metadata generator → ELF binary: opens and updates
- Metadata generator → LLVM stack maps: loads maps
- Metadata generator → Metadata sections: adds sections
- Researcher → Call-site alignment: uses alignment tools
- Researcher → Stack-slot alignment: uses alignment tools
- Researcher → DynamoRIO clients: runs tracing client
- Researcher → Pin tools: runs instrumentation
- Pin tools → Pin postprocessing: produces access data
- Researcher → NPB runner: runs benchmarks
- Researcher → SPEC runner: runs benchmarks
- Researcher → PARSEC runner: runs benchmarks
- NPB runner → NPB benchmarks: runs workloads
- SPEC runner → ELF binary: executes binaries
- PARSEC runner → ELF binary: executes binaries
- Researcher → Olden benchmarks: runs workloads
- Researcher → BFS benchmarks: runs workloads
- NPB runner → Benchmark analysis: provides results
- Researcher → Stack-depth plots: analyzes stack profiles
- Researcher → Stack assembly view: inspects assembly
- Researcher → Register pressure: analyzes register use