phosphor-regulators/docs/design.md

3 This document describes the high-level design of the `phosphor-regulators`
6 The low-level design is documented using doxygen comments in the source files.
13 The `phosphor-regulators` application is a single-threaded C++ executable. It is
15 when the BMC reaches the Ready state and before the chassis is powered on.
17 The application is driven by a system-specific JSON configuration file. The JSON
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
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
46   - The BMCServices child class provides the real implementation.
47   - The MockServices child class provides a mock implementation that can be used
56 D-Bus `configure` method on the `phosphor-regulators` application.
58 This D-Bus method is implemented by the Manager object. The Manager object calls
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
72 - The system boot will continue.
82 D-Bus `monitor` method on the `phosphor-regulators` application. The parameter
85 This D-Bus method is implemented by the Manager object. The Manager object
95 D-Bus `monitor` method on the `phosphor-regulators` application. The parameter
98 This D-Bus method is implemented by the Manager object. The Manager object stops
111 on D-Bus. On subsequent reads, the existing D-Bus sensor object is updated with
114 The D-Bus sensor object implements the following interfaces:
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
121 An existing D-Bus Sensor object is removed from D-Bus if no corresponding sensor
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
130 - The error will be logged. If the same error occurs repeatedly on a Rail, it
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.
140 following changes will be made to the D-Bus sensor objects:
142 - The Value property will be set to the new sensor reading.
143 - The Functional property will be set to true.
146 of the D-Bus sensor objects:
148 - The Value property will be set to NaN.
149 - The Available property will be set to false.
158 an error is logged. This provides "de-glitching" to ignore transient hardware
165 - The error will be logged. If the same error occurs repeatedly on regulator, it
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