1# phosphor-regulators Configuration File
2
3## Overview
4
5The `phosphor-regulators` application is controlled by a configuration file
6(config file).  The config file defines how to perform the following operations
7on voltage regulators in the system:
8* Modify regulator configuration, such as output voltage or overcurrent
9  settings
10* Read sensor values
11
12The config file does not control how voltage regulators are enabled or how to
13monitor their Power Good (pgood) status.  Those operations are typically
14performed by power sequencer hardware and related firmware.
15
16
17## Data Format
18
19The config file is written using the [JSON (JavaScript Object
20Notation)](https://www.json.org/) data format.
21
22The config file can be created using any text editor, such as Atom, Notepad++,
23gedit, Vim, or Emacs.  You can select any file name, but it must end with the
24".json" suffix, such as `regulators.json`.
25
26
27## Example
28
29See [config_file.json](../../examples/config_file.json).
30
31
32## Contents
33
34### Structure
35
36The config file typically contains the following structure:
37* Array of [rules](rule.md)
38  * Rules defining how to modify configuration of regulators
39  * Rules defining how to read sensors
40* Array of [chassis](chassis.md) in the system
41  * Array of regulator [devices](device.md) in the chassis
42    * Array of voltage [rails](rail.md) produced by the regulator
43
44Rules provide common, reusable sequences of actions that can be shared by one
45or more regulators.  They are optional and can be omitted if each regulator
46requires a unique sequence of actions.
47
48### Syntax
49
50The config file contains a single JSON [config_file](config_file.md) object at
51the root level.  That object contains arrays of other JSON objects.
52
53The following JSON object types are supported:
54* [action](action.md)
55* [and](and.md)
56* [chassis](chassis.md)
57* [compare_presence](compare_presence.md)
58* [compare_vpd](compare_vpd.md)
59* [config_file](config_file.md)
60* [configuration](configuration.md)
61* [device](device.md)
62* [i2c_compare_bit](i2c_compare_bit.md)
63* [i2c_compare_byte](i2c_compare_byte.md)
64* [i2c_compare_bytes](i2c_compare_bytes.md)
65* [i2c_interface](i2c_interface.md)
66* [i2c_write_bit](i2c_write_bit.md)
67* [i2c_write_byte](i2c_write_byte.md)
68* [i2c_write_bytes](i2c_write_bytes.md)
69* [if](if.md)
70* [not](not.md)
71* [or](or.md)
72* [pmbus_read_sensor](pmbus_read_sensor.md)
73* [pmbus_write_vout_command](pmbus_write_vout_command.md)
74* [presence_detection](presence_detection.md)
75* [rail](rail.md)
76* [rule](rule.md)
77* [run_rule](run_rule.md)
78* [sensor_monitoring](sensor_monitoring.md)
79* [set_device](set_device.md)
80
81### Comments
82
83The JSON data format does not support comments.  However, many of the JSON
84objects in the config file provide an optional "comments" property.  The value
85of this property is an array of strings.  Use this property to annotate the
86config file.  The "comments" properties are ignored when the config file is
87read by the `phosphor-regulators` application.
88
89Examples:
90
91```
92"comments": [ "IR35221 regulator producing the Vdd rail" ]
93
94"comments": [ "Check if register 0x82 contains 0x7302",
95              "Device returns bytes in little-endian order",
96              "Ignore most significant bit in each byte" ]
97```
98
99### Hexadecimal Values
100
101The JSON number data type does not support the hexadecimal format.  For this
102reason, properties with hexadecimal values use the string data type.
103
104Example:
105```
106"address": "0x70"
107```
108
109
110## Validation
111
112After creating or modifying a config file, you need to validate it using the
113tool [validate-regulators-config.py](../../tools/validate-regulators-config.py).
114
115The validation tool checks the config file for errors, such as:
116* Invalid JSON syntax (like a missing brace)
117* Unrecognized JSON object or property
118* Duplicate rule or device ID
119* Reference to a rule or device ID that does not exist
120* Infinite loop, such as rule A runs rule B which runs rule A
121
122The tool requires two input files:
123* config file to validate
124* [config_schema.json](../../schema/config_schema.json)
125
126The tool has the following command line syntax:
127```
128validate-regulators-config.py -c <config file> -s config_schema.json
129```
130where `<config file>` is the name of the config file to validate.
131
132
133## Installation
134
135### Standard Directory
136
137`/usr/share/phosphor-regulators`
138
139The standard version of the config file should be installed in this read-only
140directory as part of the firmware image install.  This is the config file that
141will normally be used.
142
143### Test Directory
144
145`/etc/phosphor-regulators`
146
147A new version of the config file can be tested by copying it into this writable
148directory.  This avoids the need to build and install a new firmware image on
149the BMC.
150
151### Search Order
152
153The `phosphor-regulators` application will search first in the test directory
154for a config file.  If no config file is found or the file contains errors, the
155application will next search in the standard directory.
156
157
158## Loading and Reloading
159
160The config file is loaded when the `phosphor-regulators` application starts.
161
162To force the application to reload the config file, use the following command
163on the BMC:
164
165``kill -SIGHUP `pidof phosphor-regulators` ``
166
167
168## Testing
169
170After creating or modifying a config file, you should test it to ensure it
171provides the desired behavior.
172
173Perform the following steps to test the config file:
174* Run the [validation tool](#validation) to ensure the config file contains no
175  errors.
176* Copy the config file into the [test directory](#test-directory) on the BMC.
177* Force the `phosphor-regulators` application to
178  [reload](#loading-and-reloading) its config file, causing it to find and load
179  the file in the test directory.
180* Boot the system.  Regulator configuration changes (such as voltage settings)
181  are only applied during the boot.
182
183When finished testing, perform the following steps to revert to the standard
184config file:
185* Remove the config file from the test directory.
186* Force the `phosphor-regulators` application to reload its config file,
187  causing it to find and load the file in the standard directory.
188* Boot the system, if necessary, to apply the regulator configuration changes
189  in the standard config file.
190