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