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
47
48## Regulator Configuration
49
50Regulator configuration occurs early in the system boot before regulators have
51been enabled (turned on).
52
53A systemd service file runs the `regsctl` utility.  This utility invokes the
54D-Bus `configure` method on the `phosphor-regulators` application.
55
56This D-Bus method is implemented by the Manager object.  The Manager object
57calls the C++ `configure()` method on all the objects representing the system
58(System, Chassis, Device, and Rail).
59
60The configuration changes are applied to a Device or Rail by executing one or
61more actions, such as
62[pmbus_write_vout_command](config_file/pmbus_write_vout_command.md).
63
64If an error occurs while executing actions:
65* The error will be logged.
66* Any remaining actions for the current Device/Rail will be skipped.
67* Configuration changes will still be applied to all remaining Device/Rail
68  objects in the system.
69* The system boot will continue.
70
71
72## Regulator Monitoring
73
74### Enabling Monitoring
75
76Regulator monitoring is enabled during the system boot after regulators are
77enabled (turned on).
78
79A systemd service file runs the `regsctl` utility.  This utility invokes the
80D-Bus `monitor` method on the `phosphor-regulators` application.  The parameter
81value `true` is passed to the method.
82
83This D-Bus method is implemented by the Manager object.  The Manager object
84starts a timer.  The timer periodically calls C++ monitoring methods on all the
85objects representing the system (System, Chassis, Device, and Rail).
86
87### Disabling Monitoring
88
89Regulator monitoring is disabled at the beginning of system shutdown before
90regulators are disabled (turned off).
91
92A systemd service file runs the `regsctl` utility.  This utility invokes the
93D-Bus `monitor` method on the `phosphor-regulators` application.  The parameter
94value `false` is passed to the method.
95
96This D-Bus method is implemented by the Manager object.  The Manager object
97stops the timer that was periodically calling C++ monitor methods.
98
99### Sensor Monitoring
100
101When regulator monitoring is enabled, sensor values are read once per second.
102The timer in the Manager object calls the `monitorSensors()` method on all the
103objects representing the system (System, Chassis, Device, and Rail).
104
105The sensor values for a Rail (such as iout, vout, and temperature) are read
106using [pmbus_read_sensor](config_file/pmbus_read_sensor.md) actions.
107
108The first time a sensor value is read, a corresponding Sensor object is created
109on D-Bus.  The D-Bus object implements the Sensor.Value and OperationalStatus
110interfaces.  On subsequent reads, the existing D-Bus Sensor object is updated
111with the new sensor value.
112
113An existing D-Bus Sensor object is removed from D-Bus if no corresponding
114sensor values are read during monitoring.  This can occur in the following
115cases:
116* The regulator has been removed from the system (no longer present).
117* The regulator was replaced, and the new regulator supports a different set of
118  sensors values.  For example, temperature_peak is no longer provided.
119
120If an error occurs while reading the sensors for a Rail:
121* The error will be logged.  If the same error occurs repeatedly on a Rail, it
122  will only be logged once per system boot.
123* Any remaining actions for the Rail will be skipped.
124* The value of all D-Bus Sensor objects for this Rail will be set to 0.
125* The Functional property of all D-Bus Sensor objects for this Rail will be set
126  to false.
127* Sensor monitoring will continue.
128* The sensors for this Rail will be read again during the next monitoring
129  cycle.
130
131If, after an error occurs, a subsequent attempt to read the sensors for a Rail
132is successful:
133* The D-Bus Sensor objects for this Rail will be set to the new sensor values.
134* The Functional property of the D-Bus Sensor objects for this Rail will be set
135  to true.
136
137When regulator monitoring is disabled, the Manager object calls the
138`disableSensors()` method on all the objects representing the system (System,
139Chassis, Device, and Rail).  Each D-Bus Sensor object is set to the special
140value NaN to indicate the Sensor is inactive.
141