.. SPDX-License-Identifier: GPL-2.0-only
.. Copyright (c) 2026 Free Mobile - Vincent Jardin <vjardin@free.fr>

Kernel driver mpq8646
=====================

Supported chips:

  * MPS MPQ8646

    Prefix: 'mpq8646'

Author:
  - Vincent Jardin <vjardin@free.fr>

Chip-identity
-------------

Support the boards that are designed with the MPS MPQ8646 probed thanks
to``MFR_MODEL`` register.

This driver targets the MPQ8646 silicon specifically.

Description
-----------

The MPQ8646 is a fully integrated, PMBus-compatible, high-frequency,
synchronous buck converter. It offers a compact solution that
achieves up high Amps output current per phase, with excellent load
and line regulation over a wide input supply range. The chip
operates at high efficiency over a wide output current load range.

The PMBus interface provides converter configurations and key
parameters monitoring.

The device adopts MPS's proprietary multi-phase digital
constant-on-time (MCOT) control, which provides fast transient
response and eases loop stabilization. The MCOT scheme also allows
multiple devices or channels to be connected in parallel with
excellent current sharing and phase interleaving for high-current
applications.

Fully integrated protection features include over-current
protection (OCP), over-voltage protection (OVP), under-voltage
protection (UVP), and over-temperature protection (OTP).

This device is compliant with:

- PMBus rev 1.3 interface.

The driver exports the following attributes via the 'sysfs' files
for input voltage:

- in1_input
- in1_label
- in1_max
- in1_max_alarm
- in1_min
- in1_min_alarm
- in1_crit
- in1_crit_alarm

The driver provides the following attributes for output voltage:

- in2_input
- in2_label
- in2_alarm
- in2_max
- in2_max_alarm
- in2_min
- in2_min_alarm
- in2_crit
- in2_crit_alarm
- in2_lcrit
- in2_lcrit_alarm

The driver provides the following attributes for output current:

- curr1_input
- curr1_label
- curr1_max
- curr1_max_alarm
- curr1_crit
- curr1_crit_alarm

The driver provides the following attributes for temperature:

- temp1_input
- temp1_max
- temp1_max_alarm
- temp1_crit
- temp1_crit_alarm

Alarm acknowledgment
---------------------

The hwmon-class ``inX_alarm``/``currX_alarm``/``tempX_alarm`` files are
read-only in pmbus_core. The driver exposes the standard
``PMBUS_VIRT_RESET_*_HISTORY`` virtual-register channel for fault
acknowledgment: writing ``1`` to ``inX_reset_history`` /
``currX_reset_history`` / ``tempX_reset_history`` sends the chip a
``CLEAR_FAULTS`` (0x03) Send-Byte, which clears the latched
``STATUS_WORD`` / ``STATUS_VOUT`` / ``STATUS_IOUT`` /
``STATUS_INPUT`` / ``STATUS_TEMPERATURE`` bits the chip is currently
exposing.

The MPS-specific NVM post-mortem register
``PROTECTION_LAST`` (0xFB) is not cleared by this path; it can be read
(decoded) via the ``protection_last`` debugfs entry described below.

Regulator framework integration
-------------------------------

When ``CONFIG_REGULATOR=y`` is set, the chip is
exposed under ``/sys/class/regulator/`` and accepts the standard
regulator framework operations:

- ``regulator_enable()`` / ``regulator_disable()`` -> ``OPERATION`` (0x01)
- ``regulator_set_voltage()`` -> ``VOUT_COMMAND`` (0x21)
- ``regulator_get_voltage()`` -> ``READ_VOUT`` (0x8B)
- ``regulator_is_enabled()`` -> ``OPERATION`` bit-decode

The single regulator descriptor is named ``"vout"`` (page 0). For a
multi-page configuration the descriptor table can be extended in
the driver.

In-driver alarm-poll fallback
-----------------------------

