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
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
52 Regulator configuration occurs early in the system boot before regulators have
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
59 the C++ `configure()` method on all the objects representing the system (System,
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.
78 Regulator monitoring is enabled during the system boot after regulators are
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
87 objects representing the system (System, Chassis, Device, and Rail).
91 Regulator monitoring is disabled at the beginning of system shutdown before
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
105 objects representing the system (System, Chassis, Device, and Rail).
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
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.
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.
155 method on all the objects representing the system (System, Chassis, Device).
158 an error is logged. This provides "de-glitching" to ignore transient hardware
161 A phase fault error will only be logged for a regulator once per system boot.
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