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