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 Atom, Notepad++, 35gedit, 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, such as 57`ibm_rainier.json`. This is required if the BMC firmware image supports multiple 58system types, and those system types do not share a common config file. 59 60The system type is obtained from the `IBMCompatibleSystem` D-Bus interface that 61is provided by the [Entity Manager](https://github.com/openbmc/entity-manager) 62application. The `Names` property of this interface contains a list of one or 63more compatible system types, ordered from most specific to most general. 64 65Example: 66 67- `ibm,rainier-2u` 68- `ibm,rainier` 69 70The `phosphor-regulators` application converts each system type into a 71corresponding config file name: 72 73- Replaces spaces and commas with underscores 74- Adds a ".json" suffix 75 76Example: 77 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## Contents 85 86### Structure 87 88The config file typically contains the following structure: 89 90- Array of [rules](rule.md) 91 - Rules defining how to modify configuration of regulators 92 - Rules defining how to read sensors 93 - Rules defining how to detect redundant phase faults (if necessary) 94- Array of [chassis](chassis.md) in the system 95 - Array of regulator [devices](device.md) in the chassis 96 - Array of voltage [rails](rail.md) produced by the regulator 97 98Rules provide common, reusable sequences of actions that can be shared by one or 99more regulators. They are optional and can be omitted if each regulator requires 100a unique sequence of actions. 101 102### Syntax 103 104The config file contains a single JSON [config_file](config_file.md) object at 105the root level. That object contains arrays of other JSON objects. 106 107The following JSON object types are supported: 108 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 of 143this property is an array of strings. Use this property to annotate the config 144file. The "comments" properties are ignored when the config file is read by the 145`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``` 165"address": "0x70" 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 175- Invalid JSON syntax (like a missing brace) 176- Unrecognized JSON object or property 177- Duplicate rule or device ID 178- Reference to a rule or device ID that does not exist 179- Infinite loop, such as rule A runs rule B which runs rule A 180 181The tool requires two input files: 182 183- config file to validate 184- [config_schema.json](../../schema/config_schema.json) 185 186The tool has the following command line syntax: 187 188``` 189validate-regulators-config.py -c <config file> -s config_schema.json 190``` 191 192where `<config file>` is the name of the config file to validate. 193 194## Installation 195 196### Standard Directory 197 198`/usr/share/phosphor-regulators` 199 200The standard version of the config file is installed in this read-only directory 201as part of the firmware image install. This is the config file that will 202normally be used. 203 204### Test Directory 205 206`/etc/phosphor-regulators` 207 208A new version of the config file can be tested by copying it into this writable 209directory. This avoids the need to build and install a new firmware image on the 210BMC. 211 212The test directory might not exist on the BMC. If it is missing, create it using 213the following command: 214 215`mkdir /etc/phosphor-regulators` 216 217### Search Order 218 219The `phosphor-regulators` application will search the installation directories 220in the following order to find a config file: 221 2221. test directory 2232. standard directory 224 225### Firmware Updates 226 227When a new firmware image is installed on the BMC, it will update the config 228file in the standard directory. 229 230The test directory will **not** be modified by a firmware update. If a config 231file exists in the test directory, it will continue to override the config file 232in the standard directory. 233 234## Loading and Reloading 235 236The config file is loaded when the `phosphor-regulators` application starts. 237 238To force the application to reload the config file, use the following command on 239the BMC: 240 241`systemctl kill -s HUP phosphor-regulators.service` 242 243To confirm which config file was loaded, use the following command on the BMC: 244 245`journalctl -u phosphor-regulators.service | grep Loading` 246 247## Testing 248 249After creating or modifying a config file, you should test it to ensure it 250provides the desired behavior. 251 252Perform the following steps to test the config file: 253 254- Run the [validation tool](#validation) to ensure the config file contains no 255 errors. 256- Copy the config file into the [test directory](#test-directory) on the BMC. 257- Force the `phosphor-regulators` application to 258 [reload](#loading-and-reloading) its config file, causing it to find and load 259 the file in the test directory. 260- Boot the system. Regulator configuration changes (such as voltage settings) 261 are only applied during the boot. 262- View output from the `phosphor-regulators` application to make sure no errors 263 occurred. Use the command `journalctl -u phosphor-regulators.service`. 264 265When finished testing, perform the following steps to revert to the standard 266config file: 267 268- Remove the config file from the test directory. If this is not done, the test 269 config file will continue to override the standard config file even after a 270 firmware update. 271- Force the `phosphor-regulators` application to reload its config file, causing 272 it to find and load the file in the standard directory. 273- Boot the system, if necessary, to apply the regulator configuration changes in 274 the standard config file. 275