PSU Sensor Module

The PSU Sensor Module in tlBMC is responsible for reading multi-channel power telemetries (including voltage, current, power, and temperature) from hardware power controllers, voltage regulators, and PMBus chips via the Hwmon and I3C sysfs Hardware Abstraction Layers (HALs).

Purpose & Overview

PSU Sensors interface with hardware power controllers, PMBus chips, power bricks, and hotswap controllers to collect critical runtime physical telemetry. When enabled as part of the sensor collection subsystem, this module discovers and monitors multi-channel power and thermal attributes, exposing them as standard Redfish Sensor resources within the /redfish/v1/Chassis/{id}/Sensors collection and integrating them directly into the underlying Redfish thermal and power subsystems.

Central Configuration (central_config.proto)

PSU Sensor telemetry collection is managed under the central SensorCollectorModule configuration within central_config.proto. Enabling the central sensor collector activates the discovery and lifecycle management of all configured PSU sensors.

Field Name	Type	Default Value	Description
enabled	bool	false	Controls whether the sensor collector module is active.
allow_sensor_creation_failure	bool	false	If true, non-fatal hardware sysfs probe failures do not abort central sensor collection.
enable_threshold_monitoring	bool	false	If true, creates a background monitoring task to track thresholds and log SEL events upon crossing.
sensor_collection_append_sub_module	SensorCollectionAppendSubmodule	none	Controls appending tlBMC-discovered sensors to external Redfish sensor collections.
thermal_control_sub_module	ThermalControlSubmodule	none	Submodule for orchestrating Redfish thermal and power subsystem integrations.

Entity Manager Configuration Reference

Platform hardware developers configure and activate PSU sensors by defining JSON configuration blocks within Entity Manager configuration files. When an Entity Manager block declares Type matching a supported PSU sensor and specifies "TlbmcOwned": true, tlBMC parses the block and instantiates the underlying channels via sysfs.

Attribute Name	Expected Type	Description
Type	string	The specific hardware
: : : chip or driver type :
: : : (e.g., "ADM1266", :
: : : "PMBUS"). :
Name	string	Base entity name for the
: : : sensor group and :
: : : configuration block. :
Bus	integer / string	Logical I2C or I3C bus
: : : number (or expression :
: : : like "$bus"). :
Address	string	Hexadecimal device
: : : address on the bus :
: : : (e.g., "0x40"). :
Labels	array of string	List of sysfs Hwmon
: : : channel labels to expose :
: : : (e.g., `[“vout1”, :
: : : “curr1”, :
: : : “highestpin”]`). :
<Label>_Name /	string (optional)	Custom Redfish resource
: Name<Index> : : name for a specific :
: : : label channel. :
<Label>_Max /	number (optional)	Custom maximum and
: <Label>_Min : : minimum reading range :
: : : overrides. :
<Label>_Scale /	number (optional)	Custom scaling factor
: <Label>_Offset : : (`reading / scale + :
: : : offset`) override. :
Thresholds	array of object	List of threshold
: : : definitions (Name, :
: : : Value, Direction, :
: : : Severity, optional :
: : : Label). :
RelatedItem	object (optional)	Relates the sensor
: : : entity to a target :
: : : parent resource (Id, :
: : : Type). :
RedfishHidden	boolean / array	Hides specific sensor
: : : instances or all (* or :
: : : true) from Redfish :
: : : collections. :
AppendToSensorCollection	boolean / array	Appends specific sensor
: : : routes or all (* or :
: : : true) to Redfish :
: : : SensorCollection. :
SensorGroup	string (optional)	Identifier for the
: : : sensor group / root bus :
: : : topology association. :
TlbmcOwned	boolean	Must be true for tlBMC
: : : to discover and manage :
: : : this sensor entity. :

Supported Chips & Drivers

tlBMC registers a comprehensive hardware chip mapping table (kSupportedPsuSensorTypes) that automatically associates Entity Manager Type strings with Linux kernel sysfs driver names:

