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