RFC: Full M5Stack M5PM1 PMIC support (MFD + regulator + GPIO + charger + fuel-gauge)

[thc1006]

RFC: Full M5Stack M5PM1 PMIC support (MFD + regulator + GPIO + charger + fuel-gauge)

Introduction

The M5Stack StickS3 board port currently ships a minimal M5PM1 driver
(m5stack,m5pm1-l3b-regulator) that only switches one rail (PYG2 / "L3B") to power
the LCD. The M5PM1 is a full PMIC; this RFC proposes the complete, idiomatic
Zephyr support.

Problem description

The minimal regulator models a single GPIO-switched rail. The chip also provides
battery charging, fuel-gauge/ADC telemetry, 5 multi-function GPIOs (PYG0-PYG4),
a 5V boost rail, watchdog, RTC RAM, NeoPixel and a wake/timer engine. None of
these are exposed, so StickS3 power management, charging, the speaker-amp enable
(PYG3) and the BMI270 interrupt (PYG4) cannot be used.

Proposed change

Refactor into the conventional Zephyr multi-driver PMIC layout (cf. AXP192/
AXP2101, AW9523B):

• drivers/mfd/ — m5stack,m5pm1 I2C MFD parent (device-id check, I2C-CFG
  idle-sleep handling, shared register lock).
• drivers/gpio/ — m5stack,m5pm1-gpio GPIO controller for PYG0-PYG4. The LCD
  rail then becomes a standard regulator-fixed with enable-gpios.
• drivers/charger/ — m5stack,m5pm1-charger via the Zephyr charger API
  (charger_get_prop/set_prop): charge current/voltage limits, status, TS.
• drivers/fuel_gauge/ (or sensor) — battery V/I/SOC via the ADC registers.
• drivers/regulator/ — keep/rework rail control on top of the GPIO controller.

Detailed RFC

• Register map and reset defaults are documented (datasheet + M5GFX source,
  see docs/09_SOURCES.md). I2C 0x6E; DEVICE_ID@0x00 = 0x50.
• Init priority: MFD < GPIO < regulator < consumers (display).
• Shared register access must be serialized at the MFD level once multiple
  function drivers exist (the current single regulator relies on the regulator
  core's per-device mutex; that is insufficient cross-driver).
• Li-ion safety (see issue: charger): do NOT change charge-voltage/TS defaults
  without bench validation.

Dependencies

Blocks full power-management, audio (PYG3 amp enable), and BMI270 interrupts
(PYG4). Should land before deep-sleep / low-power work.

Concerns and unresolved questions

• Single-rail regulator vs full MFD modeling — maintainer guidance wanted.
• Whether charger belongs in charger subsystem vs a custom binding.

Acceptance criteria

• MFD + GPIO controller + at least one regulator-fixed rail build and pass an
  emulator-backed ztest on native_sim.
• Hardware: rails toggle, charge status reads back, battery V/I sane.

References

• docs/00_RESEARCH_SNAPSHOT_UPDATED.md, docs/09_SOURCES.md
• https://github.com/m5stack/M5PM1 (datasheet + register map)
• Zephyr AXP2101 driver set (reference pattern)

[thc1006]

Spike finding (2026-06-01) that reframes this RFC's scope.

I dug the full M5PM1 register map (official m5stack/M5PM1 src/M5PM1.h regs
0x00-0xBF, the datasheet, Zephyr PR #109961's scope, and Espressif's own StickS3
power_manager.c -- four independent sources). The M5PM1 ADC exposes VOLTAGES ONLY:
VREF (0x20), VBAT (0x22), VIN (0x24), 5VINOUT (0x26), plus an internal temperature
and two GPIO analog inputs. There is NO battery-current, charge-current,
coulomb-counter or state-of-charge register anywhere in the map.

Consequences for this RFC:

• The "fuel-gauge (battery V/I/SOC)" item is not implementable on this silicon.
  Only battery VOLTAGE is available; an SoC would be a host-side estimate, not a
  measurement.
• The on-device current + per-state current dataset migrated here from M5StickS3: on-device power measurement via M5PM1 ADC #4 is not
  obtainable on-device (only an external USB meter, coarse/whole-board, or a
  VBAT-based estimate).
• What the chip really exposes for power: charge-enable (PWR_CFG 0x06 bit0),
  battery low-voltage cutoff (BATT_LVP 0x08), power-source readback (PWR_SRC 0x04:
  5VIN/5VINOUT/BAT) and battery insert/remove IRQs (0x41).

So the remaining "full PMIC" surface worth doing is MFD + GPIO + regulator (all
already in PR #109961, pending merge) plus a small charge-enable/power-source/
status add-on. The fuel-gauge part should be dropped. Keeping this open as the
tracking RFC for that reduced scope.

[kartben]

for the fuel gauge I recommend you check the latest update to the PaperColor PR with the added composite fuel-gauge :)

[thc1006]

Concrete next step for the battery side of this RFC, now that the schematic is confirmed (V0.6):

The charger is an LGS4056 (about 190 mA charge current) with AW32901 input protection; CHG_EN / CHG_STAT are routed through the M5PM1. The M5PM1 exposes voltage ADCs only (VBAT / VIN / 5VInOut / Vref). There is no charge-current, coulomb counter or state-of-charge register, so a true coulomb-counted fuel gauge is not possible on this silicon.

Achievable and actionable:

• State-of-charge percentage via zephyr,fuel-gauge-composite (VBAT plus an OCV curve), the same approach as Zephyr PR #109961. This gives a usable battery percent for the LCD without coulomb counting.
• Charge enable / charge status (CHG_EN / CHG_STAT) exposed through the M5PM1 driver.
• Power source readout (register 0x04 PWR_SRC: 5VIN / 5VINOUT / BAT) and battery insert/remove events (register 0x41).

Coordinate with PR #109961 (M5PM1 MFD upstream) rather than adding a competing driver. Coulomb-counted current stays out of scope (hardware limit, also see closed #4).