# mchehab/rasdaemon architecture

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

- Interactive diagram: https://gitdiagram.com/mchehab/rasdaemon
- Repository: https://github.com/mchehab/rasdaemon

## Overview

##### Project Type and Purpose
- This is a userspace daemon (rasdaemon) intended to collect and correlate hardware RAS (Reliability, Availability, Serviceability) events emitted by the Linux kernel (EDAC, MCE, PCIe AER, APEI, etc.). It reads kernel tracepoints via debugfs, dispatches events to specialized handlers, logs them (syslog/journald), and can optionally persist them in a SQLite database for later analysis.

##### File‐Structure Analysis
- Top level: build/configuration files (configure.ac, Makefile.am, m4/, .github/, scripts/, man/).
- Core code:
- rasdaemon.c – main daemon loop, trace event subscription, dispatch logic
- ras-*.c / ras-*.h – one handler pair per event type (ras-mce-handler.c, ras-aer-handler.c, ras-arm-handler.c, etc.)
- util/ras-mc-ctl.in – auxiliary CLI tool to query or inject events
- bitfield.c/h, queue.c/h, rbtree.c/h – internal data‐structure libraries
- trigger.c/h – logic for threshold‐based actions
- contrib/: test and injection scripts (edac-fake-inject, AER/MCE injectors)
- misc/: init scripts and systemd unit templates
- No GUI or web frontend—pure daemon + CLI tools.

##### README Insights
- Describes concepts: tracepoint-based event collection, user‐space policy engine, optional SQLite storage, syslog/journal integration, and how to compile/install/run.
- Mentions optional features (--enable-sqlite3, --enable-aer, --enable-mce) toggling backends and event types.

##### Main Components
a. Kernel Event Sources
- EDAC drivers, Machine Check (MCE) driver, PCIe AER, APEI—each exposing tracepoints under debugfs.
b. libtraceevent Layer
- Subscribes to kernel tracepoints, parses raw events into in‐memory structures.
c. rasdaemon Core
- Central event loop (rasdaemon.c) that:
- Reads events from trace pipe
- Dispatches to the correct handler module based on event type
- Maintains internal state (queues, rbtrees) for deduplication, correlation
- Applies trigger logic (thresholds, burst detection) via trigger.c
d. Handler Modules
- One per event family (ras-mce-handler, ras-aer-handler, ras-devlink-handler, etc.)
- Convert generic trace data into a unified RAS event representation
e. Output Backends
- Syslog/journald logger (built‐in)
- SQLite3 storage (if enabled): schema defined in code, persistent DB file
f. Auxiliary Tools and Scripts
- ras-mc-ctl: CLI front end for ad-hoc queries or error decoding
- contrib scripts: event injectors for testing
- systemd unit / init scripts for service management

##### Relationships and Data Flows
- Kernel → debugfs tracepoint files → libtraceevent → rasdaemon core → handler modules → output backends → syslog/journal or SQLite.
- Auxiliary CLI (ras-mc-ctl) ↔ SQLite DB or live daemon via IPC (if implemented).
- contrib scripts → kernel injection modules → test events into the same pipeline.

