Extend the upstream MC13892 driver with regulator mode and suspend support

[mcb2003]

(This was written with Codex and is frankly a mess and not entirely correct; I will rewrite this later)

Goal

Extend Linux's upstream MC13892 regulator driver so the PMIC's switcher behavior can be described and controlled through the existing regulator framework instead of board-specific register writes.

This work will begin in Paper Linux to support Kindle 3 power-management bring-up, but it should be developed toward a professional, reviewable upstream Linux patch series. This would be a strong candidate for the project's first upstream contribution, so the final design, code, bindings, commit messages and tests must meet normal kernel standards.

Current gap

Mainline drivers/regulator/mc13892-regulator.c exposes normal voltage selection for SW1-SW4, but its switcher regulator ops do not implement mode control or suspend-state programming.

The driver already defines the relevant switcher-mode registers and fields. It currently has special probe-time behavior that forces all switchers to Auto only for one exact 2.0A silicon revision signature. Other revisions generally inherit whatever mode the bootloader or previous firmware left behind.

On the Kindle 3's revision 2.1 MC13892, observed states include:

• initial mainline RAM-boot state: PWM pulse-skipping for SW1-SW4;
• stock awake state: Auto/Auto for SW2 and SW4;
• stock Wi-Fi-on state: Auto normal/off standby for SW1.

Paper Linux now safely controls SW2's normal voltage through cpufreq-dt, using Amazon's 1.275 V at 256 MHz and 1.45 V at 512 MHz. That works with the inherited mode, but it does not give Linux deliberate ownership of switcher policy, suspend behavior or the other hardware facilities represented by these registers.

Evidence and decoded stock/mainline snapshots are documented in:

• board/amazon/kindle3/power-management.md
• board/amazon/kindle3/mainline/linux-dts/nxp/imx/imx35-kindle3.dts

Hardware facilities to audit

The MC13892 switcher blocks provide more than the normal voltage selector currently used by mainline. Audit at least:

• normal operating mode for SW1-SW4;
• standby operating mode for SW1-SW4;
• normal, DVS and standby voltage slots;
• DVS transition-speed/ramp fields;
• the external DVS and standby pin semantics;
• silicon-revision restrictions and errata;
• which settings affect software voltage changes versus external-pin slot changes;
• whether any other existing regulator-framework operation maps directly and safely to MC13892 hardware.

Do not expose every register merely because it exists. Each facility should have a real regulator-framework semantic and a plausible consumer.

Preferred Linux-native design

Investigate and use existing regulator APIs wherever their semantics match, including as appropriate:

• .set_mode and .get_mode;
• .set_suspend_mode;
• .set_suspend_voltage;
• existing ramp-delay/transition-time support;
• of_map_mode plus generic regulator state constraints;
• generic Device Tree properties such as regulator allowed modes and suspend states.

The mapping between MC13892 hardware modes and Linux's REGULATOR_MODE_* values must be justified from the data sheet and regulator-framework semantics. In particular, Auto, PWM pulse-skipping, PWM no-pulse-skipping, low-power and off states must not be assigned names based only on intuition.

If DVS slots, external-pin behavior or transition-speed fields do not fit an existing generic API, first determine whether they should remain firmware-initialized, be handled internally by the driver, use an established regulator coupling mechanism, or require a narrowly designed binding/framework extension. Do not add Kindle-specific exported APIs or magic Device Tree properties as the final solution.

Compatibility requirements

An upstreamable implementation must:

• preserve existing MC13892 users unless they explicitly request a mode or suspend policy;
• avoid silently changing bootloader-provided state on unaffected revisions;
• handle shared mode registers with masked, serialized read-modify-write operations;
• support only modes genuinely available for each switcher and silicon revision;
• return standard errors for unsupported requests;
• keep board policy in Device Tree/consumers rather than the PMIC driver;
• consider whether the existing exact-revision probe-time Auto-mode override should be retained, generalized, or removed in a separate compatibility-conscious patch;
• avoid mixing Kindle-specific fixes into the upstream driver patch.

Staged implementation

1. Evidence and design

• Recheck mode encodings, standby behavior, DVS slot selection and ramp timing against the MC13892 data sheet and errata.
• Compare current mainline with NXP/Freescale and Amazon implementations, while treating old vendor APIs as evidence rather than code to copy.
• Survey comparable modern regulator drivers and binding conventions.
• Write down the proposed hardware-to-framework mode mapping before implementation.

2. Paper Linux prototype

• Implement the smallest useful generic callbacks, initially targeting deliberate SW2 mode ownership.
• Add conservative Kindle 3 constraints using standard Device Tree properties where possible.
• Provide readback/debug tooling that verifies exact masked fields without writing unrelated PMIC bits.
• Test one change at a time and retain a known-safe recovery path.

Prototype patches may be carried in Paper Linux while the design is refined, but should already avoid unnecessary board coupling.

3. Upstream-quality series

Prepare logically separated patches, likely including:

1. driver support for mode readback/control;
2. suspend voltage/mode or ramp support only where framework semantics are established;
3. binding changes only if genuinely necessary;
4. Kindle 3 DTS usage kept separate from the generic driver work.

Before submission:

• develop against current upstream Linux;
• follow kernel coding style and regulator subsystem conventions;
• run scripts/checkpatch.pl;
• build relevant configurations with warnings enabled;
• run DT schema checks for binding/DTS changes;
• use scripts/get_maintainer.pl and send the series to the regulator, MFD, Device Tree and i.MX maintainers/lists as applicable;
• include a precise cover letter and per-patch rationale;
• document hardware testing and revision details;
• respond to review by refining the generic design, not by preserving a Paper Linux shortcut.

Validation criteria

At minimum, test on the Kindle 3 MC13892 revision 2.1:

• mode readback agrees with raw masked register decoding;
• every supported mode transition reads back correctly;
• unrelated fields in shared switcher registers remain unchanged;
• SW2 remains stable at 1.275 V/256 MHz and 1.45 V/512 MHz;
• sustained load and repeated cpufreq/voltage transitions remain stable;
• idle and loaded power behavior are sensible;
• suspend configuration is not exercised until the full system suspend path and wake sources are understood;
• reboot into stock firmware shows no persistent harmful state;
• watchdog boot status and kernel logs show no regulator failures.

Where practical, seek testing on another MC13892 board or explicitly call out the lack of cross-board hardware coverage in the upstream submission.

Upstream completion criteria

This issue is complete when the generic functionality is accepted upstream, or when a submission-ready series has been reviewed locally against current mainline and any remaining upstream blocker is clearly documented. A Paper Linux-only working patch is an important milestone, but not the final definition of done.