{"id":18368636,"url":"https://github.com/openbmc/phosphor-pid-control","last_synced_at":"2025-04-06T17:31:47.418Z","repository":{"id":49254085,"uuid":"123181379","full_name":"openbmc/phosphor-pid-control","owner":"openbmc","description":"OpenBMC PID-based Thermal Control Daemon","archived":false,"fork":false,"pushed_at":"2025-04-02T21:34:56.000Z","size":3086,"stargazers_count":18,"open_issues_count":26,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-02T22:23:15.002Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openbmc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-27T20:03:04.000Z","updated_at":"2025-04-02T21:21:52.000Z","dependencies_parsed_at":"2024-04-30T10:53:34.766Z","dependency_job_id":"1b3a95e2-9d8a-4e1f-8be1-81c581d3321e","html_url":"https://github.com/openbmc/phosphor-pid-control","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-pid-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-pid-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-pid-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-pid-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openbmc","download_url":"https://codeload.github.com/openbmc/phosphor-pid-control/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522389,"owners_count":20952540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T23:26:47.788Z","updated_at":"2025-04-06T17:31:46.300Z","avatar_url":"https://github.com/openbmc.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phosphor-pid-control\n\nThis is a daemon running within the OpenBMC environment. It uses a well-defined\nconfiguration file to control the temperature of the tray components to keep\nthem within operating conditions. It may require coordination with host-side\ntooling and OpenBMC.\n\n## Overview\n\nThe BMC will run a daemon that controls the fans by pre-defined zones. The\napplication will use thermal control, such that each defined zone is kept within\na range and adjusted based on thermal information provided from locally readable\nsensors as well as host-provided information over an IPMI OEM command.\n\nA system (or tray) will be broken out into one or more zones, specified via\nconfiguration files or dbus. Each zone will contain at least one fan and at\nleast one temperature sensor and some device margins. The sensor data can be\nprovided via sysfs, dbus, or through IPMI. In either case, default margins\nshould be provided in case of failure or other unknown situation.\n\nThe system will run a control loop for each zone with the attempt to maintain\nthe temperature within that zone within the margin for the devices specified.\n\n## Configuring\n\n[How to configure phosphor-pid-control](configure.md)\n\n## Detailed Design\n\nThe software will run as a multi-threaded daemon that runs a control loop for\neach zone, and has a master thread which listens for dbus messages. Each zone\nwill require at least one fan that it exclusively controls, however, zones can\nshare temperature sensors.\n\n![Swampd Architecture](swampd_diagram.png \"Swampd Architecture\")\n\nIn this figure the communications channels between swampd and ipmid and\nphosphor-hwmon are laid out.\n\n### Zone Specification\n\nA configuration file will need to exist for each board.\n\nEach zone must have at least one fan that it exclusively controls. Each zone\nmust have at least one temperature sensor, but they may be shared.\n\nThe internal thermometers specified can be read via sysfs or dbus.\n\n### Chassis Delta\n\nDue to data center requirements, the delta between the outgoing air temperature\nand the environmental air temperature must be no greater than 15C.\n\n### IPMI Access to Phosphor-pid-control\n\n[OEM-IPMI Definitions](ipmi.md)\n\n#### Set Sensor Value\n\nTools needs to update the thermal controller with information not necessarily\navailable to the BMC. This will comprise of a list of temperature (or margin?)\nsensors that are updated by the set sensor command. Because they don't represent\nreal sensors in the system, the set sensor handler can simply broadcast the\nupdate as a properties update on dbus when it receives the command over IPMI.\n\n#### Set Fan PWM\n\nA tool can override a specific fan's PWM when we implement the set sensor IPMI\ncommand pathway.\n\n#### Get Fan Tach\n\nA tool can read fan_tach through the normal IPMI interface presently exported\nfor sensors.\n\n### Sensor Update Loop\n\nThe plan is to listen for fan_tach updates for each fan in a background thread.\nThis will receive an update from phosphor-hwmon each time it updates any sensor\nit cares about.\n\nBy default phosphor-hwmon reads each sensor in turn and then sleeps for 1\nsecond. We'll be updating phosphor-hwmon to sleep for a shorter period -- how\nshort though is still TBD. We'll also be updating phosphor-hwmon to support pwm\nas a target.\n\n### Thermal Control Loops\n\nEach zone will require a control loop that monitors the associated thermals and\ncontrols the fan(s). The EC PID loop is designed to hit the fans 10 times per\nsecond to drive them to the desired value and read the sensors once per second.\nWe'll be receiving sensor updates with such regularly, however, at present it\ntakes ~0.13s to read all 8 fans. Which can't be read constantly without bringing\nthe system to its knees -- in that all CPU cycles would be spent reading the\nfans. TBD on how frequently we'll be reading the fan sensors and the impact this\nwill have.\n\n### Main Thread\n\nThe main thread will manage the other threads, and process the initial\nconfiguration files. It will also register a dbus handler for the OEM message.\n\n### Enabling Logging \u0026 Tuning\n\nBy default, swampd won't log information. To enable logging pass \"-l\" on the\ncommand line with a parameter that is the folder into which to write the logs.\n\nThe log files will be named `{folderpath}/zone_{zoneid}.log`.\n\nTo enable tuning, pass \"-t\" on the command line.\n\nSee [Logging \u0026 Tuning](tuning.md) for more information.\n\n## Code Layout\n\nThe code is broken out into modules as follows:\n\n- `dbus` - Any read or write interface that uses dbus primarily.\n- `experiments` - Small execution paths that allow for fan examination including\n  how quickly fans respond to changes.\n- `ipmi` - Manual control for any zone is handled by receiving an IPMI message.\n  This holds the ipmid provider for receiving those messages and sending them\n  onto swampd.\n- `notimpl` - These are read-only and write-only interface implementations that\n  can be dropped into a pluggable sensor to make it complete.\n- `pid` - This contains all the PID associated code, including the zone\n  definition, controller definition, and the PID computational code.\n- `scripts` - This contains the scripts that convert YAML into C++.\n- `sensors` - This contains a couple of sensor types including the pluggable\n  sensor's definition. It also holds the sensor manager.\n- `sysfs` - This contains code that reads from or writes to sysfs.\n- `threads` - Most of swampd's threads run in this method where there's just a\n  dbus bus that we manage.\n\n## Example System Configurations\n\n### Two Margin Sensors Into Three Fans (Non-Step PID)\n\nA single zone system where multiple margin thermal sensors are fed into one PID\nthat generates the output RPM for a set of fans controlled by one PID.\n\nmargin sensors as input to thermal pid\n\n```text\nfleeting0+----\u003e+-------+    +-------+     Thermal PID sampled\n               |  min()+---\u003e+  PID  |     slower rate.\nfleeting1+----\u003e+-------+    +---+---+\n                                |\n                                |\n                                | RPM setpoint\n                    Current RPM v\n                             +--+-----+\n  The Fan PID        fan0+---\u003e        |  New PWM  +--\u003efan0\n  samples at a               |        |           |\n  faster rate        fan1+---\u003e  PID   +----------\u003e---\u003efan1\n  speeding up the            |        |           |\n  fans.              fan2+---\u003e        |           +--\u003efan2\n                       ^     +--------+                +\n                       |                               |\n                       +-------------------------------+\n                              RPM updated by PWM.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-pid-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenbmc%2Fphosphor-pid-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-pid-control/lists"}