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