openbmc/phosphor-pid-control/README.md

1 # phosphor-pid-control
3 This is a daemon running within the OpenBMC environment. It uses a well-defined
5 them within operating conditions. It may require coordination with host-side
10 The BMC will run a daemon that controls the fans by pre-defined zones. The
13 sensors as well as host-provided information over an IPMI OEM command.
17 least one temperature sensor and some device margins. The sensor data can be
26 [How to configure phosphor-pid-control](configure.md)
30 The software will run as a multi-threaded daemon that runs a control loop for
38 phosphor-hwmon are laid out.
45 must have at least one temperature sensor, but they may be shared.
54 ### IPMI Access to Phosphor-pid-control
56 [OEM-IPMI Definitions](ipmi.md)
58 #### Set Sensor Value
62 sensors that are updated by the set sensor command. Because they don't represent
63 real sensors in the system, the set sensor handler can simply broadcast the
68 A tool can override a specific fan's PWM when we implement the set sensor IPMI
76 ### Sensor Update Loop
79 This will receive an update from phosphor-hwmon each time it updates any sensor
82 By default phosphor-hwmon reads each sensor in turn and then sleeps for 1
83 second. We'll be updating phosphor-hwmon to sleep for a shorter period -- how
84 short though is still TBD. We'll also be updating phosphor-hwmon to support pwm
92 We'll be receiving sensor updates with such regularly, however, at present it
94 the system to its knees -- in that all CPU cycles would be spent reading the
105 By default, swampd won't log information. To enable logging pass "-l" on the
110 To enable tuning, pass "-t" on the command line.
118 - `dbus` - Any read or write interface that uses dbus primarily.
119 - `experiments` - Small execution paths that allow for fan examination including
121 - `ipmi` - Manual control for any zone is handled by receiving an IPMI message.
124 - `notimpl` - These are read-only and write-only interface implementations that
125   can be dropped into a pluggable sensor to make it complete.
126 - `pid` - This contains all the PID associated code, including the zone
128 - `scripts` - This contains the scripts that convert YAML into C++.
129 - `sensors` - This contains a couple of sensor types including the pluggable
130   sensor's definition. It also holds the sensor manager.
131 - `sysfs` - This contains code that reads from or writes to sysfs.
132 - `threads` - Most of swampd's threads run in this method where there's just a
137 ### Two Margin Sensors Into Three Fans (Non-Step PID)
145 fleeting0+---->+-------+    +-------+     Thermal PID sampled
146                |  min()+--->+  PID  |     slower rate.
147 fleeting1+---->+-------+    +---+---+
152                              +--+-----+
153   The Fan PID        fan0+--->        |  New PWM  +-->fan0
155   faster rate        fan1+--->  PID   +---------->--->fan1
157   fans.              fan2+--->        |           +-->fan2
158                        ^     +--------+                +
160                        +-------------------------------+