# openbmc/phosphor-pid-control architecture

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

- Interactive diagram: https://gitdiagram.com/openbmc/phosphor-pid-control
- Repository: https://github.com/openbmc/phosphor-pid-control

## Overview

##### Project Type & Purpose
- Type: A C++ multi-threaded daemon for OpenBMC
- Purpose: Monitor temperatures and control fan speeds via PID loops.
- Key integrations:
– Local sensors (sysfs, phosphor-hwmon via D-Bus)
– IPMI OEM commands (via ipmid)
– Host-side tooling updates (Set Sensor, Set Fan PWM)
– Logging & tuning interfaces

##### File Structure & Modules
– Top-level daemon entry: main.cpp
– Configuration parsing: buildjson/ & configure.md
– IPC & messaging:
- dbus/  (read/write interfaces, helper, passive mode)
- ipmi/  (OEM handlers, main_ipmi.cpp)
– Sensor abstraction: sensors/  (pluggable sensors, manager)
– Sysfs I/O: sysfs/  (read/write utilities)
– PID logic: pid/  (zone definitions, controller, EC implementation)
– Failsafe logging: failsafeloggers/
– Experiments & examples: experiments/, examples/
– Tests: test/  (unit tests for each module)
– Build system: meson.build, subprojects/ (third-party wraps)

##### Pull Architectural Insights from README
– Multi-threaded:
- Main thread: loads config, registers D-Bus OEM handler
- One control thread per zone (PID loop)
- Background thread(s) for incoming sensor/fan tach updates
– Data flows: sensors → PID loops → fan PWM
– External calls: IPMI → D-Bus → host updates
– Logging & tuning toggle via command-line flags

##### Main Components & Boundaries
1. phosphor-pid-control Daemon
- Main Thread
- Zone Control Threads (one per zone)
- Sensor Update Thread
2. Sensor Layer
- sysfs module (direct file I/O)
- dbus reader module (sdbusplus)
- IPMI “set sensor” injections (ipmi module)
- pluggable sensor interface
3. PID Layer
- Zone definition & builder
- PID algorithm (EC PID, stepwise, tuning)
- Fan controller (RPM ↔ PWM translation)
4. DBus IPC
- phosphor-hwmon service (fan tach, thermal updates)
- phosphor-pid-control’s D-Bus interfaces & handlers
5. IPMI Interface
- ipmid OEM handler
- Forwarding updates as D-Bus property signals
6. Failsafe Logging & Tuning
- Per-zone log files via failsafeloggers module
- Tuning flags & data capture
7. External Tools
- Host-side IPMI tools (Set Sensor / Set Fan PWM)
- Configuration generators (scripts converting YAML → JSON/C++)

##### Relationships & Data Flows
– On startup:
Main Thread → parse config files → build JSON → instantiate zones
Main Thread → register D-Bus OEM and property change handlers
– Sensor updates:
phosphor-hwmon → D-Bus signals → Sensor Update Thread → update sensor cache
OR  sysfs reader → direct file read → update sensor cache
OR  IPMI “set sensor” → OEM handler → emits D-Bus property update
– Control loops:
Zone Thread (10 Hz PID tick)
reads sensor cache → computes target RPM → issues PWM writes (via sysfs or dbus)
– Logging:
Zone Thread → failsafeloggers → writes zone_{zoneid}.log
– Tuning:
optional capture of PID internal states to logs

