API guide¶
How to use the driver task by task. Every call returns pf1550::Result<T>: check it before you use value.
Datasheet sections this page relies on
From NXP Semiconductors PF1550 7:
- SWx output voltage setting and DVS-done: 6.2.5 Output voltage setting in SWx, p. 28
- LDO1 and LDO3: 7.2 LDO1 and LDO3 detailed description, p. 35
- LDO load switch mode: 7.2.7 LDOy load switch mode, p. 38
- Charger operating modes: 8.1 Operating modes and behavioral description, p. 43
- Charger input source detection: 8.2 Charger input source detection, p. 45
- Charger state diagram: 8.4 Charger state diagram, p. 46
- Charger faults and restart: 8.9 Fault states, p. 64
- Charger watchdog: 8.9.2 Watchdog timer state, p. 65
- PWRON: 9.1 PWRON, p. 68
- STANDBY pin: 9.2 STANDBY, p. 69
- RESETBMCU: 9.3 RESETBMCU, p. 69
- INTB and the interrupt registers: 9.4 INTB, p. 70
- ONKEY: 9.6 ONKEY, p. 71
- State machine and transitions: 10 PF1550 state machine, p. 72
- System ON, OFF, SHIP and CORE_OFF: 10.2 System OFF states, p. 74
- Regulator power-up sequencer: 10.6 Regulator power-up sequencer, p. 77
- Regulator power-down sequencer: 10.7 Regulator power-down sequencer, p. 78
- Device start-up timing and pre-programmed options: 11 Device start up, p. 78
- Device ID, silicon revision and OTP flavour: 12.1 Specific PMIC Registers (Offset is 0x00), p. 80
All of them, with the driver API for each: Datasheet map.
The shape of the API¶
| Group | Calls | Writes the chip |
|---|---|---|
| Lifecycle | EnsureInitialized(), IsInitialized(), GetConfig(), Configure() |
Configure() only |
| Identity and state | ReadVariant(), ReadPowerState(), ReadSnapshot(), SelfCheck(), CheckChargerAgainstLimits() |
no |
| Charger | ReadChargerStatus(), SetChargerMode(), RestartCharger(), ServiceChargerWatchdog() |
yes |
| Rails | ReadRail(), SetRailModes(), SetRailVoltage(), EnableLoadSwitch() |
yes, except ReadRail() |
| Power states | RequestStandby(), EnterShip(), EnterCoreOff(), CancelShutdownRequest(), ReadPowerDownSequence(), SetPowerDownSequence() |
yes, except the read |
| Interrupts | SetIrqMask(), ReadCategories(), ReadSense(), ServiceInterrupts(), GetLatchedEvents(), ClearLatchedEvents(), IntbAsserted() |
masks and clears only |
| Bench | ReadRegister() |
no, read only |
- There is no raw register write.
ReadRegister()reads one documented register for bench work and writes nothing. The settings are typed (Configand its blocks), checked against the datasheet grids and yourLimits, and every register written is read back (Contract). - Dangerous calls need a token.
EnterShip(ShipConfirm{}),EnterCoreOff(CoreOffConfirm{})andEnableLoadSwitch(rail, LoadSwitchConfirm{.input_mv = 1800})take a struct that you write out, so the call site says what it does; the load switch token carries the input voltage of the LDO, which the driver checks againstLimits. - Time is yours: the driver has no timer. The one wait it makes is bounded and goes through
DelayUs().
Initialise and configure¶
pf1550::Error Start(Pmic& pmic) {
if (auto r = pmic.EnsureInitialized(); !r) { // validates, identifies, checks the charger as found
return r.error;
}
return pmic.Configure().error; // writes the blocks whose `apply` is true, charger last
}
EnsureInitialized() validates the stored Config, checks DEVICE_ID, checks your DVS declarations against Table 85
and reads the charger as found. It writes nothing, except that when AsFoundPolicy::MakeSafe is set and an unsafe
charge is found on, one write that puts the charger in linear-only mode. A start-up that fails on an unsafe charger
leaves the driver uninitialised, but SetChargerMode(Off) still works. Configure() writes every block whose apply
flag is true, in this order: the rails (in Config::rail_order), VSNVS, the coin cell, USBPHY, the LED, power
control, the power-down order, the interrupt masks and, last, the charger. A block with apply = false is left as the
chip holds it.
The driver does not know the chip's OTP option. Read it with ReadVariant() and decide what your board needs:
const auto v = pmic.ReadVariant();
// v.value.option is Option::A1 .. A9, A0 (not programmed) or Unknown; v.value.flavor_raw is always the raw byte.
Charge¶
The charger is parked before it is changed and is switched on only by the mode, written last. A configuration with
charger.mode = ChargerMode::Charge writes the parameters in linear-only mode and enables charging at the end, unless
the charger reports a fault (ChargerFault: the parameters are written, charging is not enabled).
pf1550::Error WatchCharger(Pmic& pmic) {
const auto s = pmic.ReadChargerStatus();
if (!s) {
return s.error;
}
if (s.value.fault == pf1550::Fault::TimerFault) {
return pmic.RestartCharger().error; // off, then on; at most three tries in a row
}
return pmic.ServiceChargerWatchdog().error; // every 16 s or less when the watchdog is on
}
ReadChargerStatus()makes four reads: VBUS_SNS, CHG_SNS, BATT_SNS and CHG_SNS again (consistentsays the two CHG_SNS reads agree).faultis classified:None,TimerFault,ThermistorSuspend,ThermalShutdown,BatteryOvervoltage,BatteryOvercurrent,WatchdogExpired,BatteryMissingorUnknownState. The reads are not atomic with each other (ambiguity C27).SetChargerMode(Off)andLinearOnlyare allowed as soon as DEVICE_ID has passed, even after a failed start-up.Chargechecks the charger's registers againstLimitsand the acknowledgements first, so a charge that was configured outside your limits by something else (a start-up option, another master) is refused withOutOfLimitsorUnsafe.RestartCharger()leaves a latched fault state: off, verify, charge. Three attempts in a row without the charger reaching a charging state returnRefused: find the cause (a cold or hot battery, a timer, a shorted cell).- With
watchdog.enablecallServiceChargerWatchdog()at least every 16 s. The datasheet reads 80 s or 32 s with 20 % accuracy; 16 s covers every reading. The call reads BATFET_CNFG until two reads agree and refuses withUnsafeif the battery overcurrent protection reads as off withoutallow_batfet_oc_off: a stuck line reads zero. Whether WDTCLR holds what is written is open (C58); the driver writes it as an edge either way. - The input limit check does not need
watchdog.enable: a cable removal puts VBUS_LIN_ILIM back to its OTP value (Table 163). With the charger in Charge (or LinearOnly, when the charger block is applied)ReadChargerStatus(),ServiceInterrupts()(when a charger interrupt is set) andServiceChargerWatchdog()all read the limit. A limit that is not the configured one is written again once VBUSIN is valid (while it is invalid the field is held in reset and nothing is written;SelfCheck()reportsinput_limit_okfalse). A limit aboveLimitsthat cannot be restored (the charger block is not applied) switches the charger off and returnsOutOfLimits. A failed check returns its error and not the status: an application that needs the status regardless callsReadSnapshot(), which reads it without the check. The check is not written over a chip that reset meanwhile (DeviceReset), and a charger interrupt thatServiceInterrupts()read owes the check until one has passed: a call that fails after the status byte was read (a later pass, the clear write), or aClearLatchedEvents()in between, does not drop it, and the next call makes it again.
Rails¶
pf1550::Error Rails(Pmic& pmic) {
if (auto r = pmic.SetRailVoltage(pf1550::Rail::Ldo1, pf1550::FromMillivolts(2800)); !r) {
return r.error; // OutOfLimits when your Limits window does not allow it
}
return pmic.SetRailModes(pf1550::Rail::Ldo1, {true, true, false, false}).error;
}
- Every rail needs a window in
Limits::rail[...];SetRailVoltage()andSetRailModes()returnOutOfLimitsfor a rail without one or a voltage outside it. - SW1 and SW2: the run voltage can be written only when you declared
Dvs::EnabledinBuckConfig::dvs; otherwiseReadOnlyRail. The standby and sleep voltages are set inConfigure()throughstandby_uvandsleep_uv. After a change of the run voltage of an enabled rail the call waits for the DVS-done flag (at most 256 us) and returnsTimeoutif it does not rise. - SW3's voltage is read only (ambiguity C2):
SetRailVoltage(Rail::Sw3, ...)returnsReadOnlyRail. SetRailModes()sets EN, STBY_EN, OMODE and LPWR. Low-power mode (low_power) needsack.load_below_10ma: the datasheet specifies it for loads up to 10 mA.EnableLoadSwitch(Rail::Ldo1 or Ldo3, LoadSwitchConfirm{.input_mv})is irreversible. It turns an LDO into a switch: the output is the input voltage, with no current limit, and it cannot be undone until the next power cycle (LS_EN 1 to 0 is not allowed).input_mvis the voltage of the rail that feeds the LDO; it must lie inside the rail'sLimitswindow, and the rail must not be in low-power mode (Refused).- An enable (
SetRailModes(), or a block inConfigure()) first reads the voltage registers it brings into effect and checks them againstLimits(OutOfLimits): a rail never comes on at a voltage the load does not tolerate. Standby and sleep need run (InvalidArgumentotherwise): EN gates both (Table 42). ReadRail()reports the enables, the load-switch flag and the programmed run voltage, decoded in the DVS mode the part has (Table 85 for A1 to A3, else your declaration).
Power states¶
ReadPowerState()decodes STATE_INFO:Wait,Run,Standby,Sleep,RegsDisable, orUnknown(SHIP and CORE_OFF have no I2C-visible state because the chip is not powered, ambiguity C36).RequestStandby(bool)drives the STANDBY pin through yourGpioSet();Unsupportedwithout it.EnterShip()andEnterCoreOff()are guarded:
pf1550::Error ShipMode(Pmic& pmic) {
// Cuts every supply, VSNVS included; recovery is a charger or a battery attach.
return pmic.EnterShip(pf1550::ShipConfirm{}).error;
}
EnterShip() returns Refused unless the chip is in Run, Standby or Sleep and VBUS reads invalid and below UVLO.
Everything is cut, VSNVS included; recovery is a charger or a battery attach. The chip enters SHIP only with VBUSIN
below 1.0 V, which the driver cannot measure (ambiguity C6): with VBUSIN between 1 V and UVLO it ends in
REGS_DISABLE. EnterCoreOff() needs VBUS invalid and ONKEY not pushed, and arms GOTO_CORE_OFF: it takes effect
at the next REGS_DISABLE, not at once. Both requests stay set in PWRCTRL3 until CancelShutdownRequest() clears
them; call it when the request is no longer wanted. It is not refused after DEVICE_ID has passed.
- ReadPowerDownSequence() and SetPowerDownSequence() read and write the seven *_PWRDN_SEQ registers. The order
decides which supply drops first, and a wrong order can damage a processor: the write needs
ack.power_down_order_reviewed. All zero bypasses the sequencer (section 10.7).
The sequencer¶
The power-up order is fixed by OTP and cannot be read back over I2C, so the driver reports it only for the
pre-programmed options A1 to A9 that Table 85 lists. The helpers are constexpr and have no I/O:
void Sequencer() {
// Table 85: the start-up order of option A4 and when each rail turns on (microseconds).
const auto profile = pf1550::StartupProfileOf(pf1550::Option::A4);
if (profile) {
const uint32_t ldo1_us = pf1550::PowerUpDelayUs(profile.value, pf1550::Rail::Ldo1);
const uint32_t total_us = pf1550::PowerUpDurationUs(profile.value);
std::printf("LDO1 at %u us of %u us\n", static_cast<unsigned>(ldo1_us),
static_cast<unsigned>(total_us));
}
}
| Helper | Gives |
|---|---|
StartupProfileOf(Option) |
The PWRUP_SEQ order of each rail, the slot length (500 us for A1, else 2000 us) and whether PWRON is edge sensitive (A8); InvalidArgument for A0 and Unknown |
PowerUpDelayUs(), PowerUpDurationUs() |
When a rail starts, and when the last one does, from the start of the first slot |
ResetReleaseDelayMs(), ColdStartToResetReleaseUs() |
RESETBMCU's delay from POR_DLY (code 1 is undefined) and the whole cold-start time to its release |
PowerDownDelayUs(), PowerDownDurationUs(), IsPowerDownBypassed() |
The power-down schedule of a PowerDownSequence: (highest - own) steps of 2 ms |
MirrorOf(profile) |
The power-down order the registers hold after reset (section 10.7: it mirrors the power-up order) |
Where the datasheet is silent the readings are C54 to C56 in Ambiguities.
Interrupts¶
pf1550::Error OnIntb(Pmic& pmic) {
const auto e = pmic.ServiceInterrupts(); // reads, copies out, clears
if (!e) {
return e.error;
}
if (pf1550::Has(e.value, pf1550::IrqSource::Onkey3s)) {
std::printf("ONKEY held for 3 s\n");
}
return e.value.fault_class ? pf1550::Error::DeviceFault : pf1550::Error::Ok;
}
- 31 sources in 8 groups (
IrqGroup): charger, SW low side, SW high side, SW DVS, LDO, temperature, ONKEY and miscellaneous.Has(events, IrqSource::X)tests one;IsFaultSource()andfault_classmark rail, die and system-overvoltage faults. - A source is masked by default (
IrqMask{}masks all).Config::apply_irq_maskwritesConfig::irq_mask;UnmaskOnly(std::array{...})builds one from a list of sources. A masked source still sets its status bit, but does not drive INTB. ServiceInterrupts()copies each status byte out before it clears it (read-then-clear, at most three passes). Its result holds the bytes as read, plus the status bits that other calls read in the meantime (the driver latches them;GetLatchedEvents()shows them). WithGpioGet(), INTB high, every source unmasked throughSetIrqMask()and an empty latch it returns at once without a transfer; otherwise it reads the chip. PWRUP_I is reported like any other event (it is the standby wake-up flag, not a reset flag).ReadCategories()andReadSense()are the live views (not latched): use them to poll without clearing.- A DVS step that the driver waits for (
SetRailVoltage(),Configure()of SW1 or SW2) reads SW_INT_STAT2 and clears the awaited rail's DVS-done bit, so that rail's own event is consumed by the wait and never reaches the latch; the other rail's bit is kept in the latch. UseReadSense(IrqGroup::SwDvs)to watch DVS done without consuming it.
Diagnostics¶
ReadSnapshot()reads about 60 registers: identity, state, the charger, every sense register, the rails, the power-down order andPOR_DLY. It is for logs and bring-up, not for a control loop.SelfCheck()answers four questions without writing: DEVICE_ID, state Run, every configured rail enabled as configured, and no latched fault.CheckChargerAgainstLimits()repeats the as-found check at any time.
Handle errors¶
const char* Explain(pf1550::Error e) {
switch (e) {
case pf1550::Error::OutOfLimits:
return "the value is valid for the chip but outside your Limits";
case pf1550::Error::Unsafe:
return "a safety downgrade needs its Acknowledgements flag";
case pf1550::Error::Refused:
return "a precondition of a dangerous call is not met";
case pf1550::Error::NoDevice:
return "nothing acknowledged the address";
default:
return pf1550::ToString(e);
}
}
| Error | Usually means | Do |
|---|---|---|
NotInitialized |
EnsureInitialized() has not succeeded |
Call it, and check its error |
InvalidArgument |
Off the grid, reserved, or Limits unset |
Fix the value; nothing was sent |
OutOfLimits |
Valid for the chip, outside your Limits |
Fix the value or, if the hardware allows it, the limit |
Unsafe |
A downgrade without its acknowledgement | Set the flag in Config::ack only if you mean it |
ReadOnlyRail |
SW3, or a buck not declared DVS | Declare Dvs::Enabled if the OTP says so |
Refused |
A precondition of SHIP, CORE_OFF or a restart limit | Read the state with ReadPowerState() and ReadChargerStatus() |
ChargerFault |
The charger reports a fault | Read ReadChargerStatus(); RestartCharger() after the cause is gone |
VerifyFailed |
A register read back differently, or a read that is not stable or reads all ones | Retry once; if it repeats, suspect a noisy line, a reset or another master |
DeviceReset |
A register the driver changed is back at its start-up value: the chip reset | EnsureInitialized() and Configure(), see Troubleshooting |
Timeout |
DVS-done did not rise | Check the load and the rail's enable; the step may be slow under a heavy load |
NoDevice |
Nothing acknowledged the address | Power, SDA, SCL, the address (Troubleshooting) |
Bus, DeviceIdMismatch |
A bus fault; another chip | Troubleshooting |
Unsupported |
An optional hook is missing | Add GpioSet() or GpioGet() to your port |
Shut down¶
There is no Deinitialize(): the chip is a supply, and the driver never switches it off. To stop using it, drop the
object. Use RequestStandby(), EnterShip() or EnterCoreOff() to change the chip's own state.