# frida/frida-gum architecture

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

- Interactive diagram: https://gitdiagram.com/frida/frida-gum
- Repository: https://github.com/frida/frida-gum

## Overview

##### Project type and purpose
- Type: Open-source C library (instrumentation & introspection).
- Purpose: Provide cross-platform inline hooking (Interceptor), code tracing (Stalker), memory monitoring, process/module introspection, code generation/relocation, plus helper libs for heap tracking & profiling.
- Consumers: frida-core (via GumJS), standalone C/C++ projects (via devkit), language bindings.

##### File structure
- Top-level “gum/”: Core C API (gum.c, guminterceptor.h, gumstalker.h, etc.).
- “gum/arch-*” & “gum/backend-*”: Architecture-specific code generators & interceptors (x86, ARM, MIPS, ARM64).
- “bindings/gumjs/”: JavaScript runtime binding layer (QuickJS, V8).
- “libs/gum/heap” & “libs/gum/prof”: Helper libraries for heap instrumentation & profiling.
- “ext/” & “subprojects/”: External dependencies (libffi, V8, QuickJS, OpenSSL, etc.) managed by Meson.
- “tests/”: Comprehensive test suites for core, arch, heap, prof, gumjs, gumpp.
- “tools/”: Utility scripts for versioning, grafting, symbolication.

##### README for architecture clues
- Core capabilities listed under “Provides:” section.
- Links to individual components (Interceptor, Stalker, MemoryAccessMonitor).
- Mentions devkit for static linking, out-of-process dynamic linker (Darwin).
- Highlights codegen & relocation modules per architecture.

a. Main components
- Core C API: gum.c / gum.h – provides public hooks (Interceptor, Stalker, MemoryAccessMonitor, introspection APIs).
- Arch-specific modules: arch-*/ backends produce machine code generators, relocators, readers, writers.
- Platform backends: backend-linux, backend-windows, backend-darwin, etc. – implement process, memory, symbol lookups per OS.
- Devkit: static library release for consumer integration.
- JS Bindings: bindings/gumjs – exposes C API to JS runtimes (QuickJS, V8).
- Helper libs: libs/gum/heap (allocation tracking), libs/gum/prof (profilers).
- External deps: subprojects (QuickJS, V8, libffi, SQLite, Capstone).
- Tests & Tools: validation & utility layers.

b. Relationships & interactions
- Core C API calls into arch-modules and platform backends via well-defined headers.
- JS Binding Layer invokes Core C API through `generate-bindings.py` runtime wrappers.
- Helper libs consume Core instrumentation hooks (e.g., Stalker events) to track allocations or sample performance.
- Tests drive the Core API, arch backends and helper libs, verifying behavior on each architecture and OS.
- Build system (Meson/Makefile) orchestrates compilation of core, subprojects, tests and bindings.

c. Architectural patterns & design principles
- Plugin-style: arch and backend modules register themselves at runtime.
- Layered: Core API → Architecture codegen/relocation → Platform abstraction → Consumer bindings.
- Extensible: New architectures or OS backends can be added under `gum/arch-*` or `gum/backend-*`.
- Build isolation: Subprojects embedded via Meson wraps, enabling reproducible builds.