##### Architectural Patterns and Design Principles
- Modular handler pattern: new event types simply add new ras-*-handler modules.
- Single-threaded event loop for simplicity and ordering guarantees.
- Pluggable backends (logging vs. database) toggled at compile time.
- Lightweight data structures (queues, rbtree) for in-memory state and event correlation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Kernel RAS Tracepoints"
        EDAC["EDAC"]:::kernel
        MCE["MCE"]:::kernel
        AER["PCIe AER"]:::kernel
        APEI["APEI"]:::kernel
    end

    EDAC -->|"debugfs tracepipe"| TRACEPIPE["tracepipe"]:::core
    MCE -->|"debugfs tracepipe"| TRACEPIPE
    AER -->|"debugfs tracepipe"| TRACEPIPE
    APEI -->|"debugfs tracepipe"| TRACEPIPE

    TRACEPIPE --> LIB["libtraceevent\n(tracepipe subscriber)"]:::core
    click LIB "https://github.com/mchehab/rasdaemon/blob/master/ras-events.c"

    LIB --> CORE["rasdaemon core loop"]:::core
    click CORE "https://github.com/mchehab/rasdaemon/blob/master/rasdaemon.c"

    subgraph "Internal Data Structures"
        BIT["bitfield"]:::core
        QUEUE["queue"]:::core
        RBT["rbtree"]:::core
    end

    CORE --> BIT
    CORE --> QUEUE
    CORE --> RBT

    click BIT "https://github.com/mchehab/rasdaemon/blob/master/bitfield.c"
    click QUEUE "https://github.com/mchehab/rasdaemon/blob/master/queue.c"
    click RBT "https://github.com/mchehab/rasdaemon/blob/master/rbtree.c"

    subgraph "Trigger Engine"
        TRIG["trigger logic"]:::core
    end

    CORE --> TRIG
    click TRIG "https://github.com/mchehab/rasdaemon/blob/master/trigger.c"

    subgraph "Handler Modules"
        AERH["ras-aer-handler"]:::handler
        ARMH["ras-arm-handler"]:::handler
        CXLH["ras-cxl-handler"]:::handler
        DEV["ras-devlink-handler"]:::handler
        DISK["ras-diskerror-handler"]:::handler
        EXT["ras-extlog-handler"]:::handler
        MCH["ras-mc-handler"]:::handler
        MCEH["ras-mce-handler"]:::handler
        MEMF["ras-memory-failure-handler"]:::handler
        NONSTD["ras-non-standard-handler"]:::handler
        PISO["ras-page-isolation"]:::handler
        CISO["ras-cpu-isolation"]:::handler
    end

    CORE --> AERH
    CORE --> ARMH
    CORE --> CXLH
    CORE --> DEV
    CORE --> DISK
    CORE --> EXT
    CORE --> MCH
    CORE --> MCEH
    CORE --> MEMF
    CORE --> NONSTD
    CORE --> PISO
    CORE --> CISO

    click AERH "https://github.com/mchehab/rasdaemon/blob/master/ras-aer-handler.c"
    click ARMH "https://github.com/mchehab/rasdaemon/blob/master/ras-arm-handler.c"
    click CXLH "https://github.com/mchehab/rasdaemon/blob/master/ras-cxl-handler.c"
    click DEV "https://github.com/mchehab/rasdaemon/blob/master/ras-devlink-handler.c"
    click DISK "https://github.com/mchehab/rasdaemon/blob/master/ras-diskerror-handler.c"
    click EXT "https://github.com/mchehab/rasdaemon/blob/master/ras-extlog-handler.c"
    click MCH "https://github.com/mchehab/rasdaemon/blob/master/ras-mc-handler.c"
    click MCEH "https://github.com/mchehab/rasdaemon/blob/master/ras-mce-handler.c"
    click MEMF "https://github.com/mchehab/rasdaemon/blob/master/ras-memory-failure-handler.c"
    click NONSTD "https://github.com/mchehab/rasdaemon/blob/master/ras-non-standard-handler.c"
    click PISO "https://github.com/mchehab/rasdaemon/blob/master/ras-page-isolation.c"
    click CISO "https://github.com/mchehab/rasdaemon/blob/master/ras-cpu-isolation.c"

    TRIG -->|applied to| AERH
    TRIG -->|applied to| ARMH

    subgraph "Output Backends"
        SYSLOG["Syslog / journald"]:::backend
        SQLITE["SQLite Storage"]:::backend
    end

    click SYSLOG "https://github.com/mchehab/rasdaemon/blob/master/ras-report.c"
    click SQLITE "https://github.com/mchehab/rasdaemon/blob/master/ras-record.c"

    AERH,ARMH,CXLH,DEV,DISK,EXT,MCH,MCEH,MEMF,NONSTD,PISO,CISO --> SYSLOG
    AERH,ARMH,CXLH,DEV,DISK,EXT,MCH,MCEH,MEMF,NONSTD,PISO,CISO --> SQLITE

    subgraph "Auxiliary Tools / Scripts"
        CLI["ras-mc-ctl CLI"]:::aux
        SCRIPTS["contrib scripts"]:::aux
        SYSTEMD["systemd / init scripts"]:::aux
    end

    click CLI "https://github.com/mchehab/rasdaemon/blob/master/util/ras-mc-ctl.in"
    click SCRIPTS "https://github.com/mchehab/rasdaemon/tree/master/contrib/"
    click SYSTEMD "https://github.com/mchehab/rasdaemon/tree/master/misc/"

    CLI --> CORE
    CLI --> SQLITE
    SCRIPTS --> TRACEPIPE
    SCRIPTS --> CORE
    SYSTEMD --> CORE

    classDef kernel fill:#ffe6e6,stroke:#ff0000
    classDef core fill:#e6f0ff,stroke:#0000ff
    classDef handler fill:#e6ffe6,stroke:#00aa00
    classDef backend fill:#fff0e6,stroke:#ff8800
    classDef aux fill:#f0f0f0,stroke:#888888
```
