pf1550_diagnostics.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <cstddef>
#include <cstdint>
 
#include "pf1550_registers.hpp"
 
namespace pf1550 {
 
enum class RailId : uint8_t {
  Sw1   = 0,  
  Sw2   = 1,  
  Sw3   = 2,  
  Ldo1  = 3,  
  Ldo2  = 4,  
  Ldo3  = 5,  
  Vsnvs = 6,  
  COUNT = 7,
};
 
enum class FaultSeverity : uint8_t {
  kInfo     = 0,
  kWarning  = 1,
  kCritical = 2,
  kMcuKill  = 3,
};
 
struct FaultFlags {
  uint32_t value{0};
 
  // ---- Switching regulator (per-rail HS / LS current limits) ----
  static constexpr uint32_t kSw1Ls = 1u << 0;
  static constexpr uint32_t kSw1Hs = 1u << 1;
  static constexpr uint32_t kSw2Ls = 1u << 2;
  static constexpr uint32_t kSw2Hs = 1u << 3;
  static constexpr uint32_t kSw3Ls = 1u << 4;
  static constexpr uint32_t kSw3Hs = 1u << 5;
 
  // ---- LDO faults ----
  static constexpr uint32_t kLdo1Fault = 1u << 8;
  static constexpr uint32_t kLdo2Fault = 1u << 9;
  static constexpr uint32_t kLdo3Fault = 1u << 10;
 
  // ---- Temperature (TEMP_INT_STAT0, Table 102) ----
  static constexpr uint32_t kTempWarn = 1u << 12; 
  static constexpr uint32_t kTempShdn = 1u << 13; 
 
  // ---- Misc system events (MISC_INT_STAT0, Table 108) ----
  static constexpr uint32_t kPwrOn     = 1u << 16; 
  static constexpr uint32_t kVsysLow   = 1u << 17; 
  static constexpr uint32_t kVsysOv    = 1u << 18; 
  static constexpr uint32_t kWdiAssert = 1u << 19; 
  static constexpr uint32_t kResetBmcu = 1u << 20; 
 
  // ---- Charger / VBUS ----
  static constexpr uint32_t kChgFault   = 1u << 24;
  static constexpr uint32_t kVbusInval  = 1u << 25;
  static constexpr uint32_t kBattOv     = 1u << 26;
 
  // ---- Driver-internal (I²C path) ----
  static constexpr uint32_t kI2cReadFail   = 1u << 30;
  static constexpr uint32_t kI2cWriteFail  = 1u << 31;
 