Entity Manager Type	Kernel Driver Name	Interface & Notes
ADM1266	"adm1266"	Standard I2C/PMBus Hwmon
: : : driver. :
ADM1272	"adm1272"	Standard I2C/PMBus Hwmon
: : : driver. :
ADM1273	"adm1275"	Uses adm1275 kernel
: : : driver. :
BMR490	"bmr490"	Standard I2C/PMBus Hwmon
: : : driver. :
DPS800	"dps800"	Standard I2C/PMBus Hwmon
: : : driver. :
GOOGLE_TPU	"google_tpu"	Standard I2C/PMBus Hwmon
: : : driver. :
INA226	"ina226"	Voltage and current
: : : monitoring driver. :
LTC2991	"ltc2991"	Octal I2C
: : : voltage/current/temperature :
: : : monitor. :
LTC4287	"ltc4286"	Uses ltc4286 kernel
: : : driver. :
LX6301	"lx6301"	Standard I2C Hwmon driver.
MAX20826	"max20826"	Standard I2C/PMBus Hwmon
: : : driver. :
MAX20830C	"max20830c"	Standard I2C/PMBus Hwmon
: : : driver. :
MAX20840C	"max20840c"	Standard I2C/PMBus Hwmon
: : : driver. :
MAX34451	"max34451"	Standard I2C/PMBus Hwmon
: : : driver. :
MP2925	"mp2925"	Standard I2C/PMBus Hwmon
: : : driver. :
MP2929	"mp2929"	Standard I2C/PMBus Hwmon
: : : driver. :
MP5998	"mp5998"	Standard I2C/PMBus Hwmon
: : : driver. :
PMBUS	"pmbus"	Generic PMBus monitoring
: : : interface. :
Q50SN12072	"q50sn12072"	Standard I2C/PMBus Hwmon
: : : driver. :
Q54SN120A4	"q54sn120a4"	Standard I2C/PMBus Hwmon
: : : driver. :
RAA228228	"raa228228"	Standard I2C/PMBus Hwmon
: : : driver. :
RAA229141	"raa229141"	Standard I2C/PMBus Hwmon
: : : driver. :
RAA229621	"raa229621"	Standard I2C/PMBus Hwmon
: : : driver. :
RAA229639	"raa229639"	Standard I2C/PMBus Hwmon
: : : driver. :
SBRMI_I3C	"sbrmi_i3c"	I3C Required Chip:
: : : Requires I3C Sysfs HAL :
: : : interaction :
: : : (IsI3cPsuSensor). :
SBTSI_I3C	"sbtsi_i3c"	I3C Required Chip:
: : : Requires I3C Sysfs HAL :
: : : interaction :
: : : (IsI3cPsuSensor). :
TDA38640	"tda38640"	Standard I2C/PMBus Hwmon
: : : driver. :
TDA38725	"tda38725"	Standard I2C/PMBus Hwmon
: : : driver. :
TDA38740	"tda38740"	Standard I2C/PMBus Hwmon
: : : driver. :
TPS25990	"tps25990"	Standard I2C/PMBus Hwmon
: : : driver. :
TPS546E25	"tps546e25"	Standard I2C/PMBus Hwmon
: : : driver. :
XDPE19284C	"xdpe19284c"	Standard I2C/PMBus Hwmon
: : : driver. :
XDPE1A2G5B	"xdpe1a2g5b"	Standard I2C/PMBus Hwmon
: : : driver. :

[!NOTE] Chips designated as I3C Required Chips (SBTSI_I3C and SBRMI_I3C) are verified via PsuSensor::IsI3cPsuSensor and utilize the I3cSysfs HAL for device detection and sysfs HWMon path resolution.

Default Reading Properties & Scale Factors (kDefaultPsuSensorProperties)

tlBMC automatically maps non-digit base labels (e.g., vout1 stripped of numbers -> vout) to standardized default physical reading properties (ReadingProperties). This mapping assigns correct physical quantities, units (SensorUnit), scale divisor powers (pow(10, scale)), and defaults:

| Base Label | Physical | Default Unit | Scale | Default | : : Quantity : : Divisor : Range : : : : : (pow(10, : (Min / : : : : : scale)) : Max) : | :------------ | :---------- | :-------------------- | :---------- | :------- | | curr / | Output | UNIT_AMPERE | 1000 | 0.0 / | : iout : Current : : (pow(10, : 255.0 : : : : : 3)) : A : | iin | Input | UNIT_AMPERE | 1000 | 0.0 / | : : Current : : (pow(10, : 20.0 A : : : : : 3)) : : | isysin / | System | UNIT_AMPERE | 1000 | 0.0 / | : isysout : Current : : (pow(10, : 255.0 : : : : : 3)) : A : | highestiout | Peak Output | UNIT_AMPERE | 1000 | 0.0 / | : / peakiout : Current : : (pow(10, : 255.0 : : : : : 3)) : A : | vin | Input | UNIT_VOLT | 1000 | 0.0 / | : : Voltage : : (pow(10, : 300.0 : : : : : 3)) : V : | in / vout | Output | UNIT_VOLT | 1000 | 0.0 / | : / voltage : Voltage : : (pow(10, : 255.0 : : : : : 3)) : V : | vmon | Auxiliary | UNIT_VOLT | 1000 | 0.0 / | : : Input : : (pow(10, : 255.0 : : : Voltage : : 3)) : V : | highestvin | Peak Input | UNIT_VOLT | 1000 | 0.0 / | : : Voltage : : (pow(10, : 300.0 : : : : : 3)) : V : | highestvout | Peak Output | UNIT_VOLT | 1000 | 0.0 / | : : Voltage : : (pow(10, : 255.0 : : : : : 3)) : V : | peakvin | Peak Input | UNIT_VOLT | 1000 | 0.0 / | : : Voltage : : (pow(10, : 300.0 : : : : : 3)) : V : | peakvout | Peak Output | UNIT_VOLT | 1000 | 0.0 / | : : Voltage : : (pow(10, : 255.0 : : : : : 3)) : V : | pin | Input Power | UNIT_WATT | 1,000,000 | 0.0 / | : : : : (pow(10, : 3000.0 : : : : : 6)) : W : | pout / | Output | UNIT_WATT | 1,000,000 | 0.0 / | : power : Power : : (pow(10, : 3000.0 : : : : : 6)) : W : | highestpin | Peak Input | UNIT_WATT | 1,000,000 | 0.0 / | : / peakpin : Power : : (pow(10, : 3000.0 : : : : : 6)) : W : | temp | Temperature | UNIT_DEGREE_CELSIUS | 1000 | -128.0 | : : : : (pow(10, : / : : : : : 3)) : 127.0 : : : : : : °C : | highesttemp | Peak | UNIT_DEGREE_CELSIUS | 1000 | -128.0 | : / peaktemp : Temperature : : (pow(10, : / : : : : : 3)) : 127.0 : : : : : : °C :

[!TIP] When sysfs returns integer raw readings (e.g. millivolts, milliamps, microwatts), PsuSensor::HandleRefreshResult applies the final conversion: reading = (raw_value / scale) + offset.

Special File Type Handling (PsuSensorFileType)

To handle distinct historical sysfs file naming conventions across power controller drivers, PsuSensor::GetPsuSensorFileInfo inspects sysfs file suffixes and associates them with appropriate label modification prefixes:

• kDefault (_input suffix): Standard telemetry input reading file (e.g., in1_input, temp1_input). Applies an empty ("") label modifier prefix.
• kHighestPower (_input_highest suffix): Special sysfs file generated for peak power telemetries (e.g., power1_input_highest). Applies the "highest" label modifier prefix.
• kHighestDefault (_highest suffix): Special sysfs file generated for peak temperature or voltage defaults (e.g., temp1_highest). Applies the "highest" label modifier prefix.

Label Normalization: To maintain cross-platform compatibility where integrators interchange "highest" and "peak" modifiers (e.g. "highestpin" vs "peakpin"), tlBMC automatically maps both prefixes to the same underlying sysfs input file.

Sensor Key Generation (GetPsuSensorKey)

Every instantiated PSU Sensor receives a fully qualified unique identifier (name) within Redfish:

1. Custom Name Check: If the Entity Manager configuration explicitly provides <Label>_Name or Name<Index>, that string is used directly.
2. Fallback Derivation: Otherwise, combines the parent configuration block name and the label's descriptive type name (e.g., ADM1266_Input_Voltage).
3. Unit Prefix Assignment: Regardless of origin, GetPsuSensorKey prefixes the final Redfish identifier based on its physical unit:
   • UNIT_AMPERE $\rightarrow$ current_{name}
   • UNIT_VOLT $\rightarrow$ voltage_{name}
   • UNIT_WATT $\rightarrow$ power_{name}
   • UNIT_DEGREE_CELSIUS $\rightarrow$ temperature_{name}

Protobuf Configuration

The following underlying protobuf schemas define the runtime data structures, properties, and configuration parsing models for PSU Sensors:

• psu_sensor_config.proto: Defines PsuSensorType enums and the primary PsuSensorConfig message mapping labels to instance properties.
• hal_common_config.proto: Defines logical bus numbers and hardware addresses (HalCommonConfig).
• sensor_instance_properties.proto: Defines instance-specific units, thresholds, transforms, ranges, and visibility flags (SensorInstanceProperties).
• entity_common_config.proto: Defines entity-level refresh intervals, queue sizes, sensor groups, and power state dependencies (EntityCommonConfig).
• central_config.proto: Defines top-level collection orchestration options (SensorCollectorModule).
• reading_range_config.proto: Defines min/max operational reading ranges (ReadingRangeConfigs).
• reading_transform_config.proto: Defines scaling divisors and offsets (ReadingTransformConfig).
• threshold_config.proto: Defines critical and non-critical thresholds (ThresholdConfigs).

Usage & Configuration Examples

Below is a concrete, fully qualified Entity Manager configuration block defining an ADM1266 power supply controller on Bus 20 at Address 0x40. It exposes specific voltage channels and configures an upper critical threshold:

{
   "Address": "0x40",
   "Bus": 20,
   "Labels": [
      "vout1",
      "vout5",
      "vout6"
   ],
   "Name": "ADM1266",
   "Thresholds": [
      {
         "Direction": "greater than",
         "Label": "vout1",
         "Name": "upper critical",
         "Severity": 1,
         "Value": 13.56
      }
   ],
   "TlbmcOwned": true
}

Code References

• psu_sensor.h: Main header defining PsuSensor, PsuSensorFileType, and scale mappings.
• psu_sensor.cc: Implementation file containing registered chip models, default properties, and sysfs reading parsers.
• entity_config_json_impl.cc: Entity Manager JSON configuration parser implementing ParsePsuSensorConfig.