PMBus support in U-Boot

This document describes U-Boot’s PMBus 1.x support: what it is for, how it is structured, and how to add support for a new PMBus chipn either from scratch from a chip datasheet or by porting an existing Linux drivers/hwmon/pmbus/ driver.

Intent and scope

U-Boot’s PMBus layer is not a hardware monitoring (hwmon) clone of the Linux kernel’s drivers/hwmon/pmbus/ subsystem. Linux owns the runtime side: continuous polling, sysfs publication, alert IRQ handling, fan control loops. U-Boot owns the boot time side. Concretely the U-Boot PMBus support exists to:

  • Identify the PMBus regulator(s) a board carries at boot: MFR_ID, MFR_MODEL, MFR_REVISION reads, plus a quick STATUS_WORD sanity check.

  • Print telemetry so an operator can confirm rail voltages, input current, and temperature before handing off to the kernel. One shot reads, on demand, via the pmbus and regulator U-Boot commands (pmbus dev <name>; pmbus telemetry, regulator dev <name>; regulator value).

  • Decode chip alerts when a rail trips an over/under voltage, over current, or thermal threshold; so a boot log shows why the previous boot failed, before the kernel even comes up.

  • Optionally trim a critical rail (typically the SoC core) before the kernel takes over; “set the voltage prior to a kernel boot to better protect the board”. This is the existing board/nxp/common/vid.c AVS path and any future per board speed binning trim.

Out of scope, by design:

  • No periodic polling. No worker thread. No background updates.

  • No sysfs / procfs / userspace surface. U-Boot has none.

  • No fan speed control loop. The kernel runs that.

  • No long tail of virtual sensor registers (PMBUS_VIRT_*).

  • No sensor caching / update timestamps.

If you find yourself wanting any of those, the answer is “wait until Linux comes up”. Keep U-Boot’s PMBus surface minimal.

Architecture overview

The framework is split into four layers (layer 3 comes in two flavours, 3a and 3b),

+----------------------------------------+
|     Layer 1: include/pmbus.h           |
|     Standard PMBus 1.x command codes,  |
|     numeric format enum, sensor class  |
|     enum, struct pmbus_driver_info,    |
|     decoder + transport prototypes,    |
|     STATUS_WORD bit names.             |
+----------------------------------------+
|     Layer 2: lib/pmbus.c               |
|     Format decoders (LINEAR11/LINEAR16/|
|     DIRECT) and encoder (LINEAR16),    |
|     two stage SMBus block read helper, |
|     STATUS_*-bit print tables, generic |
|     dispatcher pmbus_reg2data().       |
+----------------------------------------+
|     Layer 3a: drivers/power/regulator/ |
|               <chip>.c                 |
|     UCLASS_REGULATOR per chip drivers  |
|    ; one struct pmbus_driver_info    |
|     plus regulator set_value/get_value |
|     ops. Optional: per chip identify() |
|     hook to refine format from the     |
|     chip's own VOUT_MODE.              |
+----------------------------------------+
|     Layer 3b: drivers/power/regulator/ |
|               pmbus_generic.c          |
|     Catch all driver matching          |
|     compatible = "pmbus".              |
|     Auto detects format via VOUT_MODE  |
|     and PMBUS_QUERY where supported.   |
|     Use for compliant chips with no    |
|     per chip driver yet; ship        |
|     telemetry today, write a per chip  |
|     driver later only if quirks demand |
|     it.                                |
+----------------------------------------+
|     Layer 4: board/<vendor>/<board>/   |
|              <chip>_diag.c             |
|     Diagnostic commands only:          |
|       <chip>_info / <chip>_raw         |
|     Reads via regulator_get_value()    |
|     and lib/pmbus.c helpers. LINEAR /  |
|     DIRECT math NOT here.              |
+----------------------------------------+

Generic vs. board specific separation rule. Layer 1, 2, and 3 files are tree level and platform agnostic. Their comments may reference only:

  • the PMBus 1.x specification, and

  • chip manufacturer datasheets.