d. Key technologies
- Language: C99, C++ (in some modules & bindings).
- Build: Meson, Ninja, Make.
- JS engines: QuickJS, V8.
- Subproject management: Meson wraps.
- Testing: C fixtures, Python scripts, shell runners.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Core & API
  subgraph "Core C API"
    CORE["Core API\n(gum.c / gum.h)"] 
    INTERCEPT["Interceptor"]
    STALKER["Stalker"]
    MEMMON["MemoryAccessMonitor"]
    CORE --> INTERCEPT
    CORE --> STALKER
    CORE --> MEMMON
  end

  %% Architecture modules
  subgraph "Architecture Modules"
    ARM64["Arch-ARM64 Writer/Relocator"]
    X86["X86 Writer/Relocator"]
    MIPS["MIPS Writer/Relocator"]
    ARM["ARM/Thumb Writer/Relocator"]
    CORE --> ARM64
    CORE --> X86
    CORE --> MIPS
    CORE --> ARM
  end

  %% Platform backends
  subgraph "Platform Backends"
    DARWIN["backend-darwin"]
    LINUX["backend-linux"]
    WINDOWS["backend-windows"]
    BACK_ARM["backend-arm"]
    BACK_ARM64["backend-arm64"]
    CORE --> DARWIN
    CORE --> LINUX
    CORE --> WINDOWS
    CORE --> BACK_ARM
    CORE --> BACK_ARM64
  end

  %% Devkit
  subgraph "DevKit"
    DEVKIT["Static-linking Release"]
    CORE --> DEVKIT
  end

  %% JS Bindings
  subgraph "JS Bindings (GumJS)"
    QJS["QuickJS Runtime"]
    V8["V8 Runtime"]
    GEN["generate-bindings.py"]
    RUNTIME["generate-runtime.py"]
    JSBUILD["meson.build"]
    QJS --> GEN --> CORE
    V8 --> GEN
    GEN --> RUNTIME
  end

  %% Helper libraries
  subgraph "Helper Libraries"
    HEAP["libs/gum/heap"]
    PROF["libs/gum/prof"]
    HEAP --> CORE
    PROF --> CORE
  end

  %% External dependencies
  subgraph "Subprojects / ext"
    SUBP["subprojects/*.wrap"]
    EXT["ext/"]
    SUBP --> CORE
    EXT --> CORE
  end

  %% Tests & Tools
  subgraph "Tests & Tools"
    TESTS["tests/"]
    TOOLS["tools/"]
    TESTS --> CORE
    TESTS --> ARM64
    TESTS --> X86
    TESTS --> MIPS
    TESTS --> ARM
    TOOLS --> CORE
  end

  %% Styles
  classDef api fill:#bbdefb,stroke:#0d47a1
  classDef arch fill:#c8e6c9,stroke:#1b5e20
  classDef backend fill:#ffe0b2,stroke:#e65100
  classDef devkit fill:#b3e5fc,stroke:#01579b
  classDef jsb fill:#e1bee7,stroke:#4a148c
  classDef helper fill:#fff9c4,stroke:#f57f17
  classDef ext fill:#eceff1,stroke:#37474f
  classDef test fill:#f5f5f5,stroke:#9e9e9e

  class CORE,INTERCEPT,STALKER,MEMMON api
  class ARM64,X86,MIPS,ARM arch
  class DARWIN,LINUX,WINDOWS,BACK_ARM,BACK_ARM64 backend
  class DEVKIT devkit
  class QJS,V8,GEN,RUNTIME,JSBUILD jsb
  class HEAP,PROF helper
  class SUBP,EXT ext
  class TESTS,TOOLS test

  %% Click events
  click CORE "https://github.com/frida/frida-gum/blob/main/gum/gum.c"
  click ARM "https://github.com/frida/frida-gum/tree/main/gum/arch-arm/"
  click ARM64 "https://github.com/frida/frida-gum/tree/main/gum/arch-arm64/"
  click MIPS "https://github.com/frida/frida-gum/tree/main/gum/arch-mips/"
  click X86 "https://github.com/frida/frida-gum/tree/main/gum/arch-x86/"
  click DARWIN "https://github.com/frida/frida-gum/tree/main/gum/backend-darwin/"
  click LINUX "https://github.com/frida/frida-gum/tree/main/gum/backend-linux/"
  click WINDOWS "https://github.com/frida/frida-gum/tree/main/gum/backend-windows/"
  click BACK_ARM "https://github.com/frida/frida-gum/tree/main/gum/backend-arm/"
  click BACK_ARM64 "https://github.com/frida/frida-gum/tree/main/gum/backend-arm64/"
  click DEVKIT "https://github.com/frida/frida-gum/blob/main/gum/devkit/meson.build"
  click GEN "https://github.com/frida/frida-gum/blob/main/bindings/gumjs/generate-bindings.py"
  click RUNTIME "https://github.com/frida/frida-gum/blob/main/bindings/gumjs/generate-runtime.py"
  click JSBUILD "https://github.com/frida/frida-gum/blob/main/bindings/gumjs/meson.build"
  click HEAP "https://github.com/frida/frida-gum/tree/main/libs/gum/heap/"
  click PROF "https://github.com/frida/frida-gum/tree/main/libs/gum/prof/"
  click SUBP "https://github.com/frida/frida-gum/tree/main/subprojects/"
  click EXT "https://github.com/frida/frida-gum/tree/main/ext/"
  click TESTS "https://github.com/frida/frida-gum/tree/main/tests/"
  click TOOLS "https://github.com/frida/frida-gum/tree/main/tools/"
```
