# openbmc/phosphor-gpio-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/openbmc/phosphor-gpio-monitor
- Repository: https://github.com/openbmc/phosphor-gpio-monitor

## Overview

##### Project Type and Purpose
- This is a set of Linux system daemons (C++ services) for monitoring GPIO lines, triggering systemd services, or updating inventory presence over D-Bus.
- Key deliverables:
- `phosphor-gpio-monitor` (single line)
- `phosphor-multi-gpio-monitor` (multi-line, JSON-driven)
- `phosphor-multi-gpio-presence` (multi-line, JSON-driven presence via D-Bus)

##### Main Components
A. Systemd & Service Units
- `phosphor-gpio-monitor@.service`
- `phosphor-multi-gpio-monitor.service` / JSON config
- `phosphor-multi-gpio-presence.service` / JSON config
B. Daemon Executables
- Single‐line monitor (`gpioMonMain.cpp`, `monitor.cpp`, `evdev.cpp`)
- Multi‐line monitor (`multi-presence/main.cpp`, `gpio_presence.cpp`)
- Multi‐line presence (`presence/main.cpp`, `gpio_presence.cpp`)
C. Configuration Files
- `phosphor-multi-gpio-monitor.json`
- `phosphor-multi-gpio-presence.json`
D. Libraries & Frameworks
- libgpiod (GPIO kernel interface)
- CLI11 (command-line parsing)
- nlohmann_json (JSON parsing)
- sdbusplus / phosphor-logging (D-Bus & logging)
E. Kernel & D-Bus Subsystems
- GPIO character devices (e.g. `/dev/gpiochipN`)
- systemd (service management, journal)
- OpenBMC inventory D-Bus interfaces

##### Relationships & Data Flows
1. systemd service unit starts the daemon, passing either GPIO line parameters or JSON config path.
2. Daemon uses CLI11 to parse arguments.
3. Daemon loads JSON via nlohmann_json (if multi-line).
4. Daemon opens GPIO lines through libgpiod → kernel.
5. On GPIO events (FALLING/RISING):
- Log event to systemd journal via phosphor-logging.
- For monitor daemons: optionally invoke other systemd units (Targets).
- For presence daemon: call sdbusplus APIs to set inventory presence on D-Bus.
6. Daemon either continues monitoring (Continue=true) or exits after first event.

