How openbmc/phosphor-pid-control works
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