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