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 system receives standby power.
17
18The application is driven by a system-specific JSON configuration file.  The
19JSON file is found and parsed at runtime.  The parsing process creates a
20collection of C++ objects.  These objects implement the regulator configuration
21and monitoring behavior that was specified in the JSON file.
22
23
24## Key Classes
25
26* Manager
27  * Top level class created in `main()`.
28  * Loads the JSON configuration file.
29  * Implements the D-Bus `configure` and `monitor` methods.
30  * Contains a System object.
31* System
32  * Represents the computer system being controlled and monitored by the BMC.
33  * Contains one or more Chassis objects.
34* Chassis
35  * Represents an enclosure that can be independently powered off and on by the
36    BMC.
37  * Small and mid-sized systems may contain a single Chassis.
38  * In a large rack-mounted system, each drawer may correspond to a Chassis.
39  * Contains one or more Device objects.
40* Device
41  * Represents a hardware device, such as a voltage regulator or I/O expander.
42  * Contains zero or more Rail objects.
43* Rail
44  * Represents a voltage rail produced by a voltage regulator, such as 1.1V.
45
46
47## Regulator Configuration
48
49Regulator configuration occurs early in the system boot before regulators have
50been enabled (turned on).
51
52A systemd service file runs the `regsctl` utility.  This utility invokes the
53D-Bus `configure` method on the `phosphor-regulators` application.
54
55This D-Bus method is implemented by the Manager object.  The Manager object
56calls the C++ `configure()` method on all the objects representing the system
57(System, Chassis, Device, and Rail).
58
59The configuration changes are applied to a Device or Rail by executing one or
60more actions, such as
61[pmbus_write_vout_command](config_file/pmbus_write_vout_command.md).
62
63If an error occurs while executing actions:
64* The error will be logged.
65* Any remaining actions for the current Device/Rail will be skipped.
66* Configuration changes will still be applied to all remaining Device/Rail
67  objects in the system.
68* The system boot will continue.
69
70
71## Regulator Monitoring
72
73### Enabling Monitoring
74
75Regulator monitoring is enabled during the system boot after regulators are
76enabled (turned on).
77
78A systemd service file runs the `regsctl` utility.  This utility invokes the
79D-Bus `monitor` method on the `phosphor-regulators` application.  The parameter
80value `true` is passed to the method.
81
82This D-Bus method is implemented by the Manager object.  The Manager object
83starts a timer.  The timer periodically calls C++ monitoring methods on all the
84objects representing the system (System, Chassis, Device, and Rail).
85
86### Disabling Monitoring
87
88Regulator monitoring is disabled at the beginning of system shutdown before
89regulators are disabled (turned off).
90
91A systemd service file runs the `regsctl` utility.  This utility invokes the
92D-Bus `monitor` method on the `phosphor-regulators` application.  The parameter
93value `false` is passed to the method.
94
95This D-Bus method is implemented by the Manager object.  The Manager object
96stops the timer that was periodically calling C++ monitor methods.
97
98### Sensor Monitoring
99
100When regulator monitoring is enabled, sensor values are read once per second.
101The timer in the Manager object calls the `monitorSensors()` method on all the
102objects representing the system (System, Chassis, Device, and Rail).
103
104The sensor values for a Rail (such as iout, vout, and temperature) are read
105using [pmbus_read_sensor](config_file/pmbus_read_sensor.md) actions.
106
107The first time a sensor value is read, a corresponding Sensor object is created
108on D-Bus.  The D-Bus object implements the Sensor.Value and OperationalStatus
109interfaces.  On subsequent reads, the existing D-Bus Sensor object is updated
110with the new sensor value.
111
112An existing D-Bus Sensor object is removed from D-Bus if no corresponding
113sensor values are read during monitoring.  This can occur in the following
114cases:
115* The regulator has been removed from the system (no longer present).
116* The regulator was replaced, and the new regulator supports a different set of
117  sensors values.  For example, temperature_peak is no longer provided.
118
119If an error occurs while reading the sensors for a Rail:
120* The error will be logged.  If the same error occurs repeatedly on a Rail, it
121  will only be logged once per system boot.
122* Any remaining actions for the Rail will be skipped.
123* The value of all D-Bus Sensor objects for this Rail will be set to 0.
124* The Functional property of all D-Bus Sensor objects for this Rail will be set
125  to false.
126* Sensor monitoring will continue.
127* The sensors for this Rail will be read again during the next monitoring
128  cycle.
129
130If, after an error occurs, a subsequent attempt to read the sensors for a Rail
131is successful:
132* The D-Bus Sensor objects for this Rail will be set to the new sensor values.
133* The Functional property of the D-Bus Sensor objects for this Rail will be set
134  to true.
135
136When regulator monitoring is disabled, the Manager object calls the
137`disableSensors()` method on all the objects representing the system (System,
138Chassis, Device, and Rail).  Each D-Bus Sensor object is set to the special
139value NaN to indicate the Sensor is inactive.
140