1# phosphor-regulators Configuration File
2
3## Table of Contents
4
5- [Overview](#overview)
6- [Data Format](#data-format)
7- [Example](#example)
8- [Name](#name)
9- [Contents](#contents)
10- [Validation](#validation)
11- [Installation](#installation)
12- [Loading and Reloading](#loading-and-reloading)
13- [Testing](#testing)
14
15## Overview
16
17The `phosphor-regulators` application is controlled by a configuration file
18(config file). The config file defines how to perform the following operations
19on voltage regulators in the system:
20
21- Modify regulator configuration, such as output voltage or overcurrent settings
22- Read sensor values
23- Detect redundant phase faults (if necessary)
24
25The config file does not control how voltage regulators are enabled or how to
26monitor their Power Good (pgood) status. Those operations are typically
27performed by power sequencer hardware and related firmware.
28
29## Data Format
30
31The config file is written using the
32[JSON (JavaScript Object Notation)](https://www.json.org/) data format.
33
34The config file can be created using any text editor, such as Visual Studio
35Code, Atom, Notepad++, Vim, or Emacs.
36
37## Example
38
39See [config.json](../../examples/config.json).
40
41## Name
42
43There are two options for naming the config file:
44
45- [Default Name](#default-name)
46- [Name Based on System Type](#name-based-on-system-type)
47
48### Default Name
49
50The default config file name is `config.json`. The default name can be used if
51the BMC firmware image only supports one system type. It can also be used if the
52firmware image supports multiple system types that share a common config file.
53
54### Name Based on System Type
55
56The config file name can be based on the system type that it supports. This is
57required if the BMC firmware image supports multiple system types, and those
58system types do not share a common config file.
59
60A config file is normally system-specific. Each system type usually has a
61different set of voltage regulators and rails.
62
63The system type is obtained from a D-Bus Chassis object created by the
64[Entity Manager](https://github.com/openbmc/entity-manager) application. The
65object must implement the `xyz.openbmc_project.Inventory.Decorator.Compatible`
66interface.
67
68The `Names` property of this interface contains a list of one or more compatible
69system types. The types are ordered from most specific to least specific.
70
71Example:
72
73- `com.acme.Hardware.Chassis.Model.MegaServer4CPU`
74- `com.acme.Hardware.Chassis.Model.MegaServer`
75- `com.acme.Hardware.Chassis.Model.Server`
76
77The `phosphor-regulators` application searches for a config file name that
78matches one of these compatible system types. It searches from most specific to
79least specific. The first config file found, if any, will be used.
80
81For each compatible system type, the application will look for two config file
82names:
83
84- The complete compatible system type plus a '.json' suffix
85- The last node of the compatible system type plus a '.json' suffix
86
87Example:
88
89- `com.acme.Hardware.Chassis.Model.MegaServer4CPU.json`
90- `MegaServer4CPU.json`
91
92If a config file is not found based on system type, `phosphor-regulators`
93searches for a file with the [default name](#default-name).
94
95## Contents
96
97### Structure
98
99The config file typically contains the following structure:
100
101- Array of [rules](rule.md)
102  - Rules defining how to modify configuration of regulators
103  - Rules defining how to read sensors
104  - Rules defining how to detect redundant phase faults (if necessary)
105- Array of [chassis](chassis.md) in the system
106  - Array of regulator [devices](device.md) in the chassis
107    - Array of voltage [rails](rail.md) produced by the regulator
108
109Rules provide common, reusable sequences of actions that can be shared by one or
110more regulators. They are optional and can be omitted if each regulator requires
111a unique sequence of actions.
112
113### Syntax
114
115The config file contains a single JSON [config_file](config_file.md) object at
116the root level. That object contains arrays of other JSON objects.
117
118The following JSON object types are supported:
119
120- [action](action.md)
121- [and](and.md)
122- [chassis](chassis.md)
123- [compare_presence](compare_presence.md)
124- [compare_vpd](compare_vpd.md)
125- [config_file](config_file.md)
126- [configuration](configuration.md)
127- [device](device.md)
128- [i2c_capture_bytes](i2c_capture_bytes.md)
129- [i2c_compare_bit](i2c_compare_bit.md)
130- [i2c_compare_byte](i2c_compare_byte.md)
131- [i2c_compare_bytes](i2c_compare_bytes.md)
132- [i2c_interface](i2c_interface.md)
133- [i2c_write_bit](i2c_write_bit.md)
134- [i2c_write_byte](i2c_write_byte.md)
135- [i2c_write_bytes](i2c_write_bytes.md)
136- [if](if.md)
137- [log_phase_fault](log_phase_fault.md)
138- [not](not.md)
139- [or](or.md)
140- [phase_fault_detection](phase_fault_detection.md)
141- [pmbus_read_sensor](pmbus_read_sensor.md)
142- [pmbus_write_vout_command](pmbus_write_vout_command.md)
143- [presence_detection](presence_detection.md)
144- [rail](rail.md)
145- [rule](rule.md)
146- [run_rule](run_rule.md)
147- [sensor_monitoring](sensor_monitoring.md)
148- [set_device](set_device.md)
149
150### Comments
151
152The JSON data format does not support comments. However, many of the JSON
153objects in the config file provide an optional "comments" property. The value of
154this property is an array of strings. Use this property to annotate the config
155file. The "comments" properties are ignored when the config file is read by the
156`phosphor-regulators` application.
157
158Examples:
159
160```json
161"comments": [ "IR35221 regulator producing the Vdd rail" ]
162```
163
164```json
165"comments": [ "Check if register 0x82 contains 0x7302",
166              "Device returns bytes in little-endian order",
167              "Ignore most significant bit in each byte" ]
168```
169
170### Hexadecimal Values
171
172The JSON number data type does not support the hexadecimal format. For this
173reason, properties with hexadecimal values use the string data type.
174
175Example:
176
177```json
178"address": "0x70"
179```
180
181## Validation
182
183After creating or modifying a config file, you need to validate it using the
184tool [validate-regulators-config.py](../../tools/validate-regulators-config.py).
185
186The validation tool checks the config file for errors, such as:
187
188- Invalid JSON syntax (like a missing brace)
189- Unrecognized JSON object or property
190- Duplicate rule or device ID
191- Reference to a rule or device ID that does not exist
192- Infinite loop, such as rule A runs rule B which runs rule A
193
194The tool requires two input files:
195
196- config file to validate
197- [config_schema.json](../../schema/config_schema.json)
198
199The tool has the following command line syntax:
200
201```sh
202validate-regulators-config.py -c <config file> -s config_schema.json
203```
204
205where `<config file>` is the name of the config file to validate.
206
207## Installation
208
209### Standard Directory
210
211`/usr/share/phosphor-regulators`
212
213The standard version of the config file is installed in this read-only directory
214as part of the firmware image install. This is the config file that will
215normally be used.
216
217### Test Directory
218
219`/etc/phosphor-regulators`
220
221A new version of the config file can be tested by copying it into this writable
222directory. This avoids the need to build and install a new firmware image on the
223BMC.
224
225The test directory might not exist on the BMC. If it is missing, create it using
226the following command:
227
228`mkdir /etc/phosphor-regulators`
229
230### Search Order
231
232The `phosphor-regulators` application will search the installation directories
233in the following order to find a config file:
234
2351. test directory
2362. standard directory
237
238### Firmware Updates
239
240When a new firmware image is installed on the BMC, it will update the config
241file in the standard directory.
242
243The test directory will **not** be modified by a firmware update. If a config
244file exists in the test directory, it will continue to override the config file
245in the standard directory.
246
247## Loading and Reloading
248
249The config file is loaded when the `phosphor-regulators` application starts.
250
251To force the application to reload the config file, use the following command on
252the BMC:
253
254`systemctl kill -s HUP phosphor-regulators.service`
255
256To confirm which config file was loaded, use the following command on the BMC:
257
258`journalctl -u phosphor-regulators.service | grep Loading`
259
260## Testing
261
262After creating or modifying a config file, you should test it to ensure it
263provides the desired behavior.
264
265Perform the following steps to test the config file:
266
267- Run the [validation tool](#validation) to ensure the config file contains no
268  errors.
269- Copy the config file into the [test directory](#test-directory) on the BMC.
270- Force the `phosphor-regulators` application to
271  [reload](#loading-and-reloading) its config file, causing it to find and load
272  the file in the test directory.
273- Boot the system. Regulator configuration changes (such as voltage settings)
274  are only applied during the boot.
275- View output from the `phosphor-regulators` application to make sure no errors
276  occurred. Use the command `journalctl -u phosphor-regulators.service`.
277
278When finished testing, perform the following steps to revert to the standard
279config file:
280
281- Remove the config file from the test directory. If this is not done, the test
282  config file will continue to override the standard config file even after a
283  firmware update.
284- Force the `phosphor-regulators` application to reload its config file, causing
285  it to find and load the file in the standard directory.
286- Boot the system, if necessary, to apply the regulator configuration changes in
287  the standard config file.
288