On boards where the chip's ``SMBALERT#`` pin is unavailable to the
SoC, ``pmbus_core::pmbus_irq_setup`` cannot deliver SMBALERT-driven
``poll(POLLPRI)`` wakes or ``udev change@...`` events on the
``inX_alarm`` files. The driver provides a ``delayed_work``-based
polling fallback that
periodically invokes the pmbus core fault check,
``pmbus_check_and_notify_faults()``, which sends the notifications and
then clears the latched faults, exactly like the ``SMBALERT#``
interrupt path. The frequency of polling is tunable:

::

  /sys/kernel/debug/i2c/i2c-<bus>/<bus>-<addr>/alarm_poll_interval_ms

The default is 1000 ms.

Set it to 0 to disable. The worker self-suppresses
when ``client->irq != 0`` (i.e. when DT supplies an
``interrupts = <...>``  property on the regulator node), so adding
``SMBALERT#`` wiring is a zero-driver-change uplift on a future
board rev.

MPS post-mortem (PROTECTION_LAST)
---------------------------------

The MPQ8646 silicon keeps a single 16-bit NVM-backed record of the
last protection event in ``PROTECTION_LAST`` (0xFB). It survives
chip power/reset. The following debugfs entries expose it:

::

  /sys/kernel/debug/i2c/i2c-<bus>/<bus>-<addr>/protection_last     (RO)
  /sys/kernel/debug/i2c/i2c-<bus>/<bus>-<addr>/status_decoded      (RO)

``protection_last`` decodes the 16-bit value based on the datasheet
fault names (``INIT_FAULT``, ``NVM_CRC_ERROR``, ``NVM_FAULT``,
``OC_PHASE_FAULT``, ``OTP_SELF_FAULT``, ``SWITCH_PRD_FAULT``,
``VIN_OV_FAULT``, ``VOUT_OV_FAULT``, ``VOUT_UV_FAULT``,
``OC_TOT_FAULT``, ``VIN_UVLO_FAULT``, ``DRMOS_OTP``).

``status_decoded`` reads ``STATUS_WORD`` (0x79) and renders the
16 bits with MPS-extension labels (bit12 = ``NVM_SUMMARY``,
bit8 = ``WATCH_DOG``, bit0 = ``DRMOS_FAULT``) instead of the
PMBus 1.3 spec generic names.

NVMEM snapshot
--------------

When ``CONFIG_NVMEM=y`` is set, the chip's NVM-backed
observability registers are exposed as a single 16-byte read-only
``nvmem_device`` at ``/sys/bus/nvmem/devices/<i2c-name>/nvmem``.
Layout (little-endian for 16-bit fields, zero-fill on per-entry read
failure and for the reserved tail):

::

  offset 0..1   PROTECTION_LAST  (0xFB)  word
  offset 2..3   MFR_RETRY_TIMES  (0xF4)  word
  offset 4..5   MFR_CONFIG_ID    (0xC0)  word
  offset 6..7   MFR_VBOOT_CFG    (0xFC)  word
  offset 8      MFR_SILICON_REV  (0xC3)  byte
  offset 9..15  reserved (zero)

Suitable for single-``cat`` post-mortem capture by a fleet daemon.

Diagnostics and introspection
-----------------------------

When ``CONFIG_DEBUG_FS=y`` is set, the driver adds a read-only
decode surface to the client's pmbus debugfs directory,
``/sys/kernel/debug/i2c/i2c-<bus>/<bus>-<addr>/``.
The driver intentionally exposes no raw register poke/peek debugfs;
use i2c-dev (``i2cget``/``i2cset``/``i2ctransfer``) for that.

Identity / observability (read-only):

==========================  ==================  =================================
File                        PMBus / MFR cmd     Description
==========================  ==================  =================================
``mfr_config_id``           0xC0 (word)         board / SKU NVM identifier
``mfr_config_code_rev``     0xC1 (word)         NVM image revision (PART_RECOG +
                                                config code rev fields)
