1# Voltage Regulator Configuration 2 3Author: Shawn McCarney (Discord ShawnMcCarney) 4 5Other contributors: Derek Howard (Discord derekh55), Matt Spinler (Discord 6mspinler) 7 8Created: 2019-07-13 9 10## Problem Description 11 12[Voltage regulators][1] have many configurable properties such as output 13voltage, over-current limit, and pgood thresholds. The configuration is often 14dependent on the system type and rail type. Regulators have a hardware default 15configuration that is defined by hardware engineers early in system design. 16However, this default configuration sometimes must be modified by firmware. A 17new application is needed to configure regulators. It should be data-driven to 18support a variety of regulator types and to avoid hard-coded logic. 19 20## Background and References 21 22### Regulator Configuration Data ("Config File") 23 24Hardware engineers must specify many low-level configuration values for a 25regulator. Some simple examples include output voltage, over-current limit, and 26pgood thresholds. These values often vary depending on the system type and rail 27type. 28 29Depending on the regulator type, the hardware engineer may enter the 30configuration values into a tool that produces a "config file". 31 32The regulator configuration information is sent to manufacturing and stored in 33non-volatile memory on the regulator. This provides the hardware/power-on 34default configuration. 35 36The default configuration values often need to be changed later. This can be due 37to factors such as the following: 38 39- New information found during hardware testing. For example, downstream 40 hardware requires a higher voltage or is drawing more current than expected. 41- Hardware workarounds. Problems in the regulator hardware or related hardware 42 sometimes require new configuration values to work around the issue. The 43 problem may be resolved in newer versions of the hardware, but firmware still 44 must support the older hardware. For this reason, hardware workarounds are 45 sometimes conditional, applied only to regulators with a certain version 46 register value or [Vital Product Data (VPD)][2] keyword value. 47- Improve manufacturing yields. Sometimes regulator configuration values must be 48 changed to allow more hardware to pass manufacturing tests. For example, the 49 voltage may need to be increased to overcome minor manufacturing defects. 50 51### OpenBMC Regulator Configuration Scripts 52 53Regulator configuration changes are performed on some OpenBMC systems using 54shell scripts. For example, the following scripts configure regulators on 55Witherspoon systems: 56 57- [vrm-control.sh][3] 58- [power-workarounds.sh][4] 59 60### Hwmon and IIO Device Driver Frameworks 61 62The Linux [Hardware Monitoring Kernel API (hwmon)][5] and [Industrial I/O 63Subsystem (IIO)][6] provide device driver frameworks for monitoring hardware and 64making sensor values available to applications. They do not provide an interface 65for performing low-level regulator configuration. 66 67### Voltage and Current Regulator Device Framework 68 69The Linux [Voltage and Current Regulator API][7] provides a device driver 70framework for voltage and current regulators. It provides a mechanism for the 71device drivers of "consumer" devices to request a voltage or current level from 72the regulator. It does not provide an interface for performing low-level 73regulator configuration. 74 75## Requirements 76 77- Provide ability to modify configuration of any voltage regulator with a PMBus 78 or I2C connection to the BMC. 79- Apply the configuration changes early in the boot before the regulators are 80 enabled. 81- If an error occurs trying to configure a regulator, log the error and continue 82 with the next regulator. 83- Read configuration changes from a data file that is read at run-time. 84- Provide a method for testing new configuration changes by copying a new data 85 file to the BMC. 86 87### Non-Requirements 88 89- Enable/disable voltage regulators and monitor their pgood signals. 90 - This is handled by the power sequencer chip and related firmware. 91- Modify regulator configuration after regulator has been enabled. 92 - Modifying regulator configuration while the system is running is often done 93 by the host using a different bus connection. 94- Validate that the correct number and types of regulators are present in the 95 system. 96- Concurrent maintenance or hot-plugging of regulators, where a regulator is 97 removed/added/replaced while the system is running. 98 99## Proposed Design 100 101### Application 102 103A new application named `phosphor-regulators` will be created to configure 104voltage regulators. The application will be located in the proposed new 105`phosphor-power` repository. 106 107_Statement of direction: This application will provide other regulator-based 108functionality in the future, such as detecting redundant phase faults._ 109 110### Application Data File 111 112The application will read a JSON file at runtime that defines the configuration 113changes for all regulators. The JSON file will be specific to a system type, so 114it will be stored in the GitHub repository for the appropriate build layer (such 115as meta-ibm). 116 117JSON file location on the BMC: 118 119- Standard directory: `/usr/share/phosphor-regulators` (read-only) 120- Test directory: `/etc/phosphor-regulators` (writable) 121 122A new version of the JSON file can be tested by copying it to the test 123directory. The application will search both directories, and the file in the 124test directory will override the file in the standard directory. If the 125application receives a SIGHUP signal, it will re-read the JSON file. 126 127A document will be provided that describes the objects and properties that can 128appear in the JSON file. A validation tool will also be provided to verify the 129syntax and contents of the JSON file. 130 131_Statement of direction: This JSON file will be used in the future to define 132other regulator operations, such as how to detect a redundant phase fault._ 133 134### D-Bus Interfaces 135 136The following new D-Bus interface will be created: 137 138- Name: `xyz.openbmc_project.Regulator.Collection.Configure` 139- Description: Configures all voltage regulators. 140- Properties: None 141- Methods: Configure() 142 143_Statement of direction: New interfaces that apply to all regulators would use 144the same xyz.openbmc_project.Regulator.Collection namespace. New interfaces that 145apply to a single regulator would use the xyz.openbmc_project.Regulator 146namespace._ 147 148### D-Bus Paths 149 150The new `xyz.openbmc_project.Regulator.Collection.Configure` interface will be 151implemented on the object path `/xyz/openbmc_project/regulators`. 152 153_Statement of direction: New interfaces that apply to all regulators would be 154implemented on the same object path. Individual regulators would be represented 155by the object path `/xyz/openbmc_project/regulators/<regulator_name>`, and 156interfaces that apply to a single regulator would be implemented on that path._ 157 158### Systemd 159 160The application will be started using systemd when the BMC is at standby. The 161service file will be named `xyz.openbmc_project.Regulators.service`. 162 163During the boot when the chassis is being powered on, the Configure() method on 164the new `xyz.openbmc_project.Regulator.Collection.Configure` interface will be 165called. This must be done prior to the systemd target that enables the 166regulators (powers them on). 167 168### Regulator Device Interface 169 170The application will communicate with the voltage regulators directly using the 171[i2c-dev][8] userspace I2C interface. Direct communication will be used rather 172than device drivers because the current Linux device driver frameworks do not 173provide the necessary functionality. See the 174[Alternatives Considered](#alternatives-considered) section for more 175information. 176 177Voltage regulators that are configured using this application will not be bound 178to device drivers in the Linux device tree. When the system is powered on, the 179application will obtain the regulator sensor values and store them on D-Bus in 180the same format as `phosphor-hwmon`. 181 182_Statement of direction: If a driver framework is developed in the future that 183supports low-level regulator configuration, then this application will be 184enhanced to utilize those drivers. The goal is for the application to support a 185flexible device interface, where drivers are used if possible and i2c-dev is 186used if necessary._ 187 188## Alternatives Considered 189 190### Using Standard Linux Device Drivers to Configure Regulators 191 192Ideally one of the following device driver frameworks could be used rather than 193i2c-dev to configure the regulators: 194 195- [Hardware Monitoring Kernel API][5] 196- [Industrial I/O Subsystem][6] 197- [Voltage and Current Regulator API][7] 198 199Unfortunately none of these provide the required functionality: 200 201- Ability to perform system-specific and rail-specific, low-level configuration. 202- Ability to perform dynamic configuration based on regulator version register 203 values or [VPD][2] values. 204- Ability to test new configuration values iteratively and quickly without 205 needing to modify a device driver or rebuild the kernel. 206 207A meeting was held with Joel Stanley and Andrew Jeffery to discuss this issue. 208They believe long term a new driver framework could be designed that would 209provide this functionality and would be acceptable to the Linux upstream 210community. If this occurs, this application will be modified to utilize the new 211driver framework rather than performing direct I2C communication from userspace. 212 213### Using Shell Scripts to Configure Regulators 214 215Currently shell scripts are used to configure regulators on some OpenBMC 216systems, such as Witherspoon. During boot, the shell scripts unbind device 217drivers, perform `i2cset` commands to configure regulators, and then re-bind 218device drivers. 219 220Using shell scripts has the following disadvantages: 221 222- Typically no error checking is performed to verify the `i2cset` command 223 worked. If error checking were added based on return code, it would be 224 difficult to log an appropriate error with all the necessary information. 225- On a large system with many regulators and register updates, a shell script 226 would run more slowly than an application and negatively impact boot speed. 227 Each `i2cset` command requires starting a separate child process. 228- Scripts are usually hard-coded to one system type and do not provide a common, 229 data-driven solution. 230 231## Impacts 232 233- No major impacts are expected to existing APIs, security, documentation, 234 performance, or upgradability. 235- The new D-Bus interface is documented in the 236 [Proposed Design](#proposed-design) section. 237- The application should be able to configure regulators using i2c-dev as fast 238 or faster than equivalent shell scripts using `i2cset`. 239- The regulator sensor values will be stored on D-Bus in a way that is 240 consistent with `phosphor-hwmon`. 241 242## Testing 243 244- Automated test cases will be written to test as much of the application code 245 as possible. 246- A mock device interface will be used to test that the correct I2C reads and 247 writes are occurring without accessing real hardware. 248- End-to-end boot testing will be performed to ensure that the correct I2C 249 reads/writes occurred, that the system boots, and that no errors occur. 250- CI tests that boot a system will indirectly test this application. 251 252[1]: https://en.wikipedia.org/wiki/Voltage_regulator_module 253[2]: https://en.wikipedia.org/wiki/Vital_Product_Data 254[3]: 255 https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/vrm-control/vrm-control.sh 256[4]: 257 https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/power-workarounds/witherspoon/power-workarounds.sh 258[5]: https://www.kernel.org/doc/html/latest/hwmon/hwmon-kernel-api.html 259[6]: https://www.kernel.org/doc/html/latest/driver-api/iio/index.html 260[7]: https://www.kernel.org/doc/html/latest/driver-api/regulator.html 261[8]: https://www.kernel.org/doc/Documentation/i2c/dev-interface 262