Contract¶
What the PF1550 driver promises, what it needs, and the rules a caller follows.
The driver inherits the Kokeb Labs driver contract; this page states only what is specific to it. A change to anything here is a breaking change, listed under Breaking in the changelog.
Datasheet sections this page relies on
From NXP Semiconductors PF1550 7:
- Electrical limits and supply ranges: 5.3 Electrical characteristics, p. 12
- SW1 and SW2: DVS and non-DVS operation: 6.2.2 SWx DVS and non-DVS operation, p. 26
- LDO load switch mode: 7.2.7 LDOy load switch mode, p. 38
- Battery overcurrent limit and BATFET: 8.9.6 Battery overcurrent limit, p. 66
- System ON, OFF, SHIP and CORE_OFF: 10.2 System OFF states, p. 74
- State transition conditions (Table 83): 10.5 State diagram and transition conditions, p. 76
- Regulator power-down sequencer: 10.7 Regulator power-down sequencer, p. 78
- Register map and access types: 12 Register map, p. 80
- Register OTP bitmap: 12.5 Register OTP bitmap, p. 128
All of them, with the driver API for each: Datasheet map.
Promises¶
Lifecycle¶
- The constructor is
noexcept, stores the configuration, does no I/O and cannot fail. EnsureInitialized()is the only way to start the driver. It validates the storedConfigfirst (InvalidArgument,OutOfLimitsorUnsafe, nothing sent), brings the bus up, checks that DEVICE_ID reads0x7C, checks your DVS declaration against Table 85 and checks the charger as found against yourLimits. Once it has succeeded, later calls returnOkwith no I/O. After a failure the driver stays uninitialised and the call can be repeated.- Every call that touches the chip returns
Error::NotInitializedbeforeEnsureInitialized()succeeds, and sends nothing. No call starts or resets the chip as a side effect. Some calls work as soon as DEVICE_ID has passed, even when start-up then failed (an unsafe charger found on, for example):SetChargerMode(Off)orLinearOnly,SetRailModes()with every state off, the off step ofRestartCharger(),CheckChargerAgainstLimits()andCancelShutdownRequest(). An unsafe charger can always be switched off. - The chip can reset in the middle of a session (UVDET, a watchdog, a REGS_DISABLE pulse): it then starts in its OTP
state, which may be a charger on with no timer, and the driver's
Configure()is gone. The datasheet defines no reset flag (PWRUP_I is the STANDBY or SLEEP to RUN completion flag, Table 108, ambiguity C59), so the driver remembers the bits it changed and verified (at most four registers, the newest ones) and every call that switches something on or changes the chip reads those registers first (up to four extra reads); a difference twice in a row returnsDeviceReset, writes nothing, and leaves the driver uninitialised untilEnsureInitialized()andConfigure()run again.SelfCheck()reports it the same way, andConfigure()looks once more before it writes the charger block. A rail the driver switched off is remembered as off, so a reset that brings it back on is seen. A reset that leaves every bit the driver wrote at its start-up value is not seen, and does no harm; a reset in the middle of a call that writes several registers is seen by the next check, not by the writes in between.EnsureInitialized()on a driver that already is initialised returns at once and checks nothing: to look for a reset, callSelfCheck(). - A cable removal is not a chip reset.
VBUS_LIN_ILIMgoes back to its OTP value when VBUSIN becomes invalid (Table 163, reset condition CHGPOK_RSTB, ambiguity C14), so it is never kept as evidence of a reset. The charger keeps its mode through a cable removal, so a charger that was charging goes on charging at the OTP limit until the next watchdog service:ServiceChargerWatchdog()reads the limit while the charger is in Charge, writes the configured one again when the charger block is applied (a warning is logged), and otherwise switches the charger off and returnsOutOfLimitswhen the limit is aboveLimits.input_max_ma.SelfCheck()reports it asinput_limit_ok. Service the watchdog at least everykWatchdogServiceMaxSseconds (16 s) to bound that window. A charge start refused withOutOfLimitsorUnsafeleaves the charger off, also when it was found charging. - A switch-off is never refused for a reset report or a failed re-start:
SetRailModes()with every state off,SetChargerMode(Off or LinearOnly), the off step ofRestartCharger()andCancelShutdownRequest()need only a chip that answered with DEVICE_ID once (a bus error during a re-start does not take that back; another device answering does), and the write goes out even when the register cannot be read. The bits other than the switched ones then go out as zero: for CHG_OPER that is also WDTEN and an acknowledged DISBATFET, which the application sets again withConfigure(). Only the switched bits are read back. InvalidArgument,ReadOnlyRail,Unsupportedand theOutOfLimitsorUnsafethat come from the arguments and theConfigmean nothing was sent: they are decided before the reset check reads the chip. AnOutOfLimits,UnsafeorRefusedfound by reading the chip (the as-found charger, a held voltage, a protection that reads off, the shutdown preconditions) comes after reads and before any write.- Every port failure propagates: a transfer that returns
falseisError::Bus, orError::NoDevicewhen your port'sGetLastFailure()says the address was not acknowledged.
Safety¶
- There is no public raw register write. Every write is a typed call, goes through one private function that refuses any register the datasheet does not document as writable (read-only, status, key and undocumented registers), and is a read-modify-write that preserves reserved bits. The typed setter reaches configuration and mask registers only; status registers are cleared by the interrupt service and PWRCTRL3 is written by the shutdown calls.
- A value that is written back must be one the chip holds. The read of a read-modify-write is repeated until two
reads agree (at most three), and a register other than an interrupt mask that reads all ones is
VerifyFailed(a floating or stuck line).ServiceChargerWatchdog()refuses withUnsafewhen BATFET_CNFG reads with the battery overcurrent protection off andallow_batfet_oc_offis not set: a stuck line reads zero. Limitshas no defaults. A configuration withoutcell_max_mv,cell_max_charge_maandinput_max_mais rejected. A rail the application did not give a window is never enabled or set by the driver (OutOfLimits).- The charge voltage and current written never exceed
Limits, and the input current limit never exceedsinput_max_ma.Limits::coin_cell_max_mvmust be at least 3300 mV for a coin cell charge voltage above 1.8 V (ambiguity C40). - A safety downgrade is accepted only with its acknowledgement in
Config::ack, so that it is visible in the application's source: no fast-charge timer, thermistor ignored, BATFET kept closed on a fault, battery overcurrent protection reduced or off, 5 mA or 10 mA termination, a low-power mode on a rail, a coin cell charger, a changed hard-reset path, a changed undervoltage threshold, DISBATFET, a changed power-down order. - Every typed write is read back, and the whole byte is compared (bits the chip changes by itself, such as the
watchdog clear bits, are excluded). A register that reads back differently is
VerifyFailed; the value is not trusted. A rail enable that the chip clears on its own after an overcurrent (REGSCPEN, Table 136) reads back differently and reportsVerifyFailedas well. This deviates from the handbook's per-callVerifyargument (see Deviations). Not read back: the watchdog service's WDTCLR bits, the interrupt status clears and PWRCTRL3. - A rail is enabled only at a voltage inside its
Limitswindow: the voltage registers that the enable brings into effect and the call does not write are read and decoded first (OutOfLimits). The same applies toConfigure(). - The charger is parked before it is changed:
Configure()writes CHG_OPER to "linear regulator only", then every charger parameter, then the watchdog and BATFET bits, and the mode last. Charging is enabled only by a charger block inConfigure()that asks forCharge, or bySetChargerMode(Charge).SetChargerMode(Charge)re-checks the charger's registers againstLimitsand refuses withChargerFaultwhile the charger reports a fault. - The as-found check runs in
EnsureInitialized(). WithAsFoundPolicy::Report(the default) an unsafe charger found on leaves the driver uninitialised and writes nothing; withMakeSafethe driver writes CHG_OPER to "linear only" and checks again. A charger found off or in linear-only mode is not checked. EnterShip()needs aShipConfirm, state Run, Standby or Sleep, VBUS not valid and below UVLO.EnterCoreOff()needs aCoreOffConfirm, VBUS not valid and ONKEY not pushed. OtherwiseRefused, with nothing written. The driver cannot measure VBUSIN below 1.0 V, which SHIP needs (ambiguity C6): with VBUS between 1 V and UVLO the chip ends in REGS_DISABLE instead of SHIP.- GOTO_SHIP and GOTO_CORE_OFF are plain read/write bits that stay set (Table 138). A request is armed, not a
command that is over once it is sent: GOTO_CORE_OFF acts only when the chip is in REGS_DISABLE (VBUS invalid, ONKEY
high; Table 83 footnotes 8 and 9, section 10.2.2), so in Run, Standby or Sleep nothing happens and the bit stays
armed until the next REGS_DISABLE. A request that did not end in SHIP can fire at a later charger attach or battery
cycle.
CancelShutdownRequest()clears both bits and reads PWRCTRL3 back; it is not refused after DEVICE_ID has passed. Each request writes one command bit and clears the other, so a bad read cannot turn SHIP into CORE_OFF. EnableLoadSwitch()is irreversible: the chip cannot leave the mode until the next power cycle (LS_EN 1 to 0 is not allowed, Tables 130 and 134), and the output is the input rail voltage with no current limit (7.2.7). It needs aLoadSwitchConfirm{.input_mv}with the input voltage of the LDO, which must lie inside the rail'sLimitswindow, and refuses (Refused) while the rail is in low-power mode.SetPowerDownSequence()and thePowerDownConfigblock needack.power_down_order_reviewed.- Reserved bits and reserved codes are never written; a code the datasheet marks reserved is not encodable
(
InvalidArgument).
Timing and waits¶
- Every wait is bounded. The only wait is the DVS-done wait of
SetRailVoltage(): at mostkDvsWaitMaxUs(256 us), polled in 16 us steps throughDelayUs(), and only when the run voltage changes and the rail is enabled (Timeoutotherwise). - The charger watchdog, when
WatchdogConfig::enableis set, must be serviced by the application everykWatchdogServiceMaxS(16 s) or less (the datasheet reads 80 s or 32 s with 20 % accuracy, ambiguity C8). The driver has no timer:ServiceChargerWatchdog()is yours to call. The input limit check after a cable removal does not depend on it:ReadChargerStatus()andServiceInterrupts()(on a charger interrupt, also one read by a call that failed afterwards) run it too, with the charger in Charge (or LinearOnly, when the charger block is applied). While VBUSIN is invalid the limit field is held in reset: the restore waits for a valid supply andSelfCheck()reportsinput_limit_okfalse meanwhile. After an unseen chip reset the status and interrupt paths write nothing and returnDeviceReset: a charger that the reset left at an OTP limit aboveLimitsstays in that OTP state untilEnsureInitialized(), whose as-found check handles it (a switch-off bySetChargerMode(Off)is never refused). RestartCharger()makes at mostkMaxChargerRestarts(3) attempts in a row without the charger reaching a charging state and then returnsRefused.
Interrupts¶
ServiceInterrupts()reads INT_CATEGORY, copies each flagged group's status byte out, then writes the same bits back to clear them, at most three passes. A bit that sets between the copy and the clear is not lost: it is read in the next pass or the next call. The event bytes are returned as read, before the clear.- The status registers are "Read or Write 1 to clear" (Tables 90 to 110, C3): a read by another call may clear a bit.
The driver keeps every status bit that any of its calls reads (
ReadRegister(),SelfCheck(), the reset check, the DVS wait) in a latch;ServiceInterrupts()reports them with the events and empties the latch, andGetLatchedEvents()andClearLatchedEvents()give access without bus traffic. - With
GpioGet()and INTB not asserted the call returns an empty result without bus traffic, but only when the latch is empty,SetIrqMask()left no source masked (a masked source does not pull INTB, and its status bit still sets) and no input limit check is pending (one is owed from the moment a charger status byte was read, by the service or byReadRegister(), until a service has passed it). With the power-up mask (every source masked) the call reads the chip. - Residual risk: a status bit is one flag. An event of the same source that occurs again between the status read and the clear write is merged with the first and reported once, in either reading of C3 (write-one-to-clear, clear-on-read, or both). An event of another source in the same group is not lost: only the bits that were read are written back. Not verified on hardware.
- The DVS-done wait of
SetRailVoltage()polls and clears SW_INT_STAT2; the interrupt service clears the same register. Use one of them for the DVS-done bits of a rail: a call toServiceInterrupts()from another task during a voltage step can swallow the event, and the wait then returnsTimeout. - The status bytes of the charger and the PMIC groups are not atomic with each other;
ChargerStatus::consistentsays whether CHG_SNS read twice with equal values (ambiguity C27).
Data¶
Config{}holds no limits and is rejected;SingleCellLimits()gives a starting point (4.2 V, 500 mA, 1 A) that the application must check against its own cell and supply.ReadVariant()never returns an error for an option the datasheet does not list: it reports the raw bytes andOption::Unknown. A0 parts ("not programmed") are supported by reading only: the driver assumes nothing about their start-up values,StartupProfileOf(Option::A0)isInvalidArgument, and the as-found check still applies.SILICON_REVis stored raw; the driver makes no decision on it (ambiguity C22).- The DVS mode of SW1 and SW2 is an OTP fuse (
OTP_SWx_DVS_SEL) that no register reports (ambiguity C1). You declare it inBuckConfig::dvs. The driver writes a buck's voltage registers only when you declaredDvs::Enabled, and returnsReadOnlyRailotherwise. SW3 is never written. For the listed options A1 to A3 the declaration is checked against Table 85 inEnsureInitialized(): a block you configure with the wrong mode isRefused(a rail written in the wrong mode ends at 3.3 V, Table 31), and the part's mode decides how an unconfigured buck is read. For a part Table 85 does not list, DVS needsack.dvs_on_unlisted_part(Unsafewithout it, ambiguity C57). - The OTP image is not read back: the public datasheet documents no read window (ambiguity C5).
docs/datasheet.mdsays so under "What is not covered".
Depends on¶
| Dependency | Version | Why |
|---|---|---|
| A C++20 compiler | GCC 10, Clang 13 or later | Concepts constrain the port |
| CMake | 3.16 or later | Generates pf1550_version.h |
| Your port | The bus, within the bus requirements; the delay (the DVS-done wait needs DelayUs()); optionally STANDBY, INTB, a failure report and logging (Porting) |
Nothing else: no RTOS, no SDK, no other repository of the org.
Threading¶
The driver is not thread-safe and takes no lock. Use each driver object from one task at a time, or guard every call on it with one mutex; the layer that owns the driver owns that lock, and the bus lock when several chips share a bus. Nothing may run in an ISR: every call can block for a bus transfer or a delay. Separate objects share no state.
Errors¶
pf1550::Error inside pf1550::Result<T>. Values 0 to 9 are the shared base set; the chip-specific values start
at 16 and each one is returned by some call (tests/test_errors.cpp checks it).
Error |
Value | Returned when |
|---|---|---|
Ok |
0 | The call succeeded |
NotInitialized |
1 | EnsureInitialized() has not succeeded |
InvalidArgument |
2 | A value is off the datasheet grid, reserved, not an enumerator, or Limits is unset; nothing was sent |
Bus |
3 | A port hook returned false |
Timeout |
4 | The DVS-done flag did not rise within kDvsWaitMaxUs |
DeviceIdMismatch |
5 | DEVICE_ID is not 0x7C |
Crc |
6 | Not returned: I2C transfers carry no CRC |
Busy |
7 | Not returned: the chip has no busy state |
DeviceFault |
8 | Not returned: faults are reported as ChargerFault or in the status types |
Unsupported |
9 | The optional port hook the call needs is absent (GpioSet(), GpioGet()) |
OutOfLimits |
16 | A valid value outside your Limits, or a charger found on outside them; nothing was sent |
ReadOnlyRail |
17 | SW3, or SW1 or SW2 not declared Dvs::Enabled: its voltage is not written |
Unsafe |
18 | A safety downgrade without its acknowledgement; nothing was sent |
Refused |
19 | A precondition of a dangerous call is not met (state, VBUS, ONKEY, restart count) |
ChargerFault |
20 | The charger reports a fault state; charging is not enabled |
VerifyFailed |
21 | A register read back differently from what was just written |
NoDevice |
22 | Nothing acknowledged the address (needs the optional GetLastFailure() hook) |
DeviceReset |
23 | A register the driver changed reads at its start-up value again: the chip reset in the session; run EnsureInitialized() and Configure() |
Three base values (Crc, Busy, DeviceFault) are never returned: the chip's bus has no CRC, no busy state and
no fault bit that the driver reports as an error. They stay in the enumeration for the shared base set.
The API guide says what to do about each.
Memory¶
No heap, no exceptions, no RTTI, no std::function, no std::string, no printf and no static mutable state. A
driver object holds a reference to the port, the Config (296 bytes), the status latch (eight bytes) and a few flags:
336 bytes on a 64-bit host. The
largest stack objects are the diagnostic Snapshot (120 bytes) and the Config copies you make yourself. A
transfer moves one data byte, so no buffer is larger than two bytes.
Platform¶
Platform-free: the same code runs on any target with a C++20 compiler, including the host tests. The ESP-IDF port
in examples/esp32 is an example, not part of the driver.
Deviations from the standard¶
| Rule | Deviation | Why |
|---|---|---|
| KB-ARCH-041 (read-back only on request, per call) | Every typed write is followed by a read-back and VerifyFailed is returned on a mismatch |
The chip controls a battery charger and the supply of a processor. The datasheet describes registers whose writes are loaded from OTP, reset by events that the I2C interface does not report and "write-1-to-set" (ambiguity C4). A write that did not take effect cannot be allowed to pass silently. The cost is one extra single-register transfer per register written. |
Optional hooks by requires |
None: the driver detects them with named concepts as the standard asks | |
| MISRA C++:2023 rules 6.9.2, 15.1.4 and 0.0.2 (CodeQL advisories, expected) | Rule 6.9.2: the parameter of the _u8, _u16 and _u32 literal operators is unsigned long long, the type the language fixes. Rule 15.1.4: the PF1550 constructor leaves the register bus without a default member initialiser (it holds a reference). Rule 0.0.2: cppcheck's knownConditionTrueFalse on a port whose hooks are constants |
Not code defects; no waiver is recorded (see below) |
Deviations are proposed here, not waived: .kokeb/handbook.yml carries no waiver and docs/deviations.yml does not
exist for this driver. The maintainer decides whether the read-back becomes a waiver (the entry would name rule
KB-ARCH-041, this page as the place, and the one-transfer cost) or a per-call argument. No typed write targets a
write-1-to-clear or self-clearing bit: the typed setter refuses status and command registers.
Open questions¶
Ambiguities lists every place where the datasheet is silent or inconsistent (C1 to C59), the reading the driver takes, and the model knob that runs the other reading. Nothing in the driver has been verified on hardware; each bench step that would settle a row is named in Datasheet map.