  [[nodiscard]] constexpr bool Any() const noexcept { return value != 0; }
  [[nodiscard]] constexpr bool Has(uint32_t mask) const noexcept { return (value & mask) != 0; }
  constexpr void Set(uint32_t mask) noexcept { value |= mask; }
  constexpr void Clear(uint32_t mask) noexcept { value &= ~mask; }
};
 
struct RailDiagnostics {
  uint8_t  ctrl_reg{0};      
  uint8_t  volt_reg{0};      
  uint16_t set_voltage_mv{0};
  bool     enabled_run{false};
  bool     enabled_stby{false};
  bool     stat_latched{false};
  bool     sense_live{false}; 
};
 
struct DiagnosticSnapshot {
  bool          read_ok{false};         
  uint8_t       device_id{0};           
  uint8_t       silicon_rev{0};         
  uint8_t       otp_flavor{0};          
  uint8_t       int_category{0};        
  uint8_t       state_info_reg{0};      
  PmicState     state{PmicState::Unknown};      
  uint8_t       chg_sense_reg{0};       
  ChargerState  charger{ChargerState::Unknown}; 
  uint8_t       vbus_sns_reg{0};        
  uint16_t      vbus_in_limit_ma{0};    
  FaultFlags    faults{};               
  RailDiagnostics rails[static_cast<size_t>(RailId::COUNT)]{};
};
 
struct SelfTestResult {
  bool          ran{false};
  bool          device_id_ok{false};
  bool          state_run{false};
  bool          all_rails_enabled{false};
  FaultSeverity worst_severity{FaultSeverity::kInfo};
  FaultFlags    faults{};                  
  DiagnosticSnapshot snapshot{};
};
 
constexpr RailId FaultRail(uint32_t single_flag) noexcept {
  if (single_flag == FaultFlags::kSw1Ls || single_flag == FaultFlags::kSw1Hs) return RailId::Sw1;
  if (single_flag == FaultFlags::kSw2Ls || single_flag == FaultFlags::kSw2Hs) return RailId::Sw2;
  if (single_flag == FaultFlags::kSw3Ls || single_flag == FaultFlags::kSw3Hs) return RailId::Sw3;
  if (single_flag == FaultFlags::kLdo1Fault) return RailId::Ldo1;
  if (single_flag == FaultFlags::kLdo2Fault) return RailId::Ldo2;
  if (single_flag == FaultFlags::kLdo3Fault) return RailId::Ldo3;
  return RailId::COUNT;
}
 
constexpr FaultSeverity FaultSeverityPortentaH7(uint32_t single_flag) noexcept {
  switch (single_flag) {
    // MCU is powered from SW3 → losing SW3 kills the MCU.
    case FaultFlags::kSw3Hs:
    case FaultFlags::kSw3Ls:
    // LDO1 (1.0 V) feeds the SOC core analog and MIPI bridge — losing it
    // crashes the platform.
    case FaultFlags::kLdo1Fault:
    // LDO3 (1.2 V) feeds Ethernet PHY VDDCR and DSI core.
    case FaultFlags::kLdo3Fault:
    case FaultFlags::kVsysLow:
      return FaultSeverity::kMcuKill;
 
    // SW1 (+3V1SW) feeds USB/ULPI, SDRAM, ETH PHY and LDO inputs — losing it
    // takes USB / network down but MCU can still run on SW3+SW3-derived
    // domains. It IS however necessary for LDO outputs.
    case FaultFlags::kSw1Hs:
    case FaultFlags::kSw1Ls:
    // SW2 feeds carrier +3V3 only; MCU keeps running.
    case FaultFlags::kSw2Hs:
    case FaultFlags::kSw2Ls:
    // LDO2 (1.8 V) for USB PHY — USB dies, MCU survives.
    case FaultFlags::kLdo2Fault:
    case FaultFlags::kTempShdn:
    case FaultFlags::kBattOv:
    case FaultFlags::kVsysOv:
      return FaultSeverity::kCritical;
 
    case FaultFlags::kTempWarn:
    case FaultFlags::kChgFault:
    case FaultFlags::kWdiAssert:
    case FaultFlags::kI2cReadFail:
    case FaultFlags::kI2cWriteFail:
      return FaultSeverity::kWarning;
 
    // No valid VBUS (VBUS_VALID clear, Table 153) is the normal state when running from the battery.
    case FaultFlags::kVbusInval:
    case FaultFlags::kPwrOn:
    case FaultFlags::kResetBmcu:
    default:
      return FaultSeverity::kInfo;
  }
}
 
constexpr FaultSeverity WorstSeverityPortentaH7(FaultFlags fl) noexcept {
  FaultSeverity worst = FaultSeverity::kInfo;
  for (uint32_t bit = 0; bit < 32; ++bit) {
    const uint32_t mask = 1u << bit;
    if ((fl.value & mask) == 0) continue;
    const auto sev = FaultSeverityPortentaH7(mask);
    if (static_cast<uint8_t>(sev) > static_cast<uint8_t>(worst)) {
      worst = sev;
    }
  }
  return worst;
}
 
constexpr const char* RailName(RailId id) noexcept {
  switch (id) {
    case RailId::Sw1:   return "SW1";
    case RailId::Sw2:   return "SW2";
    case RailId::Sw3:   return "SW3";
    case RailId::Ldo1:  return "LDO1";
    case RailId::Ldo2:  return "LDO2";
    case RailId::Ldo3:  return "LDO3";
    case RailId::Vsnvs: return "VSNVS";
    default:            return "?";
  }
}
 
constexpr const char* PmicStateName(PmicState s) noexcept {
  switch (s) {
    case PmicState::Wait:        return "Wait";
    case PmicState::Run:         return "Run";
    case PmicState::Standby:     return "Standby";
    case PmicState::Sleep:       return "Sleep";
    case PmicState::RegsDisable: return "RegsDisable";
    default:                     return "Unknown";
  }
}
 
constexpr const char* ChargerStateName(ChargerState s) noexcept {
  switch (s) {
    case ChargerState::PreCharge:    return "PreCharge";
    case ChargerState::FastCC:       return "FastCC";
    case ChargerState::FastCV:       return "FastCV";
    case ChargerState::EndOfCharge:  return "EndOfCharge";
    case ChargerState::Done:         return "Done";
    case ChargerState::TimerFault:   return "TimerFault";
    case ChargerState::ThermSuspend: return "ThermSuspend";
    case ChargerState::Off:          return "Off";
    case ChargerState::BatteryOv:    return "BatteryOv";
    case ChargerState::TempShutdown: return "TempShutdown";
    case ChargerState::LinearOnly:   return "LinearOnly";
    default:                         return "Unknown";
  }
}
 
constexpr const char* FaultSeverityName(FaultSeverity s) noexcept {
  switch (s) {
    case FaultSeverity::kInfo:     return "info";
    case FaultSeverity::kWarning:  return "warn";
    case FaultSeverity::kCritical: return "critical";
    case FaultSeverity::kMcuKill:  return "mcu-kill";
    default:                       return "?";
  }
}
 
} // namespace pf1550