# arm-software/gator architecture

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

- Interactive diagram: https://gitdiagram.com/arm-software/gator
- Repository: https://github.com/arm-software/gator

## Overview

This project is a multi-component suite of performance monitoring and instrumentation tools designed for Arm-based environments. In particular, it provides an embedded agent (“barman”) for collecting raw performance data in bare-metal or embedded environments and the “gatord” daemon (along with related tools like “annotate” and “streamline_me.py”) for use on Linux/Android targets. The tools leverage Linux kernel interfaces (such as the perf_event API, tracepoints, ftrace, debugfs/sysfs) to capture performance metrics and debug information, then process and forward that data for analysis. The project also contains supporting libraries (for logging, IPC, asynchronous processing, etc.), build scripts for multiple target architectures, and even a Java-based notification component (“notify”).

##### Main Components
- Barman Embedded Agent: Shows its own C-based source tree (found under the “barman” directory) with sub-components that parse, generate, and process performance counter data and custom counter definitions.
- Gatord Daemon: The primary agent running on the target, found in the “daemon” directory. This is a large, multi-faceted C++ component, broken down into several modules:
– Core Daemon Functionality (e.g., main.cpp, configuration, initialization routines)
– Agent Framework: Multiple agents exist in subdirectories (agents/armnn, agents/ext_source, agents/perf, agents/perfetto, etc.) that handle specific performance sources and data collection tasks.
– IPC Mechanisms: Represent the “ipc” folder that defines protocols, message traits, and raw channels for inter-process communication.
– Asynchronous and Concurrent Processing: The “async” folder houses helper classes, continuations, and netlink/proc communication routines.
– Linux/Platform-Specific Modules: For Android-specific behaviors and Linux artifacts (found in the “android” and “linux” subdirectories) that interface with system-level resources.
- Annotation and Trace Tools: Represent “annotate” (the annotation tool with its streamline_annotate sources) and the “trace” directories (for event definitions, examples, and shared modules) that help mark and process performance data.
- Build and Configuration Infrastructure: Include CMake scripts, various build scripts (such as build-android.sh and build-linux.sh), and the vcpkg integration which governs dependencies and cross-compiling toolchains.
- External Dependencies and Libraries: Note the incorporated third-party code such as libsensors, and the licensing details that split responsibilities between GPL, BSD, and LGPL components.

##### Relationships & Data Flows
- How the Linux/Android operating system (with kernel interfaces like perf_event, ftrace, /proc, /sys) feeds performance data into the gatord daemon.
- Communication flow between the agents (via IPC channels defined in the “ipc” module) and the eventual data aggregation, logging, and notifying layers.
- Separate build pipelines (Android build and Linux build) that compile these components using toolchains defined in the “cmake” directory and build scripts.

##### Architectural Patterns & Design Principles
- Layered Architecture: Separate the low-level hardware/kernel interfacing (via Linux APIs and direct file system reads) from the higher-level agent logic, logging, and control interfaces.
- Modular Design: Emphasize the clear separation between distinct modules in the daemon (e.g., separate agents for different counter sources, asynchronous event handling, and IPC).
- Cross-Compilation & Portability: Highlight the design for both native Linux and Android targets, with CMake toolchain configurations provided for various architectures (aarch64, arm, etc.) and libc choices (musl vs. glibc).
- Extensibility: The presence of multiple “agent” directories and a rich configuration layer (with numerous XML, CMake, and Python scripts) indicates the system is designed to be extended with new performance metrics and drivers.

