1# Design 2 3This document describes the high-level design of the `phosphor-regulators` 4application. 5 6The low-level design is documented using doxygen comments in the source files. 7 8See [README.md](../README.md) for an overview of the functionality provided by 9this application. 10 11 12## Overview 13 14The `phosphor-regulators` application is a single-threaded C++ executable. It 15is a 'daemon' process that runs continually. The application is launched by 16systemd when the BMC reaches the Ready state and before the chassis is powered 17on. 18 19The application is driven by a system-specific JSON configuration file. The 20JSON file is found and parsed at runtime. The parsing process creates a 21collection of C++ objects. These objects implement the regulator configuration 22and monitoring behavior that was specified in the JSON file. 23 24 25## Key Classes 26 27* Manager 28 * Top level class created in `main()`. 29 * Loads the JSON configuration file. 30 * Implements the D-Bus `configure` and `monitor` methods. 31 * Contains a System object. 32* System 33 * Represents the computer system being controlled and monitored by the BMC. 34 * Contains one or more Chassis objects. 35* Chassis 36 * Represents an enclosure that can be independently powered off and on by the 37 BMC. 38 * Small and mid-sized systems may contain a single Chassis. 39 * In a large rack-mounted system, each drawer may correspond to a Chassis. 40 * Contains one or more Device objects. 41* Device 42 * Represents a hardware device, such as a voltage regulator or I/O expander. 43 * Contains zero or more Rail objects. 44* Rail 45 * Represents a voltage rail produced by a voltage regulator, such as 1.1V. 46* Services 47 * Abstract base class that provides access to a collection of system services 48 like error logging, journal, vpd, and hardware presence. 49 * The BMCServices child class provides the real implementation. 50 * The MockServices child class provides a mock implementation that can be 51 used in gtest test cases. 52 53 54## Regulator Configuration 55 56Regulator configuration occurs early in the system boot before regulators have 57been enabled (turned on). 58 59A systemd service file runs the `regsctl` utility. This utility invokes the 60D-Bus `configure` method on the `phosphor-regulators` application. 61 62This D-Bus method is implemented by the Manager object. The Manager object 63calls the C++ `configure()` method on all the objects representing the system 64(System, Chassis, Device, and Rail). 65 66The configuration changes are applied to a Device or Rail by executing one or 67more actions, such as 68[pmbus_write_vout_command](config_file/pmbus_write_vout_command.md). 69 70If an error occurs while executing actions: 71* The error will be logged. 72* Any remaining actions for the current Device/Rail will be skipped. 73* Configuration changes will still be applied to all remaining Device/Rail 74 objects in the system. 75* The system boot will continue. 76 77 78## Regulator Monitoring 79 80### Enabling Monitoring 81 82Regulator monitoring is enabled during the system boot after regulators are 83enabled (turned on). 84 85A systemd service file runs the `regsctl` utility. This utility invokes the 86D-Bus `monitor` method on the `phosphor-regulators` application. The parameter 87value `true` is passed to the method. 88 89This D-Bus method is implemented by the Manager object. The Manager object 90starts a timer. The timer periodically calls C++ monitoring methods on all the 91objects representing the system (System, Chassis, Device, and Rail). 92 93### Disabling Monitoring 94 95Regulator monitoring is disabled at the beginning of system shutdown before 96regulators are disabled (turned off). 97 98A systemd service file runs the `regsctl` utility. This utility invokes the 99D-Bus `monitor` method on the `phosphor-regulators` application. The parameter 100value `false` is passed to the method. 101 102This D-Bus method is implemented by the Manager object. The Manager object 103stops the timer that was periodically calling C++ monitor methods. 104 105### Sensor Monitoring 106 107When regulator monitoring is enabled, sensor values are read once per second. 108The timer in the Manager object calls the `monitorSensors()` method on all the 109objects representing the system (System, Chassis, Device, and Rail). 110 111The sensor values for a Rail (such as iout, vout, and temperature) are read 112using [pmbus_read_sensor](config_file/pmbus_read_sensor.md) actions. 113 114The first time a sensor value is read, a corresponding sensor object is created 115on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated 116with the new sensor value. 117 118The D-Bus sensor object implements the following interfaces: 119* xyz.openbmc_project.Sensor.Value 120* xyz.openbmc_project.State.Decorator.OperationalStatus 121* xyz.openbmc_project.State.Decorator.Availability 122* xyz.openbmc_project.Association.Definitions 123 124An existing D-Bus Sensor object is removed from D-Bus if no corresponding 125sensor values are read during monitoring. This can occur in the following 126cases: 127* The regulator has been removed from the system (no longer present). 128* The regulator was replaced, and the new regulator supports a different set of 129 sensors values. For example, temperature_peak is no longer provided. 130 131If an error occurs while reading the sensors for a Rail: 132* The error will be logged. If the same error occurs repeatedly on a Rail, it 133 will only be logged once per system boot. 134* Any remaining actions for the Rail will be skipped. 135* The following changes will be made to all D-Bus sensor objects for this Rail: 136 * The Value property will be set to NaN. 137 * The Functional property will be set to false. 138* Sensor monitoring will continue with the next Rail or Device. 139* The sensors for this Rail will be read again during the next monitoring 140 cycle. 141 142If a subsequent attempt to read the sensors for the Rail is successful, the 143following changes will be made to the D-Bus sensor objects: 144* The Value property will be set to the new sensor reading. 145* The Functional property will be set to true. 146 147When regulator monitoring is disabled, the following changes will be made to 148all of the D-Bus sensor objects: 149* The Value property will be set to NaN. 150* The Available property will be set to false. 151 152### Phase Fault Monitoring 153 154When regulator monitoring is enabled, phase fault detection is performed every 15515 seconds. The timer in the Manager object calls the `detectPhaseFaults()` 156method on all the objects representing the system (System, Chassis, Device). 157 158A phase fault must be detected two consecutive times (15 seconds apart) before 159an error is logged. This provides "de-glitching" to ignore transient hardware 160problems. 161 162A phase fault error will only be logged for a regulator once per system boot. 163 164If a different error occurs while detecting phase faults in a regulator: 165* The error will be logged. If the same error occurs repeatedly on regulator, 166 it will only be logged once per system boot. 167* Any remaining actions for the regulator will be skipped. 168* Phase fault detection will continue with the next regulator. 169* Phase fault detection will be attempted again for this regulator during the 170 next monitoring cycle. 171