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
11 application will use thermal control, such that each defined zone is kept within
12 a range and adjusted based on thermal information provided from locally readable
13 sensors as well as host-provided information over an IPMI OEM command.
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
33 share temperature sensors.
38 phosphor-hwmon are laid out.
54 ### IPMI Access to Phosphor-pid-control
56 [OEM-IPMI Definitions](ipmi.md)
60 Tools needs to update the thermal controller with information not necessarily
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
74 for sensors.
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
87 ### Thermal Control Loops
91 second to drive them to the desired value and read the sensors once per second.
94 the system to its knees -- in that all CPU cycles would be spent reading the
95 fans. TBD on how frequently we'll be reading the fan sensors and the impact this
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
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
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)
139 A single zone system where multiple margin thermal sensors are fed into one PID
142 margin sensors as input to thermal 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                        +-------------------------------+