Never a specific board, SoC, or product. Board-specific quirks (a particular bus number, a particular slave address, a particular PCB feedback divider, board local design notes) live exclusively in board/<vendor>/<board>/ files.

CLI commands

The framework publishes one top level command, pmbus, plus a vendor namespace dispatcher so per chip code can register chip specific extensions without touching the framework.

Active device model

pmbus mirrors the regulator command: select an active device once, then operate on it across subcommands. The active device is selected by I2C bus (decimal sequence number) and 7 bit address (hex, 0x optional, à la i2c convention):

=> pmbus dev 0:10
pmbus: active i2c0:0x10  MFR_ID="MPS"  MFR_MODEL="MPQ8785"  vendor=mps

The framework probes MFR_ID (in both natural and reverse byte orders) at selection time, looks the result up in the chip match registry populated by per chip code via pmbus_register_chip(), and caches the matched pmbus_driver_info. All subsequent subcommands consume that cached metadata.

Standard subcommands

pmbus list                       list UCLASS_REGULATOR devices (DM bound)
pmbus dev [<bus>:<addr>]         show / select active PMBus device
pmbus info                       identification banner + driver_info
pmbus telemetry                  decoded VIN, VOUT, IIN, IOUT, TEMP
pmbus status                     decode every STATUS_* register
pmbus dump                       hex dump of every standard register
pmbus read <reg> [b|w|s]         raw read (b=byte, w=word, s=string)
pmbus write <reg> <val> [b|w]    raw write
pmbus clear [faults]             issue CLEAR_FAULTS (03h)
pmbus vout [<uV>]                read or set VOUT_COMMAND (microvolts)
pmbus scan [<bus>]               PMBus aware probe of one or all I2C buses

The <reg> argument accepts either a hexadecimal address (88, 0x optional) or a symbolic name (READ_VIN, VOUT_MODE, MFR_ID); symbolic names win when both parsed. <val> is hexadecimal too. Only pmbus vout’s microvolt argument and bus numbers are decimal. Format selectors after the register select the SMBus transaction width: b for byte, w for 16 bit little endian word, s for the SMBus block read used by string registers.

Decoded telemetry honours the active device’s pmbus_driver_info; when no chip match has been registered, VOUT falls back to LINEAR16 driven by VOUT_MODE and the other sensors fall back to LINEAR11.

Vendor namespace

Per chip drivers and board files publish chip specific subcommands in the pmbus <vendor> ... namespace by calling pmbus_register_vendor_handler() at init time. The framework dispatches pmbus mps last, pmbus mps clear last, and pmbus mps clear force to the MPS handler when the active device matches the mps vendor. Additional vendor handlers for lltc, renesas, etc. land alongside the per chip drivers that need them.

Relationship to vdd_override / vdd_read

The NXP Layerscape vdd_override <mV> and vdd_read commands remain available in their original form for compatibility with existing AVS production scripts. The new pmbus vout and pmbus vout <uV> subcommands cover the read and single shot write paths against the same chips, but do not implement vdd_override’s full sequence (board drop compensation, fuse target derivation, multi step convergence loop, atomic PAGE_PLUS_WRITE block transaction, WRITE_PROTECT dance). For interactive bring up pmbus vout is sufficient; for production AVS, vdd_override stays canonical.

Lifecycle: from board boot to Linux handoff

The PMBus framework spans the entire U-Boot lifecycle. This section walks the boot timeline phase by phase, showing when each piece comes online and how the regulator uclass and the pmbus CLI converge on the same chip.

Timeline overview

Phase 0  chip power on              chip ramps to NVM default VOUT
Phase 1  boot ROM / SPL / TF-A      PMBus typically untouched
Phase 2  U-Boot relocation, DM init regulators bound, not probed
Phase 3  first regulator probe      chip driver runs, framework lights up
Phase 4  board hooks / boot scripts snapshot, AVS trim, gating
Phase 5  Linux handoff              DT passed, chip state preserved
Phase 6  Linux runtime              kernel pmbus driver takes over

Phase 0: chip power on

When the regulator chip receives its input voltage, it ramps its output to the VOUT default programmed into its NVM at factory provisioning. PMBus is silent: no software runs anywhere on the SoC yet.