``mfr_silicon_rev``         0xC3 (byte)         die revision
``mfr_retry_times``         0xF4 (word)         per-fault-class recovery-mode
                                                configuration (NOT a retry
                                                count). Four 4-bit fields
                                                [15:12]=OTP, [11:8]=VOUT_OV,
                                                [7:4]=VOUT_UV, [3:0]=OCP.
                                                Each field: 0x0=latch-off,
                                                0x1..0xE=retry N times then
                                                latch off, 0xF=hiccup
                                                (retry indefinitely). The
                                                chip exposes no in-NVM
                                                retry-event counter; track
                                                transitions externally if
                                                needed (poll
                                                ``protection_last`` or watch
                                                ``inX_alarm`` / ``temp1_alarm``
                                                ``poll(POLLPRI)`` wakes).
``mfr_vboot_cfg``           0xFC (word)         ADDR/VBOOT latched at POR
==========================  ==================  =================================

Timing / UVLO knobs (read-only):

==========================  ==================  =================================
File                        PMBus cmd           Description
==========================  ==================  =================================
``vin_on``                  0x35 (word)         UVLO turn-on threshold
``vin_off``                 0x36 (word)         UVLO turn-off threshold
``ton_delay``               0x60 (word)         soft-start delay
``ton_rise``                0x61 (word)         soft-start ramp time
``toff_delay``              0x64 (word)         soft-stop delay
``toff_fall``               0x65 (word)         soft-stop ramp time
==========================  ==================  =================================

The only writable entry is ``alarm_poll_interval_ms`` (the alarm-poll
worker cadence, see above), it is driver-local and never touches the
chip.

Unsafe provisioning
-------------------

Available only when ``CONFIG_SENSORS_MPQ8646_DEBUG_UNSAFE=y``
(``default n``, it is for boards bring up only). They WRITE to the regulator.
On many designs the MPQ8646 powers the main CPU core rail, so a wrong write can
brown out the board or persist a bad setpoint into finite-cycle NVM.
WARNING: Some wrong register writes can and likely will physically damage or
destroy the chip and/or the board. An explicit warning banner is printed at probe
time when this option is enabled.

===============================  ===============  =========================================================
File                             PMBus / MFR cmd  Description
===============================  ===============  =========================================================
``store_all``                    0x15             STORE_USER_ALL Send-Byte (commit RAM config to NVM)
``restore_all``                  0x16             RESTORE_USER_ALL Send-Byte (revert RAM to last-NVM image)
``clear_protection_last``        0x08             CLEAR_LAST_FAULT Send-Byte
``clear_protection_last_force``  --               gated CLEAR_LAST_FAULT, see below
``on_off_config``                0x02 (byte)      PMBus vs CTRL-pin on/off source + active polarity
``vout_margin_high``             0x25 (word)      margin-high VOUT setpoint
``vout_margin_low``              0x26 (word)      margin-low VOUT setpoint
``mfr_pmbus_lock``               0xEE (word)      programmable PMBus write-lock
``mfr_product_rev_user``         0xC2 (word)      user-programmable product revision
===============================  ===============  =========================================================

``clear_protection_last`` writes ``CLEAR_LAST_FAULT`` (0x08) Send-Byte.
The chip silently no-ops unless ``MFR_CFG_EXT`` (0xF5) bit[6] is set.

``clear_protection_last_force`` performs the unlock with the following
six-step dancing:

1. read ``WRITE_PROTECT`` (0x10) and ``MFR_CFG_EXT`` (0xF5) for restore
2. clear ``WRITE_PROTECT`` if set
3. set ``MFR_CFG_EXT`` bit[6] = 1, preserving other bits
4. send ``CLEAR_LAST_FAULT`` (0x08)
5. restore ``MFR_CFG_EXT`` (with retry to handle the chip's
   undocumented post-NVM-write busy window)
6. restore ``WRITE_PROTECT``

Devicetree
----------

The driver uses ``compatible = "mps,mpq8646"``. There are some few optional
properties:

- ``mps,vout-fb-divider-ratio-permille`` : it writes ``VOUT_SCALE_LOOP``
  (0x29) at probe to compensate for an external resistor divider in
  the VOUT feedback path. The valid range is 11-bit.
- ``interrupts = <...>`` : if the board routes the chip's
  ``SMBALERT#`` pin to a SoC GPIO, declaring it here lights up
  ``pmbus_core::pmbus_irq_setup`` and disables the in-driver
  alarm-poll fallback