# ivosh/valgrind architecture

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

- Interactive diagram: https://gitdiagram.com/ivosh/valgrind
- Repository: https://github.com/ivosh/valgrind

## Overview

Valgrind is a dynamic binary instrumentation framework: a user launches a client program under a selected analysis tool, the runtime translates and executes its code while the tool observes it, and the tool reports errors or profiling results. The graph preserves the major production and experimental tool families named in the README. Source excerpts here mainly establish shared interfaces and utility responsibilities; most runtime call relationships are not shown, so workflow links are marked dashed and unverified rather than presented as inspected calls.

Main entry points: [`include/pub_tool_tooliface.h`](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_tooliface.h) (Tool API), [`coregrind/m_main.c`](https://github.com/ivosh/valgrind/blob/master/coregrind/m_main.c) (Valgrind Runtime), [`coregrind/m_scheduler/scheduler.c`](https://github.com/ivosh/valgrind/blob/master/coregrind/m_scheduler/scheduler.c) (Execution Scheduler), [`VEX/pub/libvex.h`](https://github.com/ivosh/valgrind/blob/master/VEX/pub/libvex.h) (VEX Translator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_launcher["Valgrind Runtime<br/>[m_main.c]"]
  node_scheduler["Execution Scheduler<br/>[scheduler.c]"]
  node_syscalls["Syscall Wrappers<br/>[syswrap-linux.c]"]
  node_coreapi["Core Support API<br/>[pub_core_basics.h]"]
end

subgraph group_translation["Code Translation"]
  node_vex["VEX Translator<br/>[libvex.h]"]
end

subgraph group_interfaces["Tool Interface"]
  node_toolapi["Tool API"]
  node_toolbasics["Tool Utilities<br/>[pub_tool_basics.h]"]
  node_tooloptions["Tool Options<br/>[pub_tool_options.h]"]
  node_toolmemory["Tool Memory"]
  node_toolmachine["Machine Interface<br/>[pub_tool_machine.h]"]
  node_tooldebug["Debug Info API"]
  node_toolgdb["Debugger API"]
end

subgraph group_tools["Analysis Tools"]
  node_memcheck["Memcheck<br/>[mc_main.c]"]
  node_helgrind["Helgrind<br/>[hg_main.c]"]
  node_drd["DRD<br/>[drd_main.c]"]
  node_cachegrind["Cachegrind<br/>[cg_main.c]"]
  node_callgrind["Callgrind<br/>[main.c]"]
  node_massif["Massif<br/>[ms_main.c]"]
  node_sgcheck["SGCheck<br/>[sg_main.c]"]
  node_dhat["DHAT<br/>[dh_main.c]"]
  node_bbv["BBV<br/>[bbv_main.c]"]
end

subgraph group_outputs["Analysis Results"]
  node_reports["Reports and Profiles"]
end

node_user(("User"))
node_client["Client Program"]

node_user -.->|"launches"| node_launcher
node_user -.->|"selects"| node_client
node_launcher -.->|"runs under"| node_client
node_launcher -.->|"dispatches execution"| node_scheduler
node_scheduler -.->|"translates code"| node_vex
node_vex -.->|"returns translations"| node_scheduler
node_scheduler -.->|"invokes tool"| node_toolapi
node_launcher -.->|"configures"| node_tooloptions
node_launcher -.->|"wraps syscalls"| node_syscalls
node_toolapi -.->|"uses utilities"| node_toolbasics
node_toolapi -.->|"uses allocation"| node_toolmemory
node_toolapi -.->|"uses machine info"| node_toolmachine
node_toolapi -.->|"uses debug info"| node_tooldebug
node_toolapi -.->|"offers debugger hooks"| node_toolgdb
node_toolapi -.->|"hosts"| node_memcheck
node_toolapi -.->|"hosts"| node_helgrind
node_toolapi -.->|"hosts"| node_drd
node_toolapi -.->|"hosts"| node_cachegrind
node_toolapi -.->|"hosts"| node_callgrind
node_toolapi -.->|"hosts"| node_massif
node_toolapi -.->|"hosts experimental"| node_sgcheck
node_toolapi -.->|"hosts experimental"| node_dhat
node_toolapi -.->|"hosts experimental"| node_bbv
node_memcheck -.->|"reports memory errors"| node_reports
node_helgrind -.->|"reports thread errors"| node_reports
node_drd -.->|"reports thread errors"| node_reports
node_cachegrind -.->|"profiles cache"| node_reports
node_callgrind -.->|"profiles call graph"| node_reports
node_massif -.->|"profiles heap"| node_reports
node_sgcheck -.->|"detects overruns"| node_reports
node_dhat -.->|"profiles heap"| node_reports
node_bbv -.->|"generates vectors"| node_reports

click node_launcher "https://github.com/ivosh/valgrind/blob/master/coregrind/m_main.c"
click node_scheduler "https://github.com/ivosh/valgrind/blob/master/coregrind/m_scheduler/scheduler.c"
click node_syscalls "https://github.com/ivosh/valgrind/blob/master/coregrind/m_syswrap/syswrap-linux.c"
click node_coreapi "https://github.com/ivosh/valgrind/blob/master/coregrind/pub_core_basics.h"
click node_toolapi "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_tooliface.h"
click node_toolbasics "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_basics.h"
click node_tooloptions "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_options.h"
click node_toolmemory "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_mallocfree.h"
click node_toolmachine "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_machine.h"
click node_tooldebug "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_debuginfo.h"
click node_toolgdb "https://github.com/ivosh/valgrind/blob/master/include/pub_tool_gdbserver.h"
click node_vex "https://github.com/ivosh/valgrind/blob/master/VEX/pub/libvex.h"
click node_memcheck "https://github.com/ivosh/valgrind/blob/master/memcheck/mc_main.c"
click node_helgrind "https://github.com/ivosh/valgrind/blob/master/helgrind/hg_main.c"
click node_drd "https://github.com/ivosh/valgrind/blob/master/drd/drd_main.c"
click node_cachegrind "https://github.com/ivosh/valgrind/blob/master/cachegrind/cg_main.c"
click node_callgrind "https://github.com/ivosh/valgrind/blob/master/callgrind/main.c"
click node_massif "https://github.com/ivosh/valgrind/blob/master/massif/ms_main.c"
click node_sgcheck "https://github.com/ivosh/valgrind/blob/master/exp-sgcheck/sg_main.c"
click node_dhat "https://github.com/ivosh/valgrind/blob/master/exp-dhat/dh_main.c"
click node_bbv "https://github.com/ivosh/valgrind/blob/master/exp-bbv/bbv_main.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_launcher,node_scheduler,node_syscalls,node_coreapi,node_user,node_client toneBlue
class node_vex toneAmber
class node_toolapi,node_toolbasics,node_tooloptions,node_toolmemory,node_toolmachine,node_tooldebug,node_toolgdb toneMint
class node_memcheck,node_helgrind,node_drd,node_cachegrind,node_callgrind,node_massif,node_sgcheck,node_dhat,node_bbv toneRose
class node_reports toneIndigo
```

## Components

### Runtime

- [Valgrind Runtime](https://github.com/ivosh/valgrind/blob/master/coregrind/m_main.c): `coregrind/m_main.c`
- [Execution Scheduler](https://github.com/ivosh/valgrind/blob/master/coregrind/m_scheduler/scheduler.c): `coregrind/m_scheduler/scheduler.c`
- [Syscall Wrappers](https://github.com/ivosh/valgrind/blob/master/coregrind/m_syswrap/syswrap-linux.c): `coregrind/m_syswrap/syswrap-linux.c`
- [Core Support API](https://github.com/ivosh/valgrind/blob/master/coregrind/pub_core_basics.h): `coregrind/pub_core_basics.h`

### Code Translation

- [VEX Translator](https://github.com/ivosh/valgrind/blob/master/VEX/pub/libvex.h): `VEX/pub/libvex.h`

### Tool Interface

- [Tool API](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_tooliface.h): `include/pub_tool_tooliface.h`
- [Tool Utilities](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_basics.h): `include/pub_tool_basics.h`
- [Tool Options](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_options.h): `include/pub_tool_options.h`
- [Tool Memory](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_mallocfree.h): `include/pub_tool_mallocfree.h`
- [Machine Interface](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_machine.h): `include/pub_tool_machine.h`
- [Debug Info API](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_debuginfo.h): `include/pub_tool_debuginfo.h`
- [Debugger API](https://github.com/ivosh/valgrind/blob/master/include/pub_tool_gdbserver.h): `include/pub_tool_gdbserver.h`

### Analysis Tools

- [Memcheck](https://github.com/ivosh/valgrind/blob/master/memcheck/mc_main.c): `memcheck/mc_main.c`
- [Helgrind](https://github.com/ivosh/valgrind/blob/master/helgrind/hg_main.c): `helgrind/hg_main.c`
- [DRD](https://github.com/ivosh/valgrind/blob/master/drd/drd_main.c): `drd/drd_main.c`
- [Cachegrind](https://github.com/ivosh/valgrind/blob/master/cachegrind/cg_main.c): `cachegrind/cg_main.c`
- [Callgrind](https://github.com/ivosh/valgrind/blob/master/callgrind/main.c): `callgrind/main.c`
- [Massif](https://github.com/ivosh/valgrind/blob/master/massif/ms_main.c): `massif/ms_main.c`
- [SGCheck](https://github.com/ivosh/valgrind/blob/master/exp-sgcheck/sg_main.c): `exp-sgcheck/sg_main.c`
- [DHAT](https://github.com/ivosh/valgrind/blob/master/exp-dhat/dh_main.c): `exp-dhat/dh_main.c`
- [BBV](https://github.com/ivosh/valgrind/blob/master/exp-bbv/bbv_main.c): `exp-bbv/bbv_main.c`

### Analysis Results

- **Reports and Profiles**

### Other components

- **User**
- **Client Program**

## Connections

- User → Valgrind Runtime: launches (evidence: `README`)
- User → Client Program: selects (evidence: `README`)
- Valgrind Runtime → Client Program: runs under (evidence: `README`)
- Valgrind Runtime → Execution Scheduler: dispatches execution
- Execution Scheduler → VEX Translator: translates code
- VEX Translator → Execution Scheduler: returns translations
- Execution Scheduler → Tool API: invokes tool
- Valgrind Runtime → Tool Options: configures
- Valgrind Runtime → Syscall Wrappers: wraps syscalls
- Tool API → Tool Utilities: uses utilities
- Tool API → Tool Memory: uses allocation
- Tool API → Machine Interface: uses machine info
- Tool API → Debug Info API: uses debug info
- Tool API → Debugger API: offers debugger hooks
- Tool API → Memcheck: hosts (evidence: `README`)
- Tool API → Helgrind: hosts (evidence: `README`)
- Tool API → DRD: hosts (evidence: `README`)
- Tool API → Cachegrind: hosts (evidence: `README`)
- Tool API → Callgrind: hosts (evidence: `README`)
- Tool API → Massif: hosts (evidence: `README`)
- Tool API → SGCheck: hosts experimental (evidence: `README`)
- Tool API → DHAT: hosts experimental (evidence: `README`)
- Tool API → BBV: hosts experimental (evidence: `README`)
- Memcheck → Reports and Profiles: reports memory errors (evidence: `README`)
- Helgrind → Reports and Profiles: reports thread errors (evidence: `README`)
- DRD → Reports and Profiles: reports thread errors (evidence: `README`)
- Cachegrind → Reports and Profiles: profiles cache (evidence: `README`)
- Callgrind → Reports and Profiles: profiles call graph (evidence: `README`)
- Massif → Reports and Profiles: profiles heap (evidence: `README`)
- SGCheck → Reports and Profiles: detects overruns (evidence: `README`)
- DHAT → Reports and Profiles: profiles heap (evidence: `README`)
- BBV → Reports and Profiles: generates vectors (evidence: `README`)