Phase 1: pre U-Boot stages

Boot ROMs, secondary boot loaders (SPL, ARM TF-A BL2 / BL31) typically do not touch PMBus. They focus on PLLs, DDR PHY init, and bringing up enough hardware to load the next stage. Some platforms have a pre U-Boot AVS path in board specific TF-A code that writes VOUT_COMMAND from a fuse derived target; that path is independent of the U-Boot framework described here.

Phase 2: U-Boot relocation and DM init

After relocation, U-Boot binds device tree nodes to drivers but does not probe them. UCLASS_REGULATOR devices for PMBus chips are bound (driver and DT match resolved) but the .probe callback has not run yet.

Framework state at this point:

  • chip match registry: empty

  • vendor handler registry: empty

  • active device: none

  • regulator uclass: devices bound, none probed

Phase 3: lazy regulator probe

The first caller into the regulator uclass for a given chip triggers the chip driver’s .probe. Typical first callers:

  • a board EVENT_SPY at EVT_LAST_STAGE_INIT (boot snapshot)

  • a U-Boot script: regulator dev <name>; regulator value

  • the pmbus dev <name> CLI command (resolves to the regulator)

  • another DT consumer with a regulator-supplies reference

The probe chain looks like this:

<chip>_probe(dev)
    pmbus_regulator_probe_common(dev, &<chip>_info, page)
        dev_read_addr(dev)               -> reg = <addr>
        i2c_get_chip(dev->parent, addr)  -> I2C chip handle
        priv->i2c_dev = handle
        priv->info    = &<chip>_info
        priv->page    = page
        (page > 0)  write PMBUS_PAGE
    <chip>_identify_vout(priv->i2c_dev)        [optional]
        read VOUT_MODE; refine info->format[PSC_VOLTAGE_OUT]
    pmbus_regulator_apply_voltage_scale(dev, fb_div)  [optional]
        write PMBUS_VOUT_SCALE_LOOP if DT property set
    pmbus_register_chip(&<chip>_match)              [idempotent]
    pmbus_register_vendor_handler(&<chip>_op)       [idempotent]

Once probed, three independent surfaces are functional against the same chip:

  • the regulator uclass API (regulator_get_value, regulator_set_value, regulator_get_enable, regulator_set_enable)

  • the pmbus CLI (chip is reachable by name through pmbus_resolve_by_name(), by raw <bus>:<addr> through pmbus_set_active())

  • the chip’s vendor extension subcommands (pmbus <vendor> ...)

Phase 4: board hooks and boot scripts

Boards hook the boot flow at well known points to drive board specific PMBus behaviour. The framework prescribes none of these; they are conventions:

  • boot time rail snapshot. An EVENT_SPY at EVT_LAST_STAGE_INIT reads telemetry through the regulator uclass and prints a one shot summary to the console. Useful for operator visibility on serial during bring up.

  • pre kernel rail trim (AVS). A board hook in board_late_init or a custom event spy reads a fuse derived target voltage and calls regulator_set_value_force() to trim the SoC core rail before kernel handoff.

  • Linux handoff gate. A bootcmd reads the rail voltage through the regulator command and refuses to boot Linux if the rail is outside the expected range.

Phase 5: Linux handoff

When U-Boot transfers control to Linux, it passes the device tree (potentially patched). The DT compatible strings for PMBus regulators must match those in the upstream kernel binding so the kernel’s drivers/hwmon/pmbus/<chip>.c picks them up. Property names are shared with the kernel binding (regulator-name, regulator-min-microvolt, mps,vout-fb-divider-ratio-permille, etc.); see “DT alignment with Linux” below.

The chip itself is left in the state U-Boot wrote it to. If U-Boot trimmed VOUT, the chip stays at the trimmed voltage through handoff. CLEAR_FAULTS state is preserved unless an operator explicitly issued one.

Phase 6: Linux runtime

Linux’s drivers/hwmon/pmbus/pmbus_core.c probes the chip, exposes telemetry under /sys/class/hwmon, and takes over runtime voltage management through its regulator subsystem. The hwmon framework polls periodically; U-Boot does not.

