phosphor-regulators Configuration File

Table of Contents

• Overview
• Data Format
• Example
• Name
• Contents
• Validation
• Installation
• Loading and Reloading
• Testing

Overview

The phosphor-regulators application is controlled by a configuration file (config file). The config file defines how to perform the following operations on voltage regulators in the system:

• Modify regulator configuration, such as output voltage or overcurrent settings
• Read sensor values
• Detect redundant phase faults (if necessary)

The config file does not control how voltage regulators are enabled or how to monitor their Power Good (pgood) status. Those operations are typically performed by power sequencer hardware and related firmware.

Data Format

The config file is written using the JSON (JavaScript Object Notation) data format.

The config file can be created using any text editor, such as Visual Studio Code, Atom, Notepad++, Vim, or Emacs.

Example

See config.json.

Name

There are two options for naming the config file:

• Default Name
• Name Based on System Type

Default Name

The default config file name is config.json. The default name can be used if the BMC firmware image only supports one system type. It can also be used if the firmware image supports multiple system types that share a common config file.

Name Based on System Type

The config file name can be based on the system type that it supports. This is required if the BMC firmware image supports multiple system types, and those system types do not share a common config file.

A config file is normally system-specific. Each system type usually has a different set of voltage regulators and rails.

The system type is obtained from a D-Bus Chassis object created by the Entity Manager application. The object must implement the xyz.openbmc_project.Inventory.Decorator.Compatible interface.

The Names property of this interface contains a list of one or more compatible system types. The types are ordered from most specific to least specific.

Example:

• com.acme.Hardware.Chassis.Model.MegaServer4CPU
• com.acme.Hardware.Chassis.Model.MegaServer
• com.acme.Hardware.Chassis.Model.Server

The phosphor-regulators application searches for a config file name that matches one of these compatible system types. It searches from most specific to least specific. The first config file found, if any, will be used.

For each compatible system type, the application will look for two config file names:

• The complete compatible system type plus a '.json' suffix
• The last node of the compatible system type plus a '.json' suffix

Example:

• com.acme.Hardware.Chassis.Model.MegaServer4CPU.json
• MegaServer4CPU.json

If a config file is not found based on system type, phosphor-regulators searches for a file with the default name.

Contents

Structure

The config file typically contains the following structure:

• Array of rules
  • Rules defining how to modify configuration of regulators
  • Rules defining how to read sensors
  • Rules defining how to detect redundant phase faults (if necessary)
• Array of chassis in the system
  • Array of regulator devices in the chassis
    • Array of voltage rails produced by the regulator

Rules provide common, reusable sequences of actions that can be shared by one or more regulators. They are optional and can be omitted if each regulator requires a unique sequence of actions.

Syntax

The config file contains a single JSON config_file object at the root level. That object contains arrays of other JSON objects.

The following JSON object types are supported:

• action
• and
• chassis
• compare_presence
• compare_vpd
• config_file
• configuration
• device
• i2c_capture_bytes
• i2c_compare_bit
• i2c_compare_byte
• i2c_compare_bytes
• i2c_interface
• i2c_write_bit
• i2c_write_byte
• i2c_write_bytes
• if
• log_phase_fault
• not
• or
• phase_fault_detection
• pmbus_read_sensor
• pmbus_write_vout_command
• presence_detection
• rail
• rule
• run_rule
• sensor_monitoring
• set_device

Comments

The JSON data format does not support comments. However, many of the JSON objects in the config file provide an optional "comments" property. The value of this property is an array of strings. Use this property to annotate the config file. The "comments" properties are ignored when the config file is read by the phosphor-regulators application.

Examples:

"comments": [ "IR35221 regulator producing the Vdd rail" ]

"comments": [ "Check if register 0x82 contains 0x7302",
              "Device returns bytes in little-endian order",
              "Ignore most significant bit in each byte" ]

Hexadecimal Values

The JSON number data type does not support the hexadecimal format. For this reason, properties with hexadecimal values use the string data type.

Example:

"address": "0x70"

Validation

After creating or modifying a config file, you need to validate it using the tool validate-regulators-config.py.

The validation tool checks the config file for errors, such as:

• Invalid JSON syntax (like a missing brace)
• Unrecognized JSON object or property
• Duplicate rule or device ID
• Reference to a rule or device ID that does not exist
• Infinite loop, such as rule A runs rule B which runs rule A

The tool requires two input files:

• config file to validate
• config_schema.json

The tool has the following command line syntax:

validate-regulators-config.py -c <config file> -s config_schema.json

where <config file> is the name of the config file to validate.

Installation

Standard Directory

/usr/share/phosphor-regulators

The standard version of the config file is installed in this read-only directory as part of the firmware image install. This is the config file that will normally be used.

Test Directory

/etc/phosphor-regulators

A new version of the config file can be tested by copying it into this writable directory. This avoids the need to build and install a new firmware image on the BMC.

The test directory might not exist on the BMC. If it is missing, create it using the following command:

mkdir /etc/phosphor-regulators

Search Order

The phosphor-regulators application will search the installation directories in the following order to find a config file:

1. test directory
2. standard directory

Firmware Updates

When a new firmware image is installed on the BMC, it will update the config file in the standard directory.

The test directory will not be modified by a firmware update. If a config file exists in the test directory, it will continue to override the config file in the standard directory.

Loading and Reloading

The config file is loaded when the phosphor-regulators application starts.

To force the application to reload the config file, use the following command on the BMC:

systemctl kill -s HUP phosphor-regulators.service

To confirm which config file was loaded, use the following command on the BMC:

journalctl -u phosphor-regulators.service | grep Loading

Testing

After creating or modifying a config file, you should test it to ensure it provides the desired behavior.

Perform the following steps to test the config file:

• Run the validation tool to ensure the config file contains no errors.
• Copy the config file into the test directory on the BMC.
• Force the phosphor-regulators application to reload its config file, causing it to find and load the file in the test directory.
• Boot the system. Regulator configuration changes (such as voltage settings) are only applied during the boot.
• View output from the phosphor-regulators application to make sure no errors occurred. Use the command journalctl -u phosphor-regulators.service.

When finished testing, perform the following steps to revert to the standard config file:

• Remove the config file from the test directory. If this is not done, the test config file will continue to override the standard config file even after a firmware update.
• Force the phosphor-regulators application to reload its config file, causing it to find and load the file in the standard directory.
• Boot the system, if necessary, to apply the regulator configuration changes in the standard config file.