Author: Shawn McCarney (Discord ShawnMcCarney)
Other contributors: Derek Howard (Discord derekh55), Matt Spinler (Discord mspinler)
Created: 2019-07-13
Voltage regulators have many configurable properties such as output voltage, over-current limit, and pgood thresholds. The configuration is often dependent on the system type and rail type. Regulators have a hardware default configuration that is defined by hardware engineers early in system design. However, this default configuration sometimes must be modified by firmware. A new application is needed to configure regulators. It should be data-driven to support a variety of regulator types and to avoid hard-coded logic.
Hardware engineers must specify many low-level configuration values for a regulator. Some simple examples include output voltage, over-current limit, and pgood thresholds. These values often vary depending on the system type and rail type.
Depending on the regulator type, the hardware engineer may enter the configuration values into a tool that produces a "config file".
The regulator configuration information is sent to manufacturing and stored in non-volatile memory on the regulator. This provides the hardware/power-on default configuration.
The default configuration values often need to be changed later. This can be due to factors such as the following:
Regulator configuration changes are performed on some OpenBMC systems using shell scripts. For example, the following scripts configure regulators on Witherspoon systems:
The Linux Hardware Monitoring Kernel API (hwmon) and Industrial I/O Subsystem (IIO) provide device driver frameworks for monitoring hardware and making sensor values available to applications. They do not provide an interface for performing low-level regulator configuration.
The Linux Voltage and Current Regulator API provides a device driver framework for voltage and current regulators. It provides a mechanism for the device drivers of "consumer" devices to request a voltage or current level from the regulator. It does not provide an interface for performing low-level regulator configuration.
A new application named phosphor-regulators will be created to configure voltage regulators. The application will be located in the proposed new phosphor-power repository.
Statement of direction: This application will provide other regulator-based functionality in the future, such as detecting redundant phase faults.
The application will read a JSON file at runtime that defines the configuration changes for all regulators. The JSON file will be specific to a system type, so it will be stored in the GitHub repository for the appropriate build layer (such as meta-ibm).
JSON file location on the BMC:
/usr/share/phosphor-regulators (read-only)/etc/phosphor-regulators (writable)A new version of the JSON file can be tested by copying it to the test directory. The application will search both directories, and the file in the test directory will override the file in the standard directory. If the application receives a SIGHUP signal, it will re-read the JSON file.
A document will be provided that describes the objects and properties that can appear in the JSON file. A validation tool will also be provided to verify the syntax and contents of the JSON file.
Statement of direction: This JSON file will be used in the future to define other regulator operations, such as how to detect a redundant phase fault.
The following new D-Bus interface will be created:
xyz.openbmc_project.Regulator.Collection.ConfigureStatement of direction: New interfaces that apply to all regulators would use the same xyz.openbmc_project.Regulator.Collection namespace. New interfaces that apply to a single regulator would use the xyz.openbmc_project.Regulator namespace.
The new xyz.openbmc_project.Regulator.Collection.Configure interface will be implemented on the object path /xyz/openbmc_project/regulators.
Statement of direction: New interfaces that apply to all regulators would be implemented on the same object path. Individual regulators would be represented by the object path /xyz/openbmc_project/regulators/<regulator_name>, and interfaces that apply to a single regulator would be implemented on that path.
The application will be started using systemd when the BMC is at standby. The service file will be named xyz.openbmc_project.Regulators.service.
During the boot when the chassis is being powered on, the Configure() method on the new xyz.openbmc_project.Regulator.Collection.Configure interface will be called. This must be done prior to the systemd target that enables the regulators (powers them on).
The application will communicate with the voltage regulators directly using the i2c-dev userspace I2C interface. Direct communication will be used rather than device drivers because the current Linux device driver frameworks do not provide the necessary functionality. See the Alternatives Considered section for more information.
Voltage regulators that are configured using this application will not be bound to device drivers in the Linux device tree. When the system is powered on, the application will obtain the regulator sensor values and store them on D-Bus in the same format as phosphor-hwmon.
Statement of direction: If a driver framework is developed in the future that supports low-level regulator configuration, then this application will be enhanced to utilize those drivers. The goal is for the application to support a flexible device interface, where drivers are used if possible and i2c-dev is used if necessary.
Ideally one of the following device driver frameworks could be used rather than i2c-dev to configure the regulators:
Unfortunately none of these provide the required functionality:
A meeting was held with Joel Stanley and Andrew Jeffery to discuss this issue. They believe long term a new driver framework could be designed that would provide this functionality and would be acceptable to the Linux upstream community. If this occurs, this application will be modified to utilize the new driver framework rather than performing direct I2C communication from userspace.
Currently shell scripts are used to configure regulators on some OpenBMC systems, such as Witherspoon. During boot, the shell scripts unbind device drivers, perform i2cset commands to configure regulators, and then re-bind device drivers.
Using shell scripts has the following disadvantages:
i2cset command worked. If error checking were added based on return code, it would be difficult to log an appropriate error with all the necessary information.i2cset command requires starting a separate child process.i2cset.phosphor-hwmon.