1# phosphor-pid-control 2 3This is a daemon running within the OpenBMC environment. It uses a well-defined 4configuration file to control the temperature of the tray components to keep 5them within operating conditions. It may require coordination with host-side 6tooling and OpenBMC. 7 8## Overview 9 10The BMC will run a daemon that controls the fans by pre-defined zones. The 11application will use thermal control, such that each defined zone is kept within 12a range and adjusted based on thermal information provided from locally readable 13sensors as well as host-provided information over an IPMI OEM command. 14 15A system (or tray) will be broken out into one or more zones, specified via 16configuration files or dbus. Each zone will contain at least one fan and at 17least one temperature sensor and some device margins. The sensor data can be 18provided via sysfs, dbus, or through IPMI. In either case, default margins 19should be provided in case of failure or other unknown situation. 20 21The system will run a control loop for each zone with the attempt to maintain 22the temperature within that zone within the margin for the devices specified. 23 24## Configuring 25 26[How to configure phosphor-pid-control](configure.md) 27 28## Detailed Design 29 30The software will run as a multi-threaded daemon that runs a control loop for 31each zone, and has a master thread which listens for dbus messages. Each zone 32will require at least one fan that it exclusively controls, however, zones can 33share temperature sensors. 34 35 36 37In this figure the communications channels between swampd and ipmid and 38phosphor-hwmon are laid out. 39 40### Zone Specification 41 42A configuration file will need to exist for each board. 43 44Each zone must have at least one fan that it exclusively controls. Each zone 45must have at least one temperature sensor, but they may be shared. 46 47The internal thermometers specified can be read via sysfs or dbus. 48 49### Chassis Delta 50 51Due to data center requirements, the delta between the outgoing air temperature 52and the environmental air temperature must be no greater than 15C. 53 54### IPMI Access to Phosphor-pid-control 55 56[OEM-IPMI Definitions](ipmi.md) 57 58#### Set Sensor Value 59 60Tools needs to update the thermal controller with information not necessarily 61available to the BMC. This will comprise of a list of temperature (or margin?) 62sensors that are updated by the set sensor command. Because they don't represent 63real sensors in the system, the set sensor handler can simply broadcast the 64update as a properties update on dbus when it receives the command over IPMI. 65 66#### Set Fan PWM 67 68A tool can override a specific fan's PWM when we implement the set sensor IPMI 69command pathway. 70 71#### Get Fan Tach 72 73A tool can read fan_tach through the normal IPMI interface presently exported 74for sensors. 75 76### Sensor Update Loop 77 78The plan is to listen for fan_tach updates for each fan in a background thread. 79This will receive an update from phosphor-hwmon each time it updates any sensor 80it cares about. 81 82By default phosphor-hwmon reads each sensor in turn and then sleeps for 1 83second. We'll be updating phosphor-hwmon to sleep for a shorter period -- how 84short though is still TBD. We'll also be updating phosphor-hwmon to support pwm 85as a target. 86 87### Thermal Control Loops 88 89Each zone will require a control loop that monitors the associated thermals and 90controls the fan(s). The EC PID loop is designed to hit the fans 10 times per 91second to drive them to the desired value and read the sensors once per second. 92We'll be receiving sensor updates with such regularly, however, at present it 93takes ~0.13s to read all 8 fans. Which can't be read constantly without bringing 94the system to its knees -- in that all CPU cycles would be spent reading the 95fans. TBD on how frequently we'll be reading the fan sensors and the impact this 96will have. 97 98### Main Thread 99 100The main thread will manage the other threads, and process the initial 101configuration files. It will also register a dbus handler for the OEM message. 102 103### Enabling Logging & Tuning 104 105By default, swampd won't log information. To enable logging pass "-l" on the 106command line with a parameter that is the folder into which to write the logs. 107 108The log files will be named `{folderpath}/zone_{zoneid}.log`. 109 110To enable tuning, pass "-t" on the command line. 111 112See [Logging & Tuning](tuning.md) for more information. 113 114## Code Layout 115 116The code is broken out into modules as follows: 117 118- `dbus` - Any read or write interface that uses dbus primarily. 119- `experiments` - Small execution paths that allow for fan examination including 120 how quickly fans respond to changes. 121- `ipmi` - Manual control for any zone is handled by receiving an IPMI message. 122 This holds the ipmid provider for receiving those messages and sending them 123 onto swampd. 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 127 definition, controller definition, and the PID computational code. 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 133 dbus bus that we manage. 134 135## Example System Configurations 136 137### Two Margin Sensors Into Three Fans (Non-Step PID) 138 139``` 140A single zone system where multiple margin thermal sensors are fed into one PID 141that generates the output RPM for a set of fans controlled by one PID. 142 143margin sensors as input to thermal pid 144 145fleeting0+---->+-------+ +-------+ Thermal PID sampled 146 | min()+--->+ PID | slower rate. 147fleeting1+---->+-------+ +---+---+ 148 | 149 | 150 | RPM setpoint 151 Current RPM v 152 +--+-----+ 153 The Fan PID fan0+---> | New PWM +-->fan0 154 samples at a | | | 155 faster rate fan1+---> PID +---------->--->fan1 156 speeding up the | | | 157 fans. fan2+---> | +-->fan2 158 ^ +--------+ + 159 | | 160 +-------------------------------+ 161 RPM updated by PWM. 162``` 163
