|
PF1550 Driver 0.1.0
API reference
|
Driver for one PF1550 on a platform port. More...
#include <pf1550.hpp>
Public Member Functions | |
| PF1550 (Port &port, const Config &config, uint8_t address=kI2cAddress) noexcept | |
| Bind the driver to a port and a 7-bit I2C address, and store the configuration. No I/O, cannot fail. | |
| PF1550 (const PF1550 &)=delete | |
| One driver object per chip. | |
| PF1550 & | operator= (const PF1550 &)=delete |
| One driver object per chip. | |
| ~PF1550 () noexcept=default | |
| The driver holds a reference to the port. | |
| Result< uint8_t > | ReadRegister (uint8_t address) noexcept |
Read one documented register as it is, with no decoding: a read-only escape hatch for bench work. One transfer; no register is written. A status register (INT_STAT, "Read or
Write 1 to clear", Tables 90 to 110) may clear on the read: the byte is also ORed into the driver's latch (GetLatchedEvents()), so ServiceInterrupts() still reports it; a non-zero CHG_INT byte also makes the input limit check of the next ServiceInterrupts() owed, as if that call had read it. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
Start the driver: validate the configuration, bring the bus up, check DEVICE_ID = 0x7C and check the charger as found against Limits (the chip's start-up options turn the charger on with the fast-charge timer disabled, Table 85). | |
| bool | IsInitialized () const noexcept |
| const Config & | GetConfig () const noexcept |
| Result< void > | Configure () noexcept |
Write every block of the configuration whose apply is true: rails in rail_order, the small blocks, power control, the power-down order, the interrupt masks and last the charger. | |
Identity and state (read only) | |
| Result< VariantInfo > | ReadVariant () noexcept |
| Result< PowerState > | ReadPowerState () noexcept |
| Result< Snapshot > | ReadSnapshot () noexcept |
| Result< SelfCheckReport > | SelfCheck () noexcept |
| Result< ChargerAsFound > | CheckChargerAgainstLimits () noexcept |
Charger | |
| Result< ChargerStatus > | ReadChargerStatus () noexcept |
One pass over VBUS_SNS, CHG_SNS (twice), BATT_SNS: states, flags and the classified fault. The input limit is checked as well (as in ServiceChargerWatchdog(), whether or not watchdog.enable is set): a cable removal puts it back to its OTP value, and with the charger on the configured limit is written again. A failed check returns its error and not the status (the status is not kept; ReadSnapshot() reads it without the check). | |
| Result< void > | SetChargerMode (ChargerMode mode) noexcept |
Change the charger mode. Off and LinearOnly are always allowed once DEVICE_ID has passed (also when EnsureInitialized() failed or the chip reset). Charge first checks the configuration and the chip's charger registers against Limits and refuses with ChargerFault while the charger reports a fault. | |
| Result< void > | RestartCharger () noexcept |
Leave a latched fault state: off (needs only an identified chip), verify, charge (needs a live driver: DeviceReset or NotInitialized after the off step), at most kMaxChargerRestarts times in a row without the charger reaching a charging state (Refused after that). | |
| Result< void > | ServiceChargerWatchdog () noexcept |
Clear the charger watchdog (WDTCLR = 1). With watchdog.enable call it every kWatchdogServiceMaxS seconds or less (the limit check below also runs from ReadChargerStatus() and ServiceInterrupts()). The register is written from two agreeing reads; a read that shows battery overcurrent protection off is refused unless allow_batfet_oc_off is set (a stuck line must not switch the protection off). The other bits are compared after the write; WDTCLR itself is not held by the chip (C58). A cable removal puts the input limit back to its OTP value (Table 163) while the charger keeps its mode: with the charger in Charge (or LinearOnly, when the charger block is applied) the limit is read as well, and 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: nothing is written, SelfCheck() reports input_limit_ok false), a limit above Limits.input_max_ma that cannot be (the charger block is not applied) switches the charger off and returns OutOfLimits. | |
Rails | |
| Result< RailReadout > | ReadRail (Rail rail) noexcept |
| Read a rail. | |
| Result< void > | SetRailModes (Rail rail, const RailModes &modes) noexcept |
| Change which states a rail is on in. | |
| Result< void > | SetRailVoltage (Rail rail, Microvolts uv) noexcept |
Set a rail's run-mode voltage. SW1 and SW2 only when declared Dvs::Enabled; waits for the DVS-done event (at most kDvsWaitMaxUs). | |
| Result< void > | EnableLoadSwitch (Rail rail, LoadSwitchConfirm confirm) noexcept |
| Turn LDO1 or LDO3 into a load switch. IRREVERSIBLE: the chip cannot go back until the next power cycle (a 1 to 0 write of LS_EN "is not allowed", Tables 130 and 134), and a load switch has no current limit (section 7.2.6): the output is the input rail voltage. | |
Power states and the sequencer | |
| Result< void > | RequestStandby (bool standby) noexcept |
Drive the STANDBY pin (needs GpioSet()); Unsupported without it. | |
| Result< void > | EnterShip (ShipConfirm) noexcept |
| Request SHIP mode (GOTO_SHIP): every supply, VSNVS included, turns off. | |
| Result< void > | EnterCoreOff (CoreOffConfirm) noexcept |
Arm CORE_OFF (GOTO_CORE_OFF). The bit stays set; it takes effect when the part is in REGS_DISABLE (VBUS invalid, ONKEY high; Table 83 I and footnotes 8 and 9, section 10.2.2): in Run, Standby or Sleep alone nothing happens, and a later REGS_DISABLE acts on it. Refused unless STATE_INFO is Run, Standby or Sleep, VBUS reads invalid and ONKEY reads high. CancelShutdownRequest() disarms it. Not verified on hardware. Pass CoreOffConfirm{}: the tag is the caller's confirmation that the PMIC core turns off. | |
| Result< void > | CancelShutdownRequest () noexcept |
| Clear GOTO_SHIP and GOTO_CORE_OFF (write 0 to PWRCTRL3) and read it back. Works after DEVICE_ID has passed, whatever else failed: switching a request off is never refused. | |
| Result< PowerDownSequence > | ReadPowerDownSequence () noexcept |
| Read the power-down order. | |
| Result< void > | SetPowerDownSequence (const PowerDownSequence &sequence) noexcept |
Write the power-down order. Needs Acknowledgements::power_down_order_reviewed: the order decides which supply drops first and a wrong order can damage a processor. | |
Interrupts | |
| Result< void > | SetIrqMask (const IrqMask &mask) noexcept |
| Write the interrupt masks (1 masks a source). Reserved bits are preserved. | |
| Result< Categories > | ReadCategories () noexcept |
| Read INT_CATEGORY. | |
| Result< uint8_t > | ReadSense (IrqGroup group) noexcept |
| Read the live SENSE register of a group. | |
| Result< InterruptEvents > | ServiceInterrupts () noexcept |
Read and clear the pending interrupts: INT_CATEGORY, then each flagged group's status byte (copied out before the clear), then a write of the same bits to clear them, at most three passes. The result also holds every status bit that another call read since the last service (the latch). With GpioGet(), an interrupt mask that masks no source, INTB not asserted, an empty latch and no input limit check pending, the call returns an empty result without bus traffic. A status event that arrives between the read and the clearing write is cleared too when the chip clears on read (C3); keep the mask narrow. A charger interrupt also starts the input limit check of ServiceChargerWatchdog(). The check is owed from the moment a charger status byte is read, by this call or by ReadRegister(), so a call that fails later (in another pass, or a clear write) leaves it pending too; it stays pending until it has passed (it also keeps the INTB shortcut away, whatever ClearLatchedEvents() did) and is made again by the next call. The flag stays across DeviceReset and a new EnsureInitialized() (one extra check, harmless). A restore is not written over a chip that reset meanwhile (DeviceReset). | |
| InterruptEvents | GetLatchedEvents () const noexcept |
The status bits read by any call since the last ClearLatchedEvents() or service. No I/O. | |
| void | ClearLatchedEvents () noexcept |
| Empty the latch. No I/O. | |
| Result< bool > | IntbAsserted () noexcept |
| Read INTB. | |
Static Public Attributes | |
| static constexpr uint32_t | kMaxChargerRestarts = 3U |
Most restarts of a latched charger fault in a row before RestartCharger() refuses. | |
Driver for one PF1550 on a platform port.
Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one start-up call: it validates the configuration, brings the bus up, checks DEVICE_ID and checks the charger the chip starts with against your Limits. Configure() then writes the blocks you asked for. Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip as a side effect.
Optional port hooks, found at compile time:
| Hook | Used for | Without it |
|---|---|---|
void DelayUs(uint32_t us) noexcept | The DVS-done wait | Compile error at the first call that waits |
bool GpioSet(CtrlPin, GpioSignal) noexcept | STANDBY pin: RequestStandby() | RequestStandby() returns Unsupported |
bool GpioGet(CtrlPin, bool&) noexcept | INTB: IntbAsserted(), idle skip of ServiceInterrupts() | IntbAsserted() returns Unsupported |
bool GetLastFailure(I2cFailure&) noexcept | Tell an absent chip (NoDevice) from a bus error (Bus) | Every failure is Bus |
void Log(LogLevel, const char*) noexcept | One line per lifecycle event or failure | Nothing is logged |
A hook declared with the wrong signature is a compile error.
| Port | Your class derived from I2cInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port and a 7-bit I2C address, and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | What the driver validates and writes; checked in EnsureInitialized(), before any I/O. Config{} has no Limits and is rejected there. |
| address | 7-bit I2C address, 0x08 to 0x0F (OTP selects it, section 9.7.1). |
|
noexcept |
Clear GOTO_SHIP and GOTO_CORE_OFF (write 0 to PWRCTRL3) and read it back. Works after DEVICE_ID has passed, whatever else failed: switching a request off is never refused.
Ok, NotInitialized (DEVICE_ID has not passed yet), VerifyFailed (a command bit is still set), Bus.
|
noexcept |
Limits and the acknowledgements. OutOfLimits or Unsafe when the charger is on and its settings are not covered.
|
noexcept |
Write every block of the configuration whose apply is true: rails in rail_order, the small blocks, power control, the power-down order, the interrupt masks and last the charger.
The charger is written with its mode at "linear regulator only", then every parameter, then WDTEN and DISBATFET, and CHG_OPER's mode last (datasheet silent on glitch-free changes: C16, C49). Every register write is read back.
Ok, NotInitialized, Bus, VerifyFailed, Timeout (a DVS step did not finish) or ChargerFault (parameters are written, charging is not enabled).
|
noexcept |
Turn LDO1 or LDO3 into a load switch. IRREVERSIBLE: the chip cannot go back until the next power cycle (a 1 to 0 write of LS_EN "is not allowed", Tables 130 and 134), and a load switch has no current limit (section 7.2.6): the output is the input rail voltage.
| rail | Rail::Ldo1 or Rail::Ldo3. |
| confirm | The caller's confirmation, with the input rail voltage in millivolts: it must lie inside the rail's Limits window. |
Ok, InvalidArgument, OutOfLimits (no window, or the input voltage is outside it), Refused (the rail is in low-power mode), DeviceReset, VerifyFailed, Bus.
|
noexcept |
Start the driver: validate the configuration, bring the bus up, check DEVICE_ID = 0x7C and check the charger as found against Limits (the chip's start-up options turn the charger on with the fast-charge timer disabled, Table 85).
Sends: DEVICE_ID, OTP_FLAVOR (the DVS declaration of SW1 and SW2 is checked against Table 85 for a listed option), then the charger registers. It writes nothing otherwise. With AsFoundPolicy::MakeSafe and an unsafe charger found on, also one write of CHG_OPER (linear regulator only) and the same reads again.
After DEVICE_ID has passed, SetChargerMode(Off or LinearOnly), CheckChargerAgainstLimits() and CancelShutdownRequest() work even when this call then fails (an unsafe charger found on must always be switchable off).
Ok; the Validate() error; Bus or NoDevice (nothing acknowledged: needs the optional GetLastFailure() hook); DeviceIdMismatch; Refused (a DVS declaration that contradicts the part), Unsafe (a DVS declaration on an unlisted part without its acknowledgement); OutOfLimits or Unsafe for an unsafe charger under AsFoundPolicy::Report; VerifyFailed. The call can be repeated.
|
noexcept |
Arm CORE_OFF (GOTO_CORE_OFF). The bit stays set; it takes effect when the part is in REGS_DISABLE (VBUS invalid, ONKEY high; Table 83 I and footnotes 8 and 9, section 10.2.2): in Run, Standby or Sleep alone nothing happens, and a later REGS_DISABLE acts on it. Refused unless STATE_INFO is Run, Standby or Sleep, VBUS reads invalid and ONKEY reads high. CancelShutdownRequest() disarms it. Not verified on hardware. Pass CoreOffConfirm{}: the tag is the caller's confirmation that the PMIC core turns off.
Ok, Refused, DeviceReset, Bus.
|
noexcept |
Request SHIP mode (GOTO_SHIP): every supply, VSNVS included, turns off.
Refused unless STATE_INFO is Run, Standby or Sleep and VBUS reads below UVLO and not valid. The chip enters SHIP only when VBUSIN is below 1.0 V, which the driver cannot measure (Table 83, ambiguity C6); with VBUS between 1 V and UVLO it ends in REGS_DISABLE instead, and GOTO_SHIP stays set (the bit is plain read/write, Table 138): it acts again at the next REGS_DISABLE. CancelShutdownRequest() clears it. Recovery from SHIP is by a charger or a battery attach. Not verified on hardware. Pass ShipConfirm{}: the tag is the caller's confirmation that every supply turns off.
Ok, Refused, Bus.
|
inlinenoexcept |
|
inlinenoexcept |
The status bits read by any call since the last ClearLatchedEvents() or service. No I/O.
fault_class set when one is a fault-class source.
|
noexcept |
Read INTB.
Unsupported without GpioGet().
|
inlinenoexcept |
EnsureInitialized() has succeeded and until a chip reset is seen.
|
noexcept |
Read INT_CATEGORY.
|
noexcept |
One pass over VBUS_SNS, CHG_SNS (twice), BATT_SNS: states, flags and the classified fault. The input limit is checked as well (as in ServiceChargerWatchdog(), whether or not watchdog.enable is set): a cable removal puts it back to its OTP value, and with the charger on the configured limit is written again. A failed check returns its error and not the status (the status is not kept; ReadSnapshot() reads it without the check).
OutOfLimits (the limit is above Limits and the charger was switched off), VerifyFailed, DeviceReset, Bus, NotInitialized.
|
noexcept |
Read the power-down order.
*_PWRDN_SEQ registers (section 10.7).
|
noexcept |
|
noexcept |
Read a rail.
| rail | Any rail. |
dvs you declared in Config.
|
noexcept |
Read one documented register as it is, with no decoding: a read-only escape hatch for bench work. One transfer; no register is written. A status register (INT_STAT, "Read or
Write 1 to clear", Tables 90 to 110) may clear on the read: the byte is also ORed into the driver's latch (GetLatchedEvents()), so ServiceInterrupts() still reports it; a non-zero CHG_INT byte also makes the input limit check of the next ServiceInterrupts() owed, as if that call had read it.
| address | An absolute register address (PMIC 0x00 to 0x6F, charger 0x80 to 0x9F). |
InvalidArgument for an address the data sheet does not document, NotInitialized or Bus.
|
noexcept |
Read the live SENSE register of a group.
| group | The group. |
InvalidArgument.
|
noexcept |
|
noexcept |
Option::Unknown with the raw byte; pass such an option by hand to StartupProfileOf() when you know your part (C10).
|
noexcept |
Drive the STANDBY pin (needs GpioSet()); Unsupported without it.
| standby | true to request STANDBY. |
Ok, Unsupported, Bus.
|
noexcept |
Leave a latched fault state: off (needs only an identified chip), verify, charge (needs a live driver: DeviceReset or NotInitialized after the off step), at most kMaxChargerRestarts times in a row without the charger reaching a charging state (Refused after that).
Ok, Refused, ChargerFault, OutOfLimits, Unsafe, VerifyFailed, Bus.
|
noexcept |
input_limit_ok: a valid code, within Limits.input_max_ma, and the configured one when the charger block is applied). Read only.
|
noexcept |
Clear the charger watchdog (WDTCLR = 1). With watchdog.enable call it every kWatchdogServiceMaxS seconds or less (the limit check below also runs from ReadChargerStatus() and ServiceInterrupts()). The register is written from two agreeing reads; a read that shows battery overcurrent protection off is refused unless allow_batfet_oc_off is set (a stuck line must not switch the protection off). The other bits are compared after the write; WDTCLR itself is not held by the chip (C58). A cable removal puts the input limit back to its OTP value (Table 163) while the charger keeps its mode: with the charger in Charge (or LinearOnly, when the charger block is applied) the limit is read as well, and 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: nothing is written, SelfCheck() reports input_limit_ok false), a limit above Limits.input_max_ma that cannot be (the charger block is not applied) switches the charger off and returns OutOfLimits.
Ok, Unsafe, OutOfLimits, VerifyFailed, DeviceReset, Bus, NotInitialized.
|
noexcept |
Read and clear the pending interrupts: INT_CATEGORY, then each flagged group's status byte (copied out before the clear), then a write of the same bits to clear them, at most three passes. The result also holds every status bit that another call read since the last service (the latch). With GpioGet(), an interrupt mask that masks no source, INTB not asserted, an empty latch and no input limit check pending, the call returns an empty result without bus traffic. A status event that arrives between the read and the clearing write is cleared too when the chip clears on read (C3); keep the mask narrow. A charger interrupt also starts the input limit check of ServiceChargerWatchdog(). The check is owed from the moment a charger status byte is read, by this call or by ReadRegister(), so a call that fails later (in another pass, or a clear write) leaves it pending too; it stays pending until it has passed (it also keeps the INTB shortcut away, whatever ClearLatchedEvents() did) and is made again by the next call. The flag stays across DeviceReset and a new EnsureInitialized() (one extra check, harmless). A restore is not written over a chip that reset meanwhile (DeviceReset).
OutOfLimits (the limit is above Limits, the charger was switched off), VerifyFailed, DeviceReset, Bus, NotInitialized. After one of the errors the bits stay in the latch for the next call.
|
noexcept |
Change the charger mode. Off and LinearOnly are always allowed once DEVICE_ID has passed (also when EnsureInitialized() failed or the chip reset). Charge first checks the configuration and the chip's charger registers against Limits and refuses with ChargerFault while the charger reports a fault.
| mode | The mode. |
Ok, InvalidArgument, ChargerFault, OutOfLimits, Unsafe, VerifyFailed, DeviceReset (Charge only), Bus.
|
noexcept |
Write the interrupt masks (1 masks a source). Reserved bits are preserved.
| mask | One mask byte per group. |
Ok, VerifyFailed, Bus.
|
noexcept |
Write the power-down order. Needs Acknowledgements::power_down_order_reviewed: the order decides which supply drops first and a wrong order can damage a processor.
| sequence | Order 0 to 7 per rail; regulators turn off in descending order, all 0 bypasses. |
Ok, InvalidArgument, Unsafe, VerifyFailed, Bus.
|
noexcept |
Change which states a rail is on in.
| rail | Any rail. |
| modes | EN, STBY_EN, OMODE, LPWR; checked against Limits (the rail needs a window) and load_below_10ma. standby or sleep without run is refused: EN = 0 disables the rail in every state (Table 42). Before a rail is enabled the voltage registers it will use are read and decoded; a voltage outside the rail's window is OutOfLimits. A request that leaves every state off needs only an identified chip (no reset check, no limits) and is written even when the register cannot be read: the other bits then go out as zero and only the switched bits are read back (VerifyFailed if they differ). |
Ok, InvalidArgument, OutOfLimits, Unsafe, DeviceReset, VerifyFailed, Bus.
|
noexcept |
Set a rail's run-mode voltage. SW1 and SW2 only when declared Dvs::Enabled; waits for the DVS-done event (at most kDvsWaitMaxUs).
| rail | SW1, SW2, LDO1, LDO2 or LDO3. |
| uv | On the rail's grid and inside its Limits window. |
Ok, InvalidArgument, OutOfLimits, ReadOnlyRail (SW3, or a buck not declared DVS), Timeout, VerifyFailed, Bus.