Operation paths through the regulator uclass

After the first probe completes, calls into the regulator uclass for a PMBus chip flow through the shared helper.

Read VOUT:

regulator_get_value(dev)
   -> dm_regulator_ops->get_value
   -> pmbus_regulator_get_value(dev)
      pmbus_regulator_select_page(priv)
      pmbus_read_byte(priv->i2c_dev, VOUT_MODE, &mode)
      pmbus_read_word(priv->i2c_dev, READ_VOUT, &raw)
      pmbus_reg2data(priv->info, PSC_VOLTAGE_OUT, raw, mode)
          -> reg2data_linear16  (mode = 0)
          -> reg2data_direct    (chip configured for DIRECT)
      return engineering value (microvolts)

Write VOUT:

regulator_set_value(dev, uV)
   -> dm_regulator_ops->set_value
   -> pmbus_regulator_set_value(dev, uV)
      pmbus_regulator_select_page(priv)
      pmbus_read_byte(VOUT_MODE)
      check (mode == LINEAR)         [LINEAR16 only today]
      raw = pmbus_data2reg_linear16(uV, mode)
      dm_i2c_write(VOUT_COMMAND, raw)

Read / write enable bit:

regulator_get_enable(dev)
   -> pmbus_regulator_get_enable(dev)
      pmbus_read_byte(OPERATION) & PB_OPERATION_ON

regulator_set_enable(dev, on)
   -> pmbus_regulator_set_enable(dev, on)
      read OPERATION, set or clear PB_OPERATION_ON, write back

Bus traffic per call:

  • get_value : 1 byte read (VOUT_MODE) + 1 word read (READ_VOUT) + 1 byte write (PAGE) when page > 0

  • set_value : 1 byte read (VOUT_MODE) + 1 word write (VOUT_COMMAND) + 1 byte write (PAGE) when page > 0

  • get_enable : 1 byte read (OPERATION)

  • set_enable : 1 byte read (OPERATION) + 1 byte write (OPERATION)

Common board hook patterns

Boot time rail snapshot:

static int my_board_pmbus_snapshot(void)
{
    struct udevice *reg;

    if (regulator_get_by_platname("MY_RAIL", &reg))
        return 0;
    printf("MY_RAIL: VOUT = %d uV, enabled = %d\n",
           regulator_get_value(reg),
           regulator_get_enable(reg));
    return 0;
}
EVENT_SPY_SIMPLE(EVT_LAST_STAGE_INIT, my_board_pmbus_snapshot);

The first call to regulator_get_value() triggers the chip driver’s .probe, which seeds the chip match and vendor extension registries. Subsequent pmbus CLI commands work without further setup.

Pre kernel rail trim (AVS):

int board_late_init(void)
{
    struct udevice *reg;
    int target_uV = compute_avs_target();

    if (regulator_get_by_platname("VDD_CORE", &reg))
        return 0;
    return regulator_set_value_force(reg, target_uV);
}

Use regulator_set_value_force() when the target may sit outside the DT declared regulator-min-microvolt / regulator-max-microvolt range; force bypasses the bounds check.

Adding a new PMBus chip from scratch