##### Additional Elements
- Annotations for IPC relationships, such as how messages flow between processes and how the daemon interfaces with external event sources.
- External interfaces (like trace events and vcpkg dependency management) which contribute to the overall system support and extendability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Operating System / Kernel Layer
    OS["Linux Kernel / Perf API / Sysfs"]:::os

    %% Barman Embedded Agent
    Barman["Barman Embedded Agent"]:::daemon

    %% Gatord Daemon Subgraph
    subgraph "Gatord Daemon"
        Core["Gatord Daemon Core"]:::daemon
        AF["Agent Framework"]:::daemon
            subgraph "Agents"
                Armnn["Armnn Agent<br/>(Hardware Counter Collection)"]:::agent
                Ext["Ext_Source Agent<br/>(External Data Sources)"]:::agent
                Perf["Perf Agent<br/>(Performance Counters)"]:::agent
                Perfetto["Perfetto Agent<br/>(Trace-based Metrics)"]:::agent
            end
        IPC["IPC Module"]:::ipc
        Async["Async Processing"]:::async
        Android["Android Modules"]:::daemon
        LinuxMod["Linux Modules"]:::daemon
    end

    %% Annotation and Trace Tools
    Annotate["Annotate Tool"]:::tools
    Trace["Trace Tools"]:::tools
    Streamline["Streamline_me.py"]:::tools

    %% Build and Configuration Infrastructure
    subgraph "Build & Configuration"
        CMake["CMake Config"]:::build
        BuildAndroid["build-android.sh"]:::build
        BuildLinux["build-linux.sh"]:::build
        Vcpkg["Vcpkg"]:::build
    end

    %% External Dependencies and Libraries
    subgraph "External Dependencies"
        Libsensors["libsensors"]:::external
        PerfExt["Perfetto External"]:::external
    end

    %% Java Notification Component
    Notify["Notify"]:::notify

    %% Data Flow / Relationships
    OS -->|"feeds"| Barman
    OS -->|"feeds"| Core
    Core -->|"initializes"| AF
    AF -->|"invokes"| Armnn
    AF -->|"invokes"| Ext
    AF -->|"invokes"| Perf
    AF -->|"invokes"| Perfetto
    AF -->|"communicates"| IPC
    AF -->|"triggers"| Async
    Core -->|"handles platform calls"| Android
    Core -->|"handles platform calls"| LinuxMod
    IPC -->|"sends notifications"| Notify
    Libsensors ---|"integrated with"| Core
    PerfExt ---|"integrated with"| AF
    CMake ---|"builds"| Barman
    CMake ---|"builds"| Core
    BuildAndroid ---|"builds target"| Core
    BuildLinux ---|"builds target"| Core
    Vcpkg ---|"manages deps"| Core
    OS ---|"interacts with"| Android
    OS ---|"interacts with"| LinuxMod
    AF ---|"annotates data"| Annotate
    AF ---|"annotates data"| Trace
    Annotate ---|"script"| Streamline

    %% Styles
    classDef os fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef daemon fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef agent fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef ipc fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef async fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef tools fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef external fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef notify fill:#FFDEAD,stroke:#000,stroke-width:2px;

    %% Click Events
    click Barman "https://github.com/arm-software/gator/tree/main/barman/"
    click Core "https://github.com/arm-software/gator/tree/main/daemon/"
    click AF "https://github.com/arm-software/gator/tree/main/daemon/agents/"
    click Armnn "https://github.com/arm-software/gator/tree/main/daemon/agents/armnn"
    click Ext "https://github.com/arm-software/gator/tree/main/daemon/agents/ext_source"
    click Perf "https://github.com/arm-software/gator/tree/main/daemon/agents/perf"
    click Perfetto "https://github.com/arm-software/gator/tree/main/daemon/agents/perfetto"
    click IPC "https://github.com/arm-software/gator/tree/main/daemon/ipc/"
    click Async "https://github.com/arm-software/gator/tree/main/daemon/async/"
    click Android "https://github.com/arm-software/gator/tree/main/daemon/android/"
    click LinuxMod "https://github.com/arm-software/gator/tree/main/daemon/linux/"
    click Annotate "https://github.com/arm-software/gator/tree/main/annotate/"
    click Trace "https://github.com/arm-software/gator/tree/main/trace/"
    click Streamline "https://github.com/arm-software/gator/blob/main/streamline_me.py"
    click BuildAndroid "https://github.com/arm-software/gator/blob/main/build-android.sh"
    click BuildLinux "https://github.com/arm-software/gator/blob/main/build-linux.sh"
    click CMake "https://github.com/arm-software/gator/tree/main/cmake/"
    click Libsensors "https://github.com/arm-software/gator/tree/main/daemon/libsensors/"
    click PerfExt "https://github.com/arm-software/gator/tree/main/ext/perfetto/"
    click Vcpkg "https://github.com/arm-software/gator/tree/main/vcpkg/"
    click Notify "https://github.com/arm-software/gator/tree/main/notify/"
```