##### Architectural Patterns & Principles
– Modular layering: I/O → sensor abstraction → PID logic → actuator
– Dependency injection / builder pattern for pluggable sensors and controllers
– Event-driven updates via D-Bus signals
– Concurrency: one thread per control loop + main / background threads
– Separation of concerns: IPMI handler only deals with OEM messages and hands off to D-Bus

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef thread fill:#f39c12,stroke:#333,stroke-width:1px
    classDef compute fill:#3498db,stroke:#333,stroke-width:1px
    classDef io fill:#2ecc71,stroke:#333,stroke-width:1px
    classDef external fill:#7f8c8d,stroke:#333,stroke-width:1px

    subgraph "Daemon Threads"
        MT["Main Thread"]:::thread
        SUT["Sensor Update Thread"]:::thread
        ZCT["Zone Control Threads\n(one per zone, 10Hz)"]:::thread
    end

    subgraph "Configuration Parsing"
        BJSON["buildjson module"]:::compute
        CFGMD["configure.md"]:::compute
    end

    subgraph "Sensor Layer"
        SYR["sysfs reader\n(sysfs/sysfsread.cpp)"]:::io
        SYW["sysfs writer\n(sysfs/sysfswrite.cpp)"]:::io
        DBR["dbus passive reader\n(dbus/dbuspassive.cpp)"]:::io
        DBRW["dbus writer\n(dbus/dbuswrite.cpp)"]:::io
        SENSM["sensors::Manager"]:::io
    end

    subgraph "IPMI Interface"
        IPOEM["OEM Handler\n(ipmi/main_ipmi.cpp)"]:::io
    end

    subgraph "PID Control Layer"
        PB["pid::Builder\n(pid/builder.cpp)"]:::compute
        PLOOP["pid::PIDLoop\n(pid/pidloop.cpp)"]:::compute
        FPWM["Fan Controller\n(pid/fancontroller.cpp)"]:::compute
    end

    subgraph "Failsafe Logging"
        FLOG["failsafeloggers::Builder\n(failsafeloggers/builder.cpp)"]:::compute
    end

    PHHM["phosphor-hwmon\ndbus service"]:::external
    IPMID["ipmid daemon"]:::external
    HTOOLS["Host Tools\n(IPMI set sensor/PWM)"]:::external

    MT -->|"parse config"| BJSON
    BJSON -->|"instantiate zones"| PB
    MT -->|"register D-Bus OEM"| IPOEM
    MT -->|"start sensor listener"| DBR
    MT -->|"launch zone threads"| ZCT

    PHHM -->|"DBusSignal"| DBR
    DBR -->|"update cache"| SENSM
    SYR -->|"ReadTemp"| SENSM
    IPOEM -->|"DBusSignal"| SENSM
    IPMID -->|"OEMCall"| IPOEM
    HTOOLS -->|"IPMI Calls"| IPMID

    SENSM -->|"sensor data"| ZCT
    ZCT -->|"read cache"| SENSM
    ZCT -->|"compute RPM"| PLOOP
    PLOOP -->|"calc PWM"| FPWM
    FPWM -->|"SetPWM"| SYW
    ZCT -->|"log data"| FLOG

    click MT "https://github.com/openbmc/phosphor-pid-control/blob/master/main.cpp"
    click BJSON "https://github.com/openbmc/phosphor-pid-control/tree/master/buildjson/"
    click CFGMD "https://github.com/openbmc/phosphor-pid-control/blob/master/configure.md"
    click SYR "https://github.com/openbmc/phosphor-pid-control/blob/master/sysfs/sysfsread.cpp"
    click SYW "https://github.com/openbmc/phosphor-pid-control/blob/master/sysfs/sysfswrite.cpp"
    click DBR "https://github.com/openbmc/phosphor-pid-control/blob/master/dbus/dbuspassive.cpp"
    click DBRW "https://github.com/openbmc/phosphor-pid-control/blob/master/dbus/dbuswrite.cpp"
    click SENSM "https://github.com/openbmc/phosphor-pid-control/blob/master/sensors/manager.cpp"
    click IPOEM "https://github.com/openbmc/phosphor-pid-control/blob/master/ipmi/main_ipmi.cpp"
    click PB "https://github.com/openbmc/phosphor-pid-control/blob/master/pid/builder.cpp"
    click PLOOP "https://github.com/openbmc/phosphor-pid-control/blob/master/pid/pidloop.cpp"
    click FPWM "https://github.com/openbmc/phosphor-pid-control/blob/master/pid/fancontroller.cpp"
    click FLOG "https://github.com/openbmc/phosphor-pid-control/blob/master/failsafeloggers/builder.cpp"
```