##### Architectural Patterns & Principles
- Configuration-driven architecture (JSON describes all monitored lines).
- Event‐driven design (callback on GPIO edge events).
- Separation of concerns: CLI, JSON parsing, GPIO access, business logic, logging, D-Bus.
- Reuse through shared code modules (`gpioMon.hpp/.cpp`, `monitor.hpp/.cpp`, `evdev.hpp/.cpp`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External subsystem: systemd
    systemd["systemd (service manager)"]:::ext

    subgraph "Systemd & Service Units"
        S1["phosphor-gpio-monitor@.service"]:::service
        S2["phosphor-multi-gpio-monitor.service"]:::service
        S3["phosphor-multi-gpio-presence.service"]:::service
    end

    systemd --> S1
    systemd --> S2
    systemd --> S3

    subgraph "Daemon Processes"
        subgraph "phosphor-gpio-monitor"
            GPOMain["gpioMonMain.cpp"]:::code
            PhosphorMonCPP["gpioMon.cpp"]:::code
            PhosphorMonH["gpioMon.hpp"]:::code
            MonitorCPP["monitor.cpp"]:::code
            MonitorH["monitor.hpp"]:::code
            EvdevCPP["evdev.cpp"]:::code
            EvdevH["evdev.hpp"]:::code
        end
        subgraph "phosphor-multi-gpio-monitor"
            MonMulti["Multi-line Monitor Daemon"]:::daemon
        end
        subgraph "phosphor-multi-gpio-presence"
            PresMain["presence/main.cpp"]:::code
            PresCPP["presence/gpio_presence.cpp"]:::code
            PresH["presence/gpio_presence.hpp"]:::code
        end
    end

    S1 -->|starts| GPOMain
    S1 --> PhosphorMonCPP
    S1 --> PhosphorMonH
    S1 --> MonitorCPP
    S1 --> MonitorH
    S1 --> EvdevCPP
    S1 --> EvdevH

    S2 --> MonMulti
    S3 --> PresMain
    S3 --> PresCPP
    S3 --> PresH

    subgraph "Config Files"
        ConfigMonitor["phosphor-multi-gpio-monitor.json"]:::config
        ConfigPresence["phosphor-multi-gpio-presence.json"]:::config
    end

    MonMulti -->|"loads JSON"| ConfigMonitor
    PresMain -->|"loads JSON"| ConfigPresence

    subgraph "Common Library Code"
        FileH["file.hpp"]:::code
        MainApp["mainapp.cpp"]:::code
    end

    subgraph "Libraries & Frameworks"
        CLI11["CLI11"]:::lib
        JSONLib["nlohmann_json"]:::lib
        libgpiod["libgpiod"]:::lib
        sdbusplus["sdbusplus / phosphor-logging"]:::lib
    end

    CLI11 -->|CLI parsing| MonMulti
    CLI11 -->|CLI parsing| GPOMain
    CLI11 -->|CLI parsing| PresMain

    JSONLib -->|JSON parsing| MonMulti
    JSONLib -->|JSON parsing| PresMain

    MonMulti -->|libgpiod API| libgpiod
    GPOMain -->|libgpiod API| libgpiod
    PresMain -->|libgpiod API| libgpiod

    libgpiod -->|kernel interface| Kernel["GPIO Kernel Subsystem"]:::ext
    MonMulti -->|journal| sdbusplus
    GPOMain -->|journal| sdbusplus
    PresMain -->|sdbusplus method calls| sdbusplus
    sdbusplus -->|D-Bus| DBus["OpenBMC Inventory D-Bus"]:::ext

    subgraph "External Subsystems"
        Kernel
        DBus
    end

    %% Click Events
    click S1 "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-gpio-monitor@.service"
    click S2 "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-multi-gpio-monitor.service"
    click S3 "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-multi-gpio-presence.service"
    click GPOMain "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/gpioMonMain.cpp"
    click PhosphorMonCPP "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/gpioMon.cpp"
    click PhosphorMonH "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/gpioMon.hpp"
    click MonitorCPP "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/monitor.cpp"
    click MonitorH "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/monitor.hpp"
    click EvdevCPP "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/evdev.cpp"
    click EvdevH "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/evdev.hpp"
    click MonMulti "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-multi-gpio-monitor.service"
    click PresMain "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/presence/main.cpp"
    click PresCPP "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/presence/gpio_presence.cpp"
    click PresH "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/presence/gpio_presence.hpp"
    click ConfigMonitor "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-multi-gpio-monitor.json"
    click ConfigPresence "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/phosphor-multi-gpio-presence.json"
    click FileH "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/file.hpp"
    click MainApp "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/mainapp.cpp"
    click CLI11 "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/subprojects/CLI11.wrap"
    click JSONLib "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/subprojects/nlohmann_json.wrap"
    click libgpiod "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/subprojects/libgpiod.wrap"
    click sdbusplus "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/subprojects/sdbusplus.wrap"
    click sdbusplus "https://github.com/openbmc/phosphor-gpio-monitor/blob/master/subprojects/phosphor-logging.wrap"

    %% Styles
    classDef daemon fill:#bbdefb,stroke:#1e88e5;
    classDef service fill:#90caf9,stroke:#1e88e5;
    classDef config fill:#c8e6c9,stroke:#388e3c;
    classDef lib fill:#ffe0b2,stroke:#ef6c00;
    classDef ext fill:#eeeeee,stroke:#616161;
    classDef code fill:#e3f2fd,stroke:#42a5f5;
```