Use this path when the chip has no Linux driver yet, or when you want to validate the U-Boot port against the datasheet alone.

  1. Confirm PMBus 1.x compliance level. Locate in the chip datasheet:

    which PMBus standard command codes the chip implements (READ_VIN, READ_VOUT, STATUS_WORD, MFR_ID …), which numeric format(s) it uses for VOUT (LINEAR16 with the exponent in VOUT_MODE, DIRECT with chip specific m/b/R, or VID with one of the documented VRM tables), which numeric format it uses for VIN, IIN, IOUT, TEMPERATURE (most commonly LINEAR11; some MPS / MPS derivative chips use DIRECT instead), how many output rails it exposes (single page parts vs. multi rail PMBus pages).

  2. Declare a struct pmbus_driver_info. Wire each sensor class to one enum pmbus_data_format, plus the m/b/R triple if the format is DIRECT:

    static struct pmbus_driver_info chipname_info = {
    .pages = 1,
    .format[PSC_VOLTAGE_IN]  = pmbus_fmt_direct,
    .format[PSC_VOLTAGE_OUT] = pmbus_fmt_linear,
    .format[PSC_CURRENT_OUT] = pmbus_fmt_direct,
    .format[PSC_TEMPERATURE] = pmbus_fmt_direct,
    .m[PSC_VOLTAGE_IN]  = 4,  .R[PSC_VOLTAGE_IN]  = 1,
    .m[PSC_CURRENT_OUT] = 16, .R[PSC_CURRENT_OUT] = 0,
    .m[PSC_TEMPERATURE] = 1,  .R[PSC_TEMPERATURE] = 0,
};

  3. Bind to a DT compatible. Use the lowercase vendor,chip tuple Linux uses (see “DT alignment with Linux” below). Add the driver under drivers/power/regulator/ matching the existing skeleton (fan53555.c, pca9450.c).

  4. Rely on the DT binding from the Linux kernel which is imported into U-Boot under dts/upstream/Bindings/ (for PMBus chips, dts/upstream/Bindings/hwmon/pmbus/).

  5. Smoke test. With the chip wired up in DT:

    => regulator dev <name>
=> regulator value
=> regulator info

    Numbers should match the bench measurement to within the chip’s advertised LSB.

Porting an existing Linux PMBus driver to U-Boot

When the chip already has a linux/drivers/hwmon/pmbus/<chip>.c, that driver is the authoritative reference for format, coefficients, and quirks. Take what carries; leave what does not.

What carries verbatim

  • Numeric formats (format[PSC_*]).

  • DIRECT coefficients (m[], b[], R[]).

  • Per page count and per page functionality bits (pages, func[]).

  • VOUT_MODE driven per chip identify hook (e.g. MPQ8785’s switch between LINEAR16 and VID coerced DIRECT m=64 R=1).

  • Vendor register addresses for chip specific quirks (fault history, scale-loop, page mapping).

What does not carry

  • hwmon_device_register() and the attribute groups it consumes.

  • struct pmbus_data / update_lock / last_updated U-Boot has no caching layer.

  • ALERT# IRQ wiring; U-Boot is single threaded boot code.

  • Fan control hooks (read_fan_*, set_pwm_*).

  • Virtual register handling (PMBUS_VIRT_READ_VIN_* etc.); those are entirely a hwmon publication aid.

  • module_i2c_driver(...) and MODULE_* macros; U-Boot uses U_BOOT_DRIVER(...).

Worked example: porting MPQ8785

Linux’s drivers/hwmon/pmbus/mpq8785.c is 193 LOC; the U-Boot equivalent is ~150 LOC.

The mpq8785_info struct transcribes verbatim:

.pages = 1,
.format[PSC_VOLTAGE_IN]  = direct,  .m[PSC_VOLTAGE_IN]  = 4,  .R[PSC_VOLTAGE_IN]  = 1,
.format[PSC_CURRENT_OUT] = direct,  .m[PSC_CURRENT_OUT] = 16, .R[PSC_CURRENT_OUT] = 0,
.format[PSC_TEMPERATURE] = direct,  .m[PSC_TEMPERATURE] = 1,  .R[PSC_TEMPERATURE] = 0,

The VOUT format is decided at probe time from VOUT_MODE bits[7:5] : mode 0 means LINEAR16, mode 1 or 2 means DIRECT m=64 R=1 (the chip’s “VID” mode is coerced to DIRECT by the driver). Translate Linux’s mpq8785_identify() 1:1.

The per chip quirks that carry over:

  • MPS NVM string byte order: chip stores S P M for the human string MPS. pmbus_read_string() accepts a reverse_bytes flag for this case.

  • mps,vout-fb-divider-ratio-permille DT property maps to VOUT_SCALE_LOOP write at probe time.

The quirks that do not carry over:

  • The PMBUS_VIRT_* virtual sensor wiring. Drop entirely.

  • The hwmon_chip_info attribute group registration.

  • The MODULE_AUTHOR / MODULE_LICENSE declarations.

Using the generic compatible = "pmbus" driver

When a board carries a PMBus chip without a per chip U-Boot driver, the catch all drivers/power/regulator/pmbus_generic.c (Layer 3b) binds against compatible = "pmbus". It auto detects format via VOUT_MODE and PMBUS_QUERY (where the chip supports it) and provides telemetry + voltage set/get against the standard PMBus 1.x subset.

Decision tree:

  1. Try the generic driver first. Add the regulator node to the board DT with compatible = "pmbus" plus the standard regulator properties. Boot, run regulator value, compare against bench measurement.

  2. Switch to a per chip driver only when the generic one is wrong: telemetry shows wrong values (chip uses DIRECT with non default coefficients), an alert can’t be decoded (chip has vendor specific status bits), AVS is needed (the boot path has to actively trim VOUT before kernel handoff), or the chip has an ADDR-pin auto promotion / VID coercion / vendor register quirk.

DT alignment with Linux

The same .dts file should work under both U-Boot (BL33) and Linux post handoff. To make that possible:

  • Reuse the upstream Linux compatible for every PMBus chip. Look in linux/Documentation/devicetree/bindings/hwmon/pmbus/ and linux/Documentation/devicetree/bindings/regulator/. The <vendor>,<chip> tuple from the kernel binding goes into U-Boot’s of_match_table unchanged.

  • Reuse Linux property names verbatim: regulator-name, regulator-min-microvolt, regulator-max-microvolt, regulator-boot-on, regulator-always-on, mps,vout-fb-divider-ratio-permille, etc.

  • The DT binding is the kernel’s, imported under dts/upstream/Bindings/ (PMBus chips live in dts/upstream/Bindings/hwmon/pmbus/).

Multi rail/multi page chips (e.g. ISL68137 with seven outputs) declare each rail as a child regulator node with reg = <page>; each child binds as a UCLASS_REGULATOR with that PMBus PAGE setting applied at every read/write.

Common pitfalls

These have all bitten contributors during nbxv3 bring up; record them here so the next port doesn’t repeat them.

  • VOUT_MODE/DIRECT format confusion. Most generic PMBus call sites assume LINEAR16. Several MPS chips report VOUT in DIRECT format with chip specific m/b/R after a single VOUT_MODE read, the same chip read at the same address produces different numbers depending on the format the driver applies. Always read VOUT_MODE at probe time and switch the decoder accordingly. Linux’s per chip identify() callbacks document the exact rules; copy them rather than guessing.

  • SMBus block read protocol. Some I2C controllers strict check block read transactions: the master must read the length byte first, then reissue the read for the payload. Over reading a fixed length and ignoring the length byte works on lenient controllers but errors on strict ones. pmbus_read_string() does the two stage read; use it.

  • I2C bus number stability. uclass_get_device_by_seq() uses the DT alias index (i2c0 -> UCLASS_I2C seq 0) when aliases are declared, otherwise falls back to probe order which varies with which controllers are enabled in the defconfig. Always declare DT aliases for I2C buses you reference by index.

  • ADDR-pin auto addressessing. Some chips (notably MPS parts) decode their PMBus 7-bit address from an external resistor divider on ADDR_VBOOT. The “default” address in the datasheet is the factory fused slot; a board with a different divider or a die with a different revision can land in another window. If the driver hardcodes the default and the board side scan finds the chip in another window, auto promote the working address rather than failing the probe.

  • MFR string byte order. Most PMBus chips return MFR_ID characters in human order. Some MPS personalities reverse them. Pass reverse_bytes=true to pmbus_read_string() for those; spec compliant chips pass false.

References

  • Linux PMBus core: linux/drivers/hwmon/pmbus/pmbus_core.c, decoder reference; ignore the hwmon publication and caching layers.

  • Linux PMBus header: linux/drivers/hwmon/pmbus/pmbus.h; API surface reference; many constants and the struct pmbus_driver_info shape are mirrored verbatim into U-Boot’s include/pmbus.h.

  • Linux DT bindings: linux/Documentation/devicetree/bindings/hwmon/pmbus/.