tle92466ed_registers.hpp

Go to the documentation of this file.

 
#pragma once
#include <algorithm>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace tle92466ed {
 
//==============================================================================
// REGISTER ADDRESSES - CENTRAL/GLOBAL REGISTERS
//==============================================================================
 
namespace CentralReg {
constexpr uint16_t CH_CTRL = 0x0000;       
constexpr uint16_t GLOBAL_CONFIG = 0x0002; 
constexpr uint16_t GLOBAL_DIAG0 = 0x0003;  
constexpr uint16_t GLOBAL_DIAG1 = 0x0004;  
constexpr uint16_t GLOBAL_DIAG2 = 0x0005;  
constexpr uint16_t VBAT_TH = 0x0006;       
constexpr uint16_t FB_FRZ = 0x0007;        
constexpr uint16_t FB_UPD = 0x0008;        
constexpr uint16_t WD_RELOAD = 0x0009;     
 
// Channel Group Diagnosis (per datasheet §5.3.2.12 / §5.3.2.13)
// There are ONLY 3 groups. Each group covers a pair of channels via
// an internal y=0/y=1 field offset:
//   CHGR0 covers CH0 (y=0) + CH1 (y=1)
//   CHGR1 covers CH2 (y=0) + CH3 (y=1)
//   CHGR2 covers CH4 (y=0) + CH5 (y=1)
// Use DIAG_ERR_CHGR::AddressForChannel(ch) / DIAG_WARN_CHGR::AddressForChannel(ch).
// Addresses 0x000D..0x000F and 0x0013..0x0015 are NOT DIAG registers.
constexpr uint16_t DIAG_ERR_CHGR0 = 0x000A; 
constexpr uint16_t DIAG_ERR_CHGR1 = 0x000B; 
constexpr uint16_t DIAG_ERR_CHGR2 = 0x000C; 
 
constexpr uint16_t DIAG_WARN_CHGR0 = 0x0010; 
constexpr uint16_t DIAG_WARN_CHGR1 = 0x0011; 
constexpr uint16_t DIAG_WARN_CHGR2 = 0x0012; 
 
constexpr uint16_t FAULT_MASK0 = 0x0016; 
constexpr uint16_t FAULT_MASK1 = 0x0017; 
constexpr uint16_t FAULT_MASK2 = 0x0018; 
constexpr uint16_t CLK_DIV = 0x0019;     
constexpr uint16_t SFF_BIST = 0x003F;    
 
// Feedback/Status Registers
constexpr uint16_t ICVID = 0x0200;       
constexpr uint16_t PIN_STAT = 0x0201;    
constexpr uint16_t FB_STAT = 0x0202;     
constexpr uint16_t FB_VOLTAGE1 = 0x0203; 
constexpr uint16_t FB_VOLTAGE2 = 0x0204; 
constexpr uint16_t CHIPID0 = 0x0205;     
constexpr uint16_t CHIPID1 = 0x0206;     
constexpr uint16_t CHIPID2 = 0x0207;     
} // namespace CentralReg
 
//==============================================================================
// DEVICE IDENTIFICATION CONSTANTS
//==============================================================================
 
namespace DeviceID {
constexpr uint16_t DEVICE_TYPE_MASK = 0xFF00; 
constexpr uint16_t REVISION_MASK = 0x00FF;    
 
// Expected manufacturer/device-type code for TLE92466ED (upper byte of ICVID).
// Per datasheet §5.3.2.19 p.75 the high byte is fixed at 0xC1 (Infineon
// manufacturer ID for this family); the low byte is the silicon revision
// and may vary by part lot. VerifyDevice() accepts any 0xC1?? value.
constexpr uint8_t EXPECTED_TYPE_92466ED = 0xC1; 
 
// Minimum supported silicon revision
constexpr uint8_t MIN_REVISION = 0x00; 
 
[[nodiscard]] constexpr bool IsValidDevice(uint16_t icvid) noexcept {
  // Reject obviously broken reads (all-zero / all-one).
  if (icvid == 0x0000 || icvid == 0xFFFF) return false;
  const uint8_t device_type = static_cast<uint8_t>((icvid >> 8) & 0xFF);
  return device_type == EXPECTED_TYPE_92466ED;
}
 
[[nodiscard]] constexpr uint8_t GetDeviceType(uint16_t icvid) noexcept {
  return (icvid >> 8) & 0xFF;
}
 
[[nodiscard]] constexpr uint8_t GetRevision(uint16_t icvid) noexcept {
  return icvid & 0xFF;
}
} // namespace DeviceID
 
//==============================================================================
// CHANNEL REGISTER OFFSETS
//==============================================================================
 
namespace ChannelBase {
constexpr uint16_t CH0 = 0x0040; 
constexpr uint16_t CH1 = 0x0050; 
constexpr uint16_t CH2 = 0x0060; 
constexpr uint16_t CH3 = 0x0070; 
constexpr uint16_t CH4 = 0x0020; 
constexpr uint16_t CH5 = 0x0030; 
} // namespace ChannelBase
 
namespace ChannelReg {
constexpr uint16_t SETPOINT = 0x0000;          
constexpr uint16_t CTRL = 0x0001;              
constexpr uint16_t PERIOD = 0x0002;            
constexpr uint16_t INTEGRATOR_LIMIT = 0x0003;  
constexpr uint16_t DITHER_CLK_DIV = 0x0004;    
constexpr uint16_t DITHER_STEP = 0x0005;       
constexpr uint16_t DITHER_CTRL = 0x0006;       
constexpr uint16_t CH_CONFIG = 0x0007;         
constexpr uint16_t MODE = 0x000C;              
constexpr uint16_t TON = 0x000D;               
constexpr uint16_t CTRL_INT_THRESH = 0x000E;   
constexpr uint16_t FB_DC = 0x0200;             
constexpr uint16_t FB_VBAT = 0x0201;           
constexpr uint16_t FB_I_AVG = 0x0202;          
constexpr uint16_t FB_IMIN_IMAX = 0x0203;      
constexpr uint16_t FB_I_AVG_s16 = 0x0204;      
constexpr uint16_t FB_INT_THRESH = 0x0205;     
constexpr uint16_t FB_PERIOD_MIN_MAX = 0x0206; 
} // namespace ChannelReg
 
//==============================================================================
// CH_CTRL REGISTER (0x0000) - Channel Control
//==============================================================================
 
namespace CH_CTRL {
constexpr uint16_t EN_CH0 = (1 << 0);      
constexpr uint16_t EN_CH1 = (1 << 1);      
constexpr uint16_t EN_CH2 = (1 << 2);      
constexpr uint16_t EN_CH3 = (1 << 3);      
constexpr uint16_t EN_CH4 = (1 << 4);      
constexpr uint16_t EN_CH5 = (1 << 5);      
constexpr uint16_t CH_PAR_4_5 = (1 << 12); 
constexpr uint16_t CH_PAR_0_3 = (1 << 13); 
constexpr uint16_t CH_PAR_1_2 = (1 << 14); 
constexpr uint16_t OP_MODE = (1 << 15);    
 
constexpr uint16_t ALL_CH_MASK = 0x003F;  
constexpr uint16_t ALL_PAR_MASK = 0x7000; 
 
constexpr uint16_t DEFAULT = 0x0000; 
 
constexpr uint16_t CONFIG_MODE = 0x0000;
constexpr uint16_t MISSION_MODE = OP_MODE;
 
[[nodiscard]] constexpr uint16_t ChannelMask(uint8_t channel) noexcept {
  return (channel < 6) ? static_cast<uint16_t>(1 << channel) : 0;
}
} // namespace CH_CTRL
 
//==============================================================================
// GLOBAL_CONFIG REGISTER (0x0002) - Global Configuration
//==============================================================================
 
namespace GLOBAL_CONFIG {
constexpr uint16_t CLK_WD_EN = (1 << 0);    
constexpr uint16_t SPI_WD_EN = (1 << 1);    
constexpr uint16_t CRC_EN = (1 << 2);       
constexpr uint16_t V1V5_UV_TEST = (1 << 4); 
constexpr uint16_t V1V5_OV_TEST = (1 << 5); 
constexpr uint16_t OT_TEST = (1 << 12);     
constexpr uint16_t UV_OV_SWAP = (1 << 13);  
constexpr uint16_t VIO_SEL = (1 << 14);     
 
constexpr uint16_t DEFAULT = 0x4005; 
} // namespace GLOBAL_CONFIG
 
//==============================================================================
// GLOBAL_DIAG0 REGISTER (0x0003) - Global Diagnosis Register 0
//==============================================================================
 
namespace GLOBAL_DIAG0 {
constexpr uint16_t VBAT_UV = (1 << 0);     
constexpr uint16_t VBAT_OV = (1 << 1);     
constexpr uint16_t VIO_UV = (1 << 2);      
constexpr uint16_t VIO_OV = (1 << 3);      
constexpr uint16_t VDD_UV = (1 << 4);      
constexpr uint16_t VDD_OV = (1 << 5);      
constexpr uint16_t CLK_NOK = (1 << 6);     
constexpr uint16_t COTERR = (1 << 7);      
constexpr uint16_t COTWARN = (1 << 8);     
constexpr uint16_t RES_EVENT = (1 << 9);   
constexpr uint16_t POR_EVENT = (1 << 10);  
constexpr uint16_t SPI_WD_ERR = (1 << 14); 
 
constexpr uint16_t DEFAULT = 0x0600;    
constexpr uint16_t FAULT_MASK = 0x47FF; 
constexpr uint16_t CLEAR_ALL = 0xFFFF;  
} // namespace GLOBAL_DIAG0
 
//==============================================================================
// WD_RELOAD REGISTER (0x0009) - SPI Watchdog Reload Register
//==============================================================================
 
namespace WD_RELOAD {
constexpr uint16_t WD_TIME_MASK = 0x07FF; 
constexpr uint16_t WD_TIME_MAX = 0x07FF;  
constexpr uint16_t DEFAULT = 0x0001;      
 
[[nodiscard]] constexpr uint16_t MaskValue(uint16_t value) noexcept {
  return value & WD_TIME_MASK;
}
} // namespace WD_RELOAD
 
//==============================================================================
// GLOBAL_DIAG1 REGISTER (0x0004) - Global Diagnosis Register 1
//==============================================================================
 
namespace GLOBAL_DIAG1 {
constexpr uint16_t VR_IREF_UV = (1 << 0); 
constexpr uint16_t VR_IREF_OV = (1 << 1); 
constexpr uint16_t VDD2V5_UV = (1 << 2);  
constexpr uint16_t VDD2V5_OV = (1 << 3);  
constexpr uint16_t REF_UV = (1 << 4);     
constexpr uint16_t REF_OV = (1 << 5);     
constexpr uint16_t VPRE_OV = (1 << 6);    
constexpr uint16_t HVADC_ERR = (1 << 15); 
 
constexpr uint16_t DEFAULT = 0x0000;   
constexpr uint16_t CLEAR_ALL = 0xFFFF; 
} // namespace GLOBAL_DIAG1
 
//==============================================================================
// DIAG_ERR_CHGRx REGISTERS (0x000A..0x000C) - Per-Channel-Pair Error Diagnostics
//==============================================================================
 
namespace DIAG_ERR_CHGR {
constexpr uint8_t BIT_OLSG = 0; 
constexpr uint8_t BIT_OL   = 1; 
constexpr uint8_t BIT_OC   = 2; 
constexpr uint8_t BIT_SG   = 3; 
constexpr uint8_t BIT_OTE  = 4; 
 
constexpr uint16_t PER_CHANNEL_MASK = 0x001Fu;
 
constexpr uint16_t OC_BOTH_MASK = (1u << BIT_OC) | (1u << (BIT_OC + 8));
 
[[nodiscard]] constexpr uint16_t AddressForChannel(uint8_t channel) noexcept {
  return static_cast<uint16_t>(CentralReg::DIAG_ERR_CHGR0 + (channel / 2));
}
 
[[nodiscard]] constexpr uint8_t YShiftForChannel(uint8_t channel) noexcept {
  return static_cast<uint8_t>((channel & 1u) * 8u);
}
 
[[nodiscard]] constexpr uint16_t ChannelBitMask(uint8_t channel, uint8_t bit_index) noexcept {
  return static_cast<uint16_t>(1u << (bit_index + YShiftForChannel(channel)));
}
 
[[nodiscard]] constexpr uint16_t OcClearMaskForChannel(uint8_t channel) noexcept {
  return ChannelBitMask(channel, BIT_OC);
}
} // namespace DIAG_ERR_CHGR
 
//==============================================================================
// DIAG_WARN_CHGRx REGISTERS (0x0010..0x0012) - Per-Channel-Pair Warnings
//==============================================================================
 
namespace DIAG_WARN_CHGR {
constexpr uint8_t BIT_PWM_REG      = 0;
constexpr uint8_t BIT_I_REG        = 1;
constexpr uint8_t BIT_OTW          = 2;
constexpr uint8_t BIT_OLSG_WARN    = 3;
constexpr uint8_t BIT_OLSG_CHK_NOK = 4;
 
constexpr uint16_t PER_CHANNEL_MASK = 0x001Fu;
 
[[nodiscard]] constexpr uint16_t AddressForChannel(uint8_t channel) noexcept {
  return static_cast<uint16_t>(CentralReg::DIAG_WARN_CHGR0 + (channel / 2));
}
 
[[nodiscard]] constexpr uint8_t YShiftForChannel(uint8_t channel) noexcept {
  return static_cast<uint8_t>((channel & 1u) * 8u);
}
 
[[nodiscard]] constexpr uint16_t ChannelBitMask(uint8_t channel, uint8_t bit_index) noexcept {
  return static_cast<uint16_t>(1u << (bit_index + YShiftForChannel(channel)));
}
} // namespace DIAG_WARN_CHGR
 
//==============================================================================
// GLOBAL_DIAG2 REGISTER (0x0005) - Global Diagnosis Register 2
//==============================================================================
 
namespace GLOBAL_DIAG2 {
constexpr uint16_t REG_ECC_ERR = (1 << 1); 
constexpr uint16_t OTP_ECC_ERR = (1 << 3); 
constexpr uint16_t OTP_VIRGIN = (1 << 4);  
 
constexpr uint16_t DEFAULT = 0x0000;   
constexpr uint16_t CLEAR_ALL = 0xFFFF; 
} // namespace GLOBAL_DIAG2
 
//==============================================================================
// FB_STAT REGISTER (0x0202) - Feedback Status
//==============================================================================
 
namespace FB_STAT {
constexpr uint32_t DIAG_WARN_CHGR0 = (1u << 0);  
constexpr uint32_t DIAG_WARN_CHGR1 = (1u << 1);  
constexpr uint32_t DIAG_WARN_CHGR2 = (1u << 2);  
constexpr uint32_t OLSG_WARN_CHK_NOK_CHGR0 = (1u << 3);  
constexpr uint32_t OLSG_WARN_CHK_NOK_CHGR1 = (1u << 4);  
constexpr uint32_t OLSG_WARN_CHK_NOK_CHGR2 = (1u << 5);  
constexpr uint32_t CLK_NOK_STAT = (1u << 6);  
constexpr uint32_t COTERR = (1u << 7);        
constexpr uint32_t COTWARN = (1u << 8);       
constexpr uint32_t RES_EVENT = (1u << 9);     
constexpr uint32_t POR_EVENT = (1u << 10);    
constexpr uint32_t DATA_ERR = (1u << 11);     
constexpr uint32_t SUP_NOK_EXT = (1u << 12);  
constexpr uint32_t SUP_NOK_INT = (1u << 13);  
constexpr uint32_t ERR_CHGR0 = (1u << 14);    
constexpr uint32_t ERR_CHGR1 = (1u << 15);    
constexpr uint32_t ERR_CHGR2 = (1u << 16);    
constexpr uint32_t SPI_WD_ERR = (1u << 20);   
constexpr uint32_t INIT_DONE = (1u << 21);    
} // namespace FB_STAT
 
//==============================================================================
// CHANNEL SETPOINT REGISTER - Per Channel
//==============================================================================
 
namespace SETPOINT {
constexpr uint16_t TARGET_MASK = 0x7FFF;       
constexpr uint16_t AUTO_LIMIT_DIS = (1 << 15); 
 
constexpr uint16_t DEFAULT = 0x0000; 
 
constexpr uint16_t MAX_TARGET = 0x6000;
 
[[nodiscard]] constexpr uint16_t CalculateTarget(uint16_t current_ma,
                                                 bool parallel_mode = false) noexcept {
  uint32_t max_current = parallel_mode ? 4000 : 2000;
  // Integer math: adding (max_current/2) before division is equivalent to (val / max_current + 0.5)
  // for rounding up (uint32_t(current_ma) * 32767UL + max_current / 2) / max_current  <=>
  // (current_ma * 32767 / max_current + 0.5)
  uint32_t target = (static_cast<uint32_t>(current_ma) * 32767UL + (max_current / 2)) / max_current;
  // Saturate at MAX_TARGET
  target = std::min(target, static_cast<uint32_t>(MAX_TARGET));
  return static_cast<uint16_t>(target);
}
 
[[nodiscard]] constexpr uint16_t CalculateTargetUa(uint32_t current_ua,
                                                   bool parallel_mode = false) noexcept {
  const uint64_t max_ua = parallel_mode ? 4000000ULL : 2000000ULL;
  uint64_t target = (static_cast<uint64_t>(current_ua) * 32767ULL + (max_ua / 2ULL)) / max_ua;
  if (target > MAX_TARGET) {
    target = MAX_TARGET;
  }
  return static_cast<uint16_t>(target);
}
 
[[nodiscard]] constexpr uint16_t CalculateCurrent(uint16_t target,
                                                  bool parallel_mode = false) noexcept {
  uint32_t max_current = parallel_mode ? 4000 : 2000;
  // Use rounding: add half of 32767 before division to minimize quantization error
  uint32_t current = (static_cast<uint32_t>(target & TARGET_MASK) * max_current + 16383) / 32767UL;
  return static_cast<uint16_t>(current);
}
 
// Datasheet §5.3.3.3: I_set = 2 A * TARGET / (2^15-1); 0x6000 saturates at 1.5 A.
// A 9-bit TARGET (0x1FF) decodes as 31 mA — the HIL "clamped to 31 mA" signature
// when SETPOINT readback is actually FB_IMIN (10-bit signed, max +511) or a
// truncated field rather than the 15-bit TARGET. CH_CTRL 0x8020 (Mission+CH5)
// decodes as 2 mA — the leftover from a MakeRead(0) dummy.
static_assert(CalculateTarget(115) == 1884, "115 mA → TARGET 0x075C");
static_assert(CalculateCurrent(1884) == 115, "TARGET 0x075C → 115 mA");
static_assert(CalculateCurrent(0x01FF) == 31, "9-bit max TARGET decodes as 31 mA");
static_assert(CalculateCurrent(0x0020) == 2, "CH_CTRL EN_CH5 leftover decodes as 2 mA");
} // namespace SETPOINT
 
//==============================================================================
// PERIOD REGISTER - PWM Period Configuration
//==============================================================================
 
namespace PERIOD {
constexpr uint16_t MANT_MASK = 0x00FF;       
constexpr uint16_t EXP_MASK = 0x0700;        
constexpr uint16_t EXP_SHIFT = 8;            
constexpr uint8_t EXP_VALUE_MASK = 0x07;     
constexpr uint16_t LOW_FREQ_BIT = (1 << 11); 
 
constexpr uint16_t PWM_CTRL_PARAM_SHIFT = 12;
constexpr uint16_t PWM_CTRL_PARAM_MASK  = 0xF000;
 
constexpr uint32_t F_SYS_HZ = 28'000'000UL;           
constexpr float F_SYS_PERIOD_US = 1.0F / 28.0F;       
 
//
// Datasheet-spec PWM frequency range
// ----------------------------------
// Per datasheet (Electrical Characteristics, parameter "Target PWM frequency
// fPWM"): the PWM frequency controller is specified to operate between
// 110 Hz and 4000 Hz. Setting a value outside this range will not be
// rejected by the chip — it simply isn't guaranteed to work.
//
// With the LOW_FREQ_RANGE_EN bit set, the period is multiplied by 8, so
// the supported frequency range is 8× lower (≈13.75 Hz – 500 Hz).
//
// Periods are derived from the formula  T_pwm = 1 / f_pwm.
//
// Note: the chip family cannot drive PWM above 4 kHz, so reaching the
// ultrasonic range (>20 kHz) is not possible with the TLE92466ED.
//
constexpr float kSpecMinFrequency_Hz   = 110.0F;     
constexpr float kSpecMaxFrequency_Hz   = 4000.0F;    
constexpr float kSpecMinPeriod_us      = 1.0e6F / kSpecMaxFrequency_Hz;  
constexpr float kSpecMaxPeriod_us      = 1.0e6F / kSpecMinFrequency_Hz;  
 
constexpr float kSpecLowRangeMinFreq_Hz = kSpecMinFrequency_Hz / 8.0F;   
constexpr float kSpecLowRangeMaxFreq_Hz = kSpecMaxFrequency_Hz / 8.0F;   
constexpr float kSpecLowRangeMinPeriod_us =
    1.0e6F / kSpecLowRangeMaxFreq_Hz;                                    
constexpr float kSpecLowRangeMaxPeriod_us =
    1.0e6F / kSpecLowRangeMinFreq_Hz;                                    
 
constexpr float kSpecCombinedMinPeriod_us = kSpecMinPeriod_us;
constexpr float kSpecCombinedMaxPeriod_us = kSpecLowRangeMaxPeriod_us;
 
struct PeriodConfig {
  uint8_t mantissa;    
  uint8_t exponent;    
  bool low_freq_range; 
 
  [[nodiscard]] constexpr float CalculatePeriodUs() const noexcept {
    float base_period =
        static_cast<float>(mantissa) * static_cast<float>(1ULL << exponent) * F_SYS_PERIOD_US;
    return low_freq_range ? (base_period * 8.0F) : base_period;
  }
};
 
[[nodiscard]] inline PeriodConfig CalculateFromPeriodUs(float period_us) noexcept {
  PeriodConfig config{};
 
  // Try standard range first
  for (uint8_t exp = 0; exp <= 7; ++exp) {
    float divisor = static_cast<float>(1ULL << exp) * F_SYS_PERIOD_US;
    float mantissa_f = period_us / divisor;
 
    if (mantissa_f <= 255.0F && mantissa_f >= 1.0F) {
      config.mantissa = static_cast<uint8_t>(std::lround(mantissa_f)); // Round
      config.exponent = exp;
      config.low_freq_range = false;
      return config;
    }
  }
 
  // Try low frequency range (8x multiplier)
  for (uint8_t exp = 0; exp <= 7; ++exp) {
    float divisor = static_cast<float>(1ULL << exp) * F_SYS_PERIOD_US * 8.0F;
    float mantissa_f = period_us / divisor;
 
    if (mantissa_f <= 255.0F && mantissa_f >= 1.0F) {
      config.mantissa = static_cast<uint8_t>(std::lround(mantissa_f)); // Round
      config.exponent = exp;
      config.low_freq_range = true;
      return config;
    }
  }
 
  // Out of range - return invalid (mantissa = 0)
  config.mantissa = 0;
  config.exponent = 0;
  config.low_freq_range = false;
  return config;
}
 
[[nodiscard]] constexpr uint16_t BuildRegisterValue(const PeriodConfig& config) noexcept {
  return config.mantissa | ((config.exponent & 0x07) << EXP_SHIFT) |
         (config.low_freq_range ? LOW_FREQ_BIT : 0);
}
} // namespace PERIOD
 
//==============================================================================
// CHANNEL CTRL REGISTER - Per Channel
//==============================================================================
 
namespace CH_CTRL_REG {
constexpr uint16_t MIN_INT_THRESH_MASK = 0x00FF;    
constexpr uint16_t PWM_PERIOD_CALC_MODE = (1 << 8); 
constexpr uint16_t OLSG_WARN_WINDOW_MASK = 0x3E00;  
constexpr uint16_t OLSG_WARN_WINDOW_SHIFT = 9;      
constexpr uint16_t OLSG_WARN_EN = (1 << 14);        
 
constexpr uint16_t DEFAULT = 0x4600; 
 
constexpr uint16_t DEFAULT_OLSG_WARN_WINDOW = 3u;
 
constexpr uint8_t MIN_INT_THRESH_FLOOR = 2u;
 
constexpr uint8_t MIN_INT_THRESH_CEIL = 12u;
 
[[nodiscard]] constexpr uint16_t Build(uint8_t min_int_thresh,
                                       bool olsg_warning_enabled,
                                       bool pwm_period_calc_mode) noexcept {
  return static_cast<uint16_t>(
      (static_cast<uint16_t>(min_int_thresh) & MIN_INT_THRESH_MASK) |
      ((DEFAULT_OLSG_WARN_WINDOW << OLSG_WARN_WINDOW_SHIFT) & OLSG_WARN_WINDOW_MASK) |
      (olsg_warning_enabled ? OLSG_WARN_EN : 0u) |
      (pwm_period_calc_mode ? PWM_PERIOD_CALC_MODE : 0u));
}
 
static_assert(Build(0u, true, false) == DEFAULT,
              "Build with POR fields must reproduce the datasheet reset value");
} // namespace CH_CTRL_REG
 
//==============================================================================
// CH_CONFIG REGISTER - Per Channel Configuration
//==============================================================================
 
namespace CH_CONFIG {
// Slew rate control [1:0]
constexpr uint16_t SLEWR_1V0_US = 0b00;  
constexpr uint16_t SLEWR_2V5_US = 0b01;  
constexpr uint16_t SLEWR_5V0_US = 0b10;  
constexpr uint16_t SLEWR_10V0_US = 0b11; 
constexpr uint16_t SLEWR_MASK = 0x0003;  
 
// OFF-state diagnostic current [3:2]
constexpr uint16_t I_DIAG_80UA = (0 << 2);   
constexpr uint16_t I_DIAG_190UA = (1 << 2);  
constexpr uint16_t I_DIAG_720UA = (2 << 2);  
constexpr uint16_t I_DIAG_1250UA = (3 << 2); 
constexpr uint16_t I_DIAG_MASK = 0x000C;     
 
// Open load threshold relative to setpoint [6:4]
constexpr uint16_t OL_TH_DISABLED = (0 << 4); 
constexpr uint16_t OL_TH_1_8 = (1 << 4);      
constexpr uint16_t OL_TH_2_8 = (2 << 4);      
constexpr uint16_t OL_TH_3_8 = (3 << 4);      
constexpr uint16_t OL_TH_4_8 = (4 << 4);      
constexpr uint16_t OL_TH_5_8 = (5 << 4);      
constexpr uint16_t OL_TH_6_8 = (6 << 4);      
constexpr uint16_t OL_TH_7_8 = (7 << 4);      
constexpr uint16_t OL_TH_MASK = 0x0070;       
constexpr uint8_t OL_TH_VALUE_MASK = 0x07;    
constexpr uint8_t OL_TH_SHIFT = 4;            
 
// Fixed open load threshold [12:7]
constexpr uint16_t OL_TH_FIXED_SHIFT = 7;
constexpr uint16_t OL_TH_FIXED_MASK = 0x1F80;
 
constexpr uint16_t OC_DIAG_EN = (1 << 13); 
 
// OFF-state diagnostic control [15:14]
constexpr uint16_t OFF_DIAG_ENABLED = (0 << 14); 
constexpr uint16_t OFF_DIAG_LS_ONLY = (1 << 14); 
constexpr uint16_t OFF_DIAG_HS_ONLY = (2 << 14); 
constexpr uint16_t OFF_DIAG_MASK = 0xC000;       
 
constexpr uint16_t DEFAULT = 0x0003; 
} // namespace CH_CONFIG
 
//==============================================================================
// MODE REGISTER - Channel Mode
//==============================================================================
 
namespace CH_MODE {
constexpr uint16_t OFF = 0x0000;               
constexpr uint16_t ICC_CURRENT_CTRL = 0x0001;  
constexpr uint16_t DIRECT_DRIVE_SPI = 0x0002;  
constexpr uint16_t DIRECT_DRIVE_DRV0 = 0x0003; 
constexpr uint16_t DIRECT_DRIVE_DRV1 = 0x0004; 
constexpr uint16_t FREE_RUN_MEAS = 0x000C;     
constexpr uint16_t MODE_MASK = 0x000F;         
 
constexpr uint16_t DEFAULT = OFF; 
} // namespace CH_MODE
 
//==============================================================================
// TON REGISTER - Direct-Drive On-Time (Per Channel, offset 0x000D)
//==============================================================================
 
namespace TON {
constexpr uint16_t TON_MANT_MASK      = 0x03FFu; 
constexpr uint16_t OLSG_TIMEOUT_SHIFT = 10u;     
constexpr uint16_t OLSG_TIMEOUT_MASK  = 0xFC00u; 
 
constexpr uint16_t DEFAULT = 0x0000;             
 
[[nodiscard]] constexpr uint16_t Build(uint16_t ton_mant, uint8_t olsg_timeout) noexcept {
  return static_cast<uint16_t>((ton_mant & TON_MANT_MASK)
       | ((static_cast<uint16_t>(olsg_timeout) << OLSG_TIMEOUT_SHIFT) & OLSG_TIMEOUT_MASK));
}
} // namespace TON
 
//==============================================================================
// INTEGRATOR_LIMIT REGISTER - ICC Integrator Limit (Per Channel, offset 0x0003)
//==============================================================================
 
namespace INTEGRATOR_LIMIT {
constexpr uint16_t LIM_VALUE_ABS_MASK      = 0x03FFu; 
constexpr uint16_t AUTO_LIM_VALUE_ABS_SHIFT = 10u;
constexpr uint16_t AUTO_LIM_VALUE_ABS_MASK  = 0x7C00u; 
 
constexpr uint16_t DEFAULT = 0x43FFu;
 
[[nodiscard]] constexpr uint16_t Build(uint16_t lim_value_abs,
                                       uint8_t  auto_lim_value_abs) noexcept {
  return static_cast<uint16_t>((lim_value_abs & LIM_VALUE_ABS_MASK)
       | ((static_cast<uint16_t>(auto_lim_value_abs) << AUTO_LIM_VALUE_ABS_SHIFT)
          & AUTO_LIM_VALUE_ABS_MASK));
}
} // namespace INTEGRATOR_LIMIT
 
//==============================================================================
// CTRL_INT_THRESH REGISTER - ICC Integrator Threshold (Per Channel, offset 0x000E)
//==============================================================================
 
namespace CTRL_INT_THRESH {
constexpr uint16_t INT_THRESH_MASK = 0x01FFu; 
constexpr uint16_t INT_THRESH_MAX  = 0x01FFu; 
 
constexpr uint16_t DEFAULT = 0x0003u; 
 
[[nodiscard]] constexpr uint16_t Build(uint16_t int_thresh) noexcept {
  return static_cast<uint16_t>(int_thresh & INT_THRESH_MASK);
}
} // namespace CTRL_INT_THRESH
 
//==============================================================================
// CLK_DIV REGISTER (0x0019) - Central Clock Source and PLL Divider
//==============================================================================
 
namespace CLK_DIV {
constexpr uint16_t EXT_CLK_BIT      = (1u << 15);
constexpr uint16_t PLL_REFDIV_SHIFT = 9u;
constexpr uint16_t PLL_REFDIV_MASK  = 0x7E00u; // 6-bit
constexpr uint16_t PLL_FBDIV_MASK   = 0x01FFu; // 9-bit
 
constexpr uint32_t F_SYS_TARGET_HZ  = 28'000'000UL; 
 
[[nodiscard]] constexpr uint16_t BuildExternalPll(uint8_t pll_refdiv,
                                                  uint16_t pll_fbdiv) noexcept {
  return static_cast<uint16_t>(EXT_CLK_BIT
       | ((static_cast<uint16_t>(pll_refdiv) << PLL_REFDIV_SHIFT) & PLL_REFDIV_MASK)
       | (pll_fbdiv & PLL_FBDIV_MASK));
}
 
constexpr uint16_t INTERNAL_OSC = 0x0000u;
 
struct PllConfig { uint8_t refdiv; uint16_t fbdiv; uint32_t actual_f_sys_hz; };
[[nodiscard]] inline PllConfig CalculatePllFromExternalHz(uint32_t f_clk_hz) noexcept {
  PllConfig cfg{0u, 0u, 0u};
  if (f_clk_hz == 0) return cfg;
  const uint32_t n_plus_1 = (F_SYS_TARGET_HZ + (f_clk_hz / 2)) / f_clk_hz;
  if (n_plus_1 == 0 || n_plus_1 > 512) return cfg;
  cfg.refdiv        = 0u;
  cfg.fbdiv         = static_cast<uint16_t>(n_plus_1 - 1u);
  cfg.actual_f_sys_hz = f_clk_hz * n_plus_1;
  return cfg;
}
} // namespace CLK_DIV
 
//==============================================================================
// SFF_BIST REGISTER (0x003F) - Safe State / BIST Control
//==============================================================================
 
namespace SFF_BIST {
constexpr uint16_t EN   = (1u << 0);
constexpr uint16_t DONE = (1u << 1);
constexpr uint16_t FAIL = (1u << 2);
constexpr uint16_t UERR = (1u << 3);
constexpr uint16_t CERR = (1u << 4);
 
constexpr uint16_t DEFAULT = 0x0000;
} // namespace SFF_BIST
 
//==============================================================================
// PIN_STAT REGISTER (0x0201) - Input Pin Status (read-only)
//==============================================================================
 
namespace PIN_STAT {
constexpr uint16_t DRV0      = (1u << 0);
constexpr uint16_t DRV1      = (1u << 1);
constexpr uint16_t EN        = (1u << 4);
constexpr uint16_t FAULTN    = (1u << 5);
constexpr uint16_t FAULTN_FB = (1u << 6);
} // namespace PIN_STAT
 
//==============================================================================
// FAULT_MASK0/1/2 REGISTERS (0x0016-0x0018) - Contribution to FAULTN
//==============================================================================
 
namespace FAULT_MASK0 {
constexpr uint16_t CH_ERR_MASK     = 0x003Fu;   
constexpr uint16_t EN_PIN_MASK     = (1u << 13);
constexpr uint16_t SUP_NOK_INT_MASK = (1u << 14);
constexpr uint16_t SUP_NOK_EXT_MASK = (1u << 15);
constexpr uint16_t DEFAULT          = 0xC03Fu;
} // namespace FAULT_MASK0
 
namespace FAULT_MASK1 {
constexpr uint16_t CH_WARN_MASK = 0x003Fu;    
constexpr uint16_t COTWARN_MASK = (1u << 12);
constexpr uint16_t COTERR_MASK  = (1u << 13);
constexpr uint16_t CLK_LOW_MASK = (1u << 14);
constexpr uint16_t DEFAULT      = 0x703Fu;
} // namespace FAULT_MASK1
 
namespace FAULT_MASK2 {
constexpr uint16_t VBAT_UV_MASK  = (1u << 0);
constexpr uint16_t VBAT_OV_MASK  = (1u << 1);
constexpr uint16_t VIO_UV_MASK   = (1u << 2);
constexpr uint16_t VIO_OV_MASK   = (1u << 3);
constexpr uint16_t VDD_UV_MASK   = (1u << 4);
constexpr uint16_t VDD_OV_MASK   = (1u << 5);
constexpr uint16_t DATA_ERR_MASK = (1u << 14); 
constexpr uint16_t SPI_WD_MASK   = (1u << 15); 
constexpr uint16_t DEFAULT       = 0xC000u;
} // namespace FAULT_MASK2
 
//==============================================================================
// DITHER CONTROL REGISTER - Per Channel
//==============================================================================
 
namespace DITHER_CTRL {
constexpr uint16_t STEP_SIZE_MASK = 0x0FFF;    
constexpr uint16_t DEEP_DITHER = (1 << 13);    
constexpr uint16_t FAST_MEAS_DITH = (0 << 14); 
constexpr uint16_t FAST_MEAS_HALF = (1 << 14); 
constexpr uint16_t FAST_MEAS_QUAD = (2 << 14); 
constexpr uint16_t FAST_MEAS_MASK = 0xC000;    
 
constexpr uint16_t DEFAULT = 0x0000; 
} // namespace DITHER_CTRL
 
//==============================================================================
// DITHER STEP REGISTER - Per Channel
//==============================================================================
 
namespace DITHER_STEP {
constexpr uint16_t FLAT_MASK = 0x00FF;  
constexpr uint16_t STEPS_SHIFT = 8;     
constexpr uint16_t STEPS_MASK = 0xFF00; 
 
constexpr uint16_t DEFAULT = 0x0000; 
} // namespace DITHER_STEP
 
//==============================================================================
// DITHER HELPER FUNCTIONS
//==============================================================================
 
//==============================================================================
// DITHER_CLK_DIV REGISTER - Per Channel  (offset 0x0004 within channel bank)
//==============================================================================
 
namespace DITHER_CLK_DIV {
constexpr uint16_t MANT_MASK         = 0x03FFu;       
constexpr uint16_t EXP_SHIFT         = 10u;           
constexpr uint16_t EXP_MASK          = 0x3C00u;       
constexpr uint8_t  EXP_VALUE_MASK    = 0x0Fu;         
constexpr uint16_t DITHER_PWM_SYNC_EN_BIT      = (1u << 14);
constexpr uint16_t DITHER_SETPOINT_SYNC_EN_BIT = (1u << 15);
 
constexpr uint32_t F_SYS_HZ          = 28'000'000UL;  
constexpr float    F_SYS_PERIOD_US   = 1.0F / 28.0F;  
 
struct ClkDivConfig {
  uint16_t mantissa;                  
  uint8_t  exponent;                  
  bool     dither_pwm_sync_en;        
  bool     dither_setpoint_sync_en;   
 
  [[nodiscard]] constexpr float CalculateTrefClkUs() const noexcept {
    return static_cast<float>(mantissa)
         * static_cast<float>(1ULL << exponent)
         * F_SYS_PERIOD_US;
  }
 
  [[nodiscard]] constexpr uint16_t ToRegister() const noexcept {
    return (mantissa & MANT_MASK)
         | ((static_cast<uint16_t>(exponent) & EXP_VALUE_MASK) << EXP_SHIFT)
         | (dither_pwm_sync_en      ? DITHER_PWM_SYNC_EN_BIT      : 0u)
         | (dither_setpoint_sync_en ? DITHER_SETPOINT_SYNC_EN_BIT : 0u);
  }
};
 
[[nodiscard]] inline ClkDivConfig CalculateFromTrefClkUs(float t_ref_clk_us) noexcept {
  ClkDivConfig best{};
  best.mantissa = 1;
  best.exponent = 0;
  best.dither_pwm_sync_en      = false;
  best.dither_setpoint_sync_en = false;
 
  if (t_ref_clk_us <= 0.0F) return best;
 
  float best_err = 1e30F;
  for (uint8_t exp = 0; exp <= 15; ++exp) {
    const float divisor = static_cast<float>(1ULL << exp) * F_SYS_PERIOD_US;
    const float mant_f  = t_ref_clk_us / divisor;
    if (mant_f < 1.0F)    continue;       // mantissa would round to 0
    if (mant_f > 1023.0F) continue;       // out of 10-bit range
    const uint16_t mant = static_cast<uint16_t>(mant_f + 0.5F);
    const float    actual = static_cast<float>(mant) * divisor;
    const float    err    = std::fabs(actual - t_ref_clk_us);
    if (err < best_err) {
      best_err = err;
      best.mantissa = mant;
      best.exponent = exp;
    }
  }
  return best;
}
 
}  // namespace DITHER_CLK_DIV
 
namespace DITHER {
constexpr float F_SYS_HZ = 28'000'000.0F;                
constexpr float DEFAULT_T_REF_CLK_US = 1.0F / 28.0F;     
 
struct DitherConfig {
  uint16_t step_size; 
  uint8_t num_steps;  
  uint8_t flat_steps; 
 
  [[nodiscard]] constexpr float CalculateAmplitudeMa(bool parallel_mode = false) const noexcept {
    uint32_t max_current = parallel_mode ? 4000 : 2000;
    float amplitude = (static_cast<float>(num_steps) * static_cast<float>(step_size) *
                       static_cast<float>(max_current)) /
                      32767.0F;
    return amplitude;
  }
 
  [[nodiscard]] constexpr float CalculatePeriodUs(
      float t_ref_clk_us = DEFAULT_T_REF_CLK_US) const noexcept {
    return (4.0F * static_cast<float>(num_steps) + 2.0F * static_cast<float>(flat_steps)) *
           t_ref_clk_us;
  }
};
 
[[nodiscard]] inline DitherConfig CalculateFromAmplitudeFrequency(
    float amplitude_ma,  // Current amplitude in milliamperes
    float frequency_hz,  // Dither frequency in hertz
    bool parallel_mode = false,
    float t_ref_clk_us = DEFAULT_T_REF_CLK_US) noexcept {
 
  DitherConfig config{};
 
  // Calculate desired period from frequency
  float period_us = 1'000'000.0F / frequency_hz;
 
  // Calculate dither period from formula: T_dither = [4×STEPS + 2×FLAT] × t_ref_clk
  // Use reasonable defaults: num_steps = 16, flat_steps = 2
  constexpr uint8_t default_steps = 16;
  constexpr uint8_t default_flat = 2;
 
  float calculated_period = (4.0F * default_steps + 2.0F * default_flat) * t_ref_clk_us;
 
  // If calculated period doesn't match desired, adjust steps
  if (calculated_period < period_us * 0.9F || calculated_period > period_us * 1.1F) {
    // Adjust num_steps to get closer to desired period
    float target_steps = (period_us / t_ref_clk_us - 2.0F * default_flat) / 4.0F;
    // Clamp to valid range before casting to uint8_t
    target_steps = std::max(1.0F, target_steps);
    target_steps = std::min(255.0F, target_steps);
    config.num_steps = static_cast<uint8_t>(std::lround(target_steps));
  } else {
    config.num_steps = default_steps;
  }
 
  config.flat_steps = default_flat;
 
  // Calculate step_size from amplitude formula: I_dither = STEPS × STEP_SIZE × 2A / 32767
  uint32_t max_current = parallel_mode ? 4000 : 2000;
  float step_size_f = (amplitude_ma * 32767.0F) /
                      (static_cast<float>(config.num_steps) * static_cast<float>(max_current));
 
  config.step_size = static_cast<uint16_t>(std::lround(step_size_f));
  config.step_size = std::min(config.step_size, static_cast<uint16_t>(DITHER_CTRL::STEP_SIZE_MASK));
 
  return config;
}
} // namespace DITHER
 
//==============================================================================
// VBAT THRESHOLD HELPER FUNCTIONS
//==============================================================================
 
namespace VBAT_THRESHOLD {
constexpr float LSB_VOLTAGE = 0.16208F; 
constexpr float MIN_VOLTAGE = 0.0F;     
constexpr float MAX_VOLTAGE = 41.4F;    
 
[[nodiscard]] constexpr uint8_t CalculateFromVoltage(float voltage_volts) noexcept {
  if (voltage_volts < MIN_VOLTAGE || voltage_volts > MAX_VOLTAGE) {
    return 0;
  }
  float register_value_f = voltage_volts / LSB_VOLTAGE;
  // Clamp to valid range before casting to uint8_t
  register_value_f = std::max(0.0F, register_value_f);
  register_value_f = std::min(255.0F, register_value_f);
  return static_cast<uint8_t>(std::lround(register_value_f)); // Round
}
 
[[nodiscard]] constexpr float CalculateVoltage(uint8_t register_value) noexcept {
  return static_cast<float>(register_value) * LSB_VOLTAGE;
}
} // namespace VBAT_THRESHOLD
 
//==============================================================================
// VOLTAGE FEEDBACK HELPER FUNCTIONS
//==============================================================================
 
namespace VOLTAGE_FEEDBACK {
// VIO/VDD conversion constants (from FB_VOLTAGE1)
constexpr float VIO_VDD_LSB_VOLTAGE = 0.0034534F; 
constexpr uint32_t VIO_VDD_MASK = 0x7FF;          
constexpr uint32_t VDD_SHIFT = 11;                
 
// VBAT conversion constants (from FB_VOLTAGE2)
constexpr float VBAT_MAX_VOLTAGE = 41.47F; 
constexpr uint32_t VBAT_MAX_COUNT = 2047;  
constexpr uint32_t VBAT_MASK = 0x7FF;      
constexpr uint32_t VBAT_SHIFT = 11;        
 
[[nodiscard]] constexpr uint16_t ExtractVioMillivolts(uint32_t register_value) noexcept {
  uint32_t vio_raw = (register_value >> 0) & VIO_VDD_MASK; // Bits [10:0]
  float vio_volts = static_cast<float>(vio_raw) * VIO_VDD_LSB_VOLTAGE;
  return static_cast<uint16_t>(std::lround(vio_volts * 1000.0F)); // Convert to mV and round
}
 
[[nodiscard]] constexpr uint16_t ExtractVddMillivolts(uint32_t register_value) noexcept {
  uint32_t vdd_raw = (register_value >> VDD_SHIFT) & VIO_VDD_MASK; // Bits [21:11]
  float vdd_volts = static_cast<float>(vdd_raw) * VIO_VDD_LSB_VOLTAGE;
  return static_cast<uint16_t>(std::lround(vdd_volts * 1000.0F)); // Convert to mV and round
}
 
[[nodiscard]] constexpr uint16_t ExtractVbatMillivolts(uint32_t register_value) noexcept {
  uint32_t vbat_raw = (register_value >> VBAT_SHIFT) & VBAT_MASK; // Bits [21:11]
  float vbat_volts =
      (static_cast<float>(vbat_raw) / static_cast<float>(VBAT_MAX_COUNT)) * VBAT_MAX_VOLTAGE;
  return static_cast<uint16_t>(std::lround(vbat_volts * 1000.0F)); // Convert to mV and round
}
 
[[nodiscard]] constexpr uint16_t ExtractTemperatureRaw(uint32_t register_value) noexcept {
  return static_cast<uint16_t>((register_value >> 0) & VBAT_MASK); // Bits [10:0]
}
 
[[nodiscard]] constexpr float TemperatureCelsiusFromRaw(uint16_t temp_value) noexcept {
  constexpr float K_VPERLSB  = 0.000593F;   // V per LSB
  constexpr float K_OFFSET_V = 0.819F;      // V offset
  constexpr float K_SLOPE_VPERC = -0.0016F; // V per \u00b0C (negative slope)
  const float v = static_cast<float>(temp_value & 0x7FFu) * K_VPERLSB - K_OFFSET_V;
  return v / K_SLOPE_VPERC;
}
 
[[nodiscard]] constexpr float TemperatureCelsiusFromFbVoltage2(uint32_t register_value) noexcept {
  return TemperatureCelsiusFromRaw(ExtractTemperatureRaw(register_value));
}
} // namespace VOLTAGE_FEEDBACK
 
//==============================================================================
// FB_IMIN_IMAX DECODER - Per-Channel Signed Min/Max Load Current
//==============================================================================
 
namespace FB_IMIN_IMAX {
constexpr uint32_t IMIN_SHIFT = 0u;
constexpr uint32_t IMIN_MASK  = 0x3FFu;      // 10-bit
constexpr uint32_t IMAX_SHIFT = 10u;
constexpr uint32_t IMAX_MASK  = 0x3FFu;      // 10-bit
constexpr int32_t  FULL_SCALE_mA = 4000;     // 4 A full scale
constexpr int32_t  FULL_SCALE_COUNT = 511;   // 2^9 - 1
 
[[nodiscard]] constexpr int16_t SignExtend10(uint32_t v) noexcept {
  const uint32_t masked = v & 0x3FFu;
  return static_cast<int16_t>((masked & 0x200u) ? (masked | 0xFC00u) : masked);
}
 
[[nodiscard]] constexpr int16_t ExtractIMin(uint32_t raw) noexcept {
  return SignExtend10((raw >> IMIN_SHIFT) & IMIN_MASK);
}
 
[[nodiscard]] constexpr int16_t ExtractIMax(uint32_t raw) noexcept {
  return SignExtend10((raw >> IMAX_SHIFT) & IMAX_MASK);
}
 
[[nodiscard]] constexpr int32_t FieldToMilliamps(int16_t field) noexcept {
  // I [mA] = field * 4000 / 511 (round toward zero)
  return (static_cast<int32_t>(field) * FULL_SCALE_mA) / FULL_SCALE_COUNT;
}
 
[[nodiscard]] constexpr int32_t IMin_mA(uint32_t raw) noexcept {
  return FieldToMilliamps(ExtractIMin(raw));
}
 
[[nodiscard]] constexpr int32_t IMax_mA(uint32_t raw) noexcept {
  return FieldToMilliamps(ExtractIMax(raw));
}
} // namespace FB_IMIN_IMAX
 
//==============================================================================
// PER-CHANNEL FEEDBACK HELPERS — FB_DC, FB_I_AVG, FB_VBAT
//==============================================================================
 
namespace FB_FEEDBACK {
 
constexpr uint32_t MANT11_MASK     = 0x7FFu;          
constexpr uint32_t TP_MANT_SHIFT   = 0u;              
constexpr uint32_t TO_MANT_SHIFT   = 11u;             
constexpr uint32_t I_AVG_MANT_SHIFT  = 0u;            
constexpr uint32_t VBAT_MANT_SHIFT   = 0u;            
constexpr uint32_t MEAS_EXP_SHIFT    = 12u;           
constexpr uint32_t MEAS_EXP_MASK     = 0xFu;          
 
constexpr float I_AVG_FULL_SCALE_AMPS = 4.0f;         
constexpr float VBAT_FULL_SCALE_VOLTS = 41.47f;       
 
[[nodiscard]] constexpr int16_t SignExtend11(uint32_t v) noexcept {
  const uint32_t masked = v & MANT11_MASK;
  return static_cast<int16_t>((masked & 0x400u) ? (masked | 0xFFFFF800u) : masked);
}
 
[[nodiscard]] constexpr uint16_t ExtractTpMant(uint32_t fb_dc_raw) noexcept {
  return static_cast<uint16_t>((fb_dc_raw >> TP_MANT_SHIFT) & MANT11_MASK);
}
 
[[nodiscard]] constexpr uint16_t ExtractToMant(uint32_t fb_dc_raw) noexcept {
  return static_cast<uint16_t>((fb_dc_raw >> TO_MANT_SHIFT) & MANT11_MASK);
}
 
[[nodiscard]] constexpr int16_t ExtractIAvgMant(uint32_t fb_i_avg_raw) noexcept {
  return SignExtend11((fb_i_avg_raw >> I_AVG_MANT_SHIFT) & MANT11_MASK);
}
 
[[nodiscard]] constexpr uint8_t ExtractMeasExp(uint32_t fb_vbat_or_iavg_raw) noexcept {
  return static_cast<uint8_t>((fb_vbat_or_iavg_raw >> MEAS_EXP_SHIFT) & MEAS_EXP_MASK);
}
 
[[nodiscard]] constexpr float ComputeDutyCycle(uint32_t fb_dc_raw) noexcept {
  const uint16_t tp = ExtractTpMant(fb_dc_raw);
  if (tp == 0) return 0.0f;
  return static_cast<float>(ExtractToMant(fb_dc_raw)) / static_cast<float>(tp);
}
 
constexpr uint16_t kMinValidTpMant = 64u;
 
[[nodiscard]] constexpr bool HasValidMeasurementWindow(uint32_t fb_dc_raw) noexcept {
  return ExtractTpMant(fb_dc_raw) >= kMinValidTpMant;
}
 
[[nodiscard]] inline int32_t ComputeAverageCurrent_mA(uint32_t fb_i_avg_raw,
                                                      uint32_t fb_dc_raw) noexcept {
  const uint16_t tp = ExtractTpMant(fb_dc_raw);
  if (tp == 0) return 0;
  const int16_t i_mant = ExtractIAvgMant(fb_i_avg_raw);
  // Iavg [A]  = 4 A × I_AVG_MANT / TP_MANT
  // Iavg [mA] = 4000 × I_AVG_MANT / TP_MANT
  return static_cast<int32_t>(
      (static_cast<int32_t>(i_mant) * 4000) / static_cast<int32_t>(tp));
}
 
[[nodiscard]] inline uint32_t ComputeVbatChannel_mV(uint32_t fb_vbat_raw,
                                                    uint32_t fb_dc_raw) noexcept {
  const uint16_t tp = ExtractTpMant(fb_dc_raw);
  if (tp == 0) return 0;
  const uint16_t vbat_mant = static_cast<uint16_t>(
      (fb_vbat_raw >> VBAT_MANT_SHIFT) & MANT11_MASK);
  // VBAT [V]  = 41.47 V × VBAT_AVG_MANT / TP_MANT
  // VBAT [mV] = 41470  × VBAT_AVG_MANT / TP_MANT
  return (static_cast<uint32_t>(vbat_mant) * 41470u)
       / static_cast<uint32_t>(tp);
}
 
}  // namespace FB_FEEDBACK
 
//==============================================================================
// FB_I_AVG_s16 REGISTER (Per Channel, offset 0x0204) - High-res signed average
//==============================================================================
 
namespace FB_I_AVG_s16 {
constexpr uint32_t I_AVG_MASK         = 0x0001FFFFu; 
constexpr uint32_t I_AVG_SIGN_BIT     = (1u << 16);
constexpr uint32_t TIME_STAMP_SHIFT   = 20u;
constexpr uint32_t TIME_STAMP_MASK    = 0x00300000u; 
 
constexpr int32_t  FULL_SCALE_mA      = 4000;
constexpr int32_t  FULL_SCALE_COUNT   = 65535;
 
[[nodiscard]] constexpr int32_t SignExtend17(uint32_t raw17) noexcept {
  const uint32_t m = raw17 & I_AVG_MASK;
  return (m & I_AVG_SIGN_BIT) ? static_cast<int32_t>(m | 0xFFFE0000u)
                              : static_cast<int32_t>(m);
}
 
constexpr uint32_t SETTLING_CODE = 0x8000u;
 
[[nodiscard]] constexpr bool IsSettlingFrame(uint32_t reply_22bit) noexcept {
  return (reply_22bit & I_AVG_MASK) == SETTLING_CODE;
}
 
[[nodiscard]] constexpr int32_t ToMilliamps(uint32_t reply_22bit) noexcept {
  const int32_t s = SignExtend17(reply_22bit);
  return (s * FULL_SCALE_mA) / FULL_SCALE_COUNT;
}
 
[[nodiscard]] constexpr uint8_t ExtractTimestamp(uint32_t reply_22bit) noexcept {
  return static_cast<uint8_t>((reply_22bit & TIME_STAMP_MASK) >> TIME_STAMP_SHIFT);
}
} // namespace FB_I_AVG_s16
 
//==============================================================================
// FB_INT_THRESH REGISTER (Per Channel, offset 0x0205) - Integrator Threshold Readback
//==============================================================================
 
namespace FB_INT_THRESH {
constexpr uint32_t INT_THRESH_MASK = 0x0000FFFFu;
 
[[nodiscard]] constexpr int16_t Extract(uint32_t reply_22bit) noexcept {
  return static_cast<int16_t>(reply_22bit & INT_THRESH_MASK);
}
} // namespace FB_INT_THRESH
 
//==============================================================================
// FB_PERIOD_MIN_MAX REGISTER (Per Channel, offset 0x0206) - PWM Period Bounds
//==============================================================================
 
namespace FB_PERIOD_MIN_MAX {
constexpr uint32_t PERIOD_MIN_MASK  = 0x000003FFu;
constexpr uint32_t PERIOD_MAX_SHIFT = 10u;
constexpr uint32_t PERIOD_MAX_MASK  = 0x000FFC00u;
constexpr uint32_t TICK_CYCLES      = 256u;
 
[[nodiscard]] constexpr uint32_t ToMicroseconds(uint16_t raw_count) noexcept {
  // T_us = count * 256 / 28 = count * 64 / 7 (exact)
  return (static_cast<uint32_t>(raw_count) * TICK_CYCLES) / 28u;
}
 
[[nodiscard]] constexpr uint16_t ExtractMin(uint32_t reply_22bit) noexcept {
  return static_cast<uint16_t>(reply_22bit & PERIOD_MIN_MASK);
}
[[nodiscard]] constexpr uint16_t ExtractMax(uint32_t reply_22bit) noexcept {
  return static_cast<uint16_t>((reply_22bit & PERIOD_MAX_MASK) >> PERIOD_MAX_SHIFT);
}
 
[[nodiscard]] constexpr uint32_t PeriodMinMicroseconds(uint32_t reply_22bit) noexcept {
  return ToMicroseconds(ExtractMin(reply_22bit));
}
[[nodiscard]] constexpr uint32_t PeriodMaxMicroseconds(uint32_t reply_22bit) noexcept {
  return ToMicroseconds(ExtractMax(reply_22bit));
}
} // namespace FB_PERIOD_MIN_MAX
 
//==============================================================================
// HELPER ENUMERATIONS
//==============================================================================
 
enum class Channel : uint8_t {
  CH0 = 0, 
  CH1 = 1, 
  CH2 = 2, 
  CH3 = 3, 
  CH4 = 4, 
  CH5 = 5, 
 
  COUNT = 6 
};
 
enum class ChannelMode : uint8_t {
  OFF = 0x0,               
  ICC = 0x1,               
  DIRECT_DRIVE_SPI = 0x2,  
  DIRECT_DRIVE_DRV0 = 0x3, 
  DIRECT_DRIVE_DRV1 = 0x4, 
  FREE_RUN_MEAS = 0xC      
};
 
enum class SlewRate : uint8_t {
  SLOW_1V0_US = 0,    
  MEDIUM_2V5_US = 1,  
  FAST_5V0_US = 2,    
  FASTEST_10V0_US = 3 
};
 
enum class DiagCurrent : uint8_t {
  I_80UA = 0,  
  I_190UA = 1, 
  I_720UA = 2, 
  I_1250UA = 3 
};
 
enum class ParallelPair : uint8_t {
  NONE = 0,    
  CH0_CH3 = 1, 
  CH1_CH2 = 2, 
  CH4_CH5 = 3  
};
 
//==============================================================================
// ADDRESS CALCULATION HELPERS
//==============================================================================
 
[[nodiscard]] constexpr uint16_t GetChannelBase(Channel channel) noexcept {
  switch (channel) {
  case Channel::CH0:
    return ChannelBase::CH0;
  case Channel::CH1:
    return ChannelBase::CH1;
  case Channel::CH2:
    return ChannelBase::CH2;
  case Channel::CH3:
    return ChannelBase::CH3;
  case Channel::CH4:
    return ChannelBase::CH4;
  case Channel::CH5:
    return ChannelBase::CH5;
  default:
    return 0x0000; // Invalid channel
  }
}
 
[[nodiscard]] constexpr uint16_t GetChannelRegister(Channel channel, uint16_t offset) noexcept {
  return GetChannelBase(channel) + offset;
}
 
enum class ExpectedReply : uint8_t {
  Bits16, 
  Bits22  
};
 
[[nodiscard]] constexpr ExpectedReply ExpectedReplyFor(uint16_t address) noexcept {
  if (address == CentralReg::FB_STAT || address == CentralReg::FB_VOLTAGE1 ||
      address == CentralReg::FB_VOLTAGE2) {
    return ExpectedReply::Bits22;
  }
  /* Per-channel feedback bank: base (0x20..0x70) + 0x200, offsets +0..+6.
   * Every register in the bank answers in reply mode 01B.
   *
   * Datasheet Rev 1.2 §5.3.3.14–5.3.3.23 draws each of these with a bits-21:16
   * row and a six-hex-digit reset value ("00 0000H"), the convention this
   * document uses for 22-bit replies; true 16-bit registers (FB_FRZ 0x0007,
   * FB_UPD 0x0008) stop at bit 15 and show "0000H". FB_I_AVG_s16 (+4) carries
   * TIME_STAMP at 21:20 and FB_INT_THRESH (+5) reserves 21:16, so both are
   * 22-bit. Listing them as 16-bit made every read of those two fail the
   * reply-width check, burn its retry, and return an error — which is why the
   * Iavg16 path looked unusable rather than merely unsuitable for control. */
  if (address > CentralReg::FB_VOLTAGE2) {
    const uint16_t base = static_cast<uint16_t>((address - 0x0200U) & 0x00F0U);
    const uint16_t offset = static_cast<uint16_t>(address & 0x000FU);
    const bool in_channel_bank =
        (address >= 0x0220U) && (address <= 0x0276U) && (base >= 0x0020U) &&
        (base <= 0x0070U) && (offset <= 0x0006U);
    if (in_channel_bank) {
      return ExpectedReply::Bits22;
    }
  }
  return ExpectedReply::Bits16;
}
 
[[nodiscard]] constexpr uint8_t ToIndex(Channel ch) noexcept {
  return static_cast<uint8_t>(ch);
}
 
//==============================================================================
// ENUM TO_STRING HELPERS
//==============================================================================
 
[[nodiscard]] inline const char* ToString(ChannelMode mode) noexcept {
  switch (mode) {
  case ChannelMode::OFF:
    return "OFF";
  case ChannelMode::ICC:
    return "ICC";
  case ChannelMode::DIRECT_DRIVE_SPI:
    return "DIRECT_DRIVE_SPI";
  case ChannelMode::DIRECT_DRIVE_DRV0:
    return "DIRECT_DRIVE_DRV0";
  case ChannelMode::DIRECT_DRIVE_DRV1:
    return "DIRECT_DRIVE_DRV1";
  case ChannelMode::FREE_RUN_MEAS:
    return "FREE_RUN_MEAS";
  default:
    return "UNKNOWN";
  }
}
 
[[nodiscard]] inline const char* ToString(SlewRate rate) noexcept {
  switch (rate) {
  case SlewRate::SLOW_1V0_US:
    return "SLOW_1V0_US";
  case SlewRate::MEDIUM_2V5_US:
    return "MEDIUM_2V5_US";
  case SlewRate::FAST_5V0_US:
    return "FAST_5V0_US";
  case SlewRate::FASTEST_10V0_US:
    return "FASTEST_10V0_US";
  default:
    return "UNKNOWN";
  }
}
 
[[nodiscard]] inline const char* ToString(DiagCurrent current) noexcept {
  switch (current) {
  case DiagCurrent::I_80UA:
    return "I_80UA";
  case DiagCurrent::I_190UA:
    return "I_190UA";
  case DiagCurrent::I_720UA:
    return "I_720UA";
  case DiagCurrent::I_1250UA:
    return "I_1250UA";
  default:
    return "UNKNOWN";
  }
}
 
[[nodiscard]] inline const char* ToString(ParallelPair pair) noexcept {
  switch (pair) {
  case ParallelPair::NONE:
    return "NONE";
  case ParallelPair::CH0_CH3:
    return "CH0_CH3";
  case ParallelPair::CH1_CH2:
    return "CH1_CH2";
  case ParallelPair::CH4_CH5:
    return "CH4_CH5";
  default:
    return "UNKNOWN";
  }
}
 
[[nodiscard]] inline const char* ToString(Channel channel) noexcept {
  switch (channel) {
  case Channel::CH0:
    return "CH0";
  case Channel::CH1:
    return "CH1";
  case Channel::CH2:
    return "CH2";
  case Channel::CH3:
    return "CH3";
  case Channel::CH4:
    return "CH4";
  case Channel::CH5:
    return "CH5";
  default:
    return "UNKNOWN";
  }
}
 
[[nodiscard]] constexpr bool IsValidChannel(Channel ch) noexcept {
  return ToIndex(ch) < static_cast<uint8_t>(Channel::COUNT);
}
 
//==============================================================================
// CRC CALCULATION (SAE J1850)
//==============================================================================
 
[[nodiscard]] constexpr uint8_t CalculateCrc8J1850(const uint8_t* data,
                                                   std::size_t length) noexcept {
  constexpr uint8_t POLY = 0x1D;
  uint8_t crc = 0xFF;
 
  for (std::size_t i = 0; i < length; ++i) {
    crc ^= data[i];
    for (uint8_t bit = 0; bit < 8; ++bit) {
      if ((crc & 0x80) != 0) {
        crc = (crc << 1) ^ POLY;
      } else {
        crc = (crc << 1);
      }
    }
  }
 
  return crc ^ 0xFF;
}
 
[[nodiscard]] inline uint8_t CalculateFrameCrc(const tle92466ed::SPIFrame& frame) noexcept {
  static_assert(__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__,
                "CRC byte sequence (datasheet §5.1.2) assumes little-endian frame storage");
  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast) - Required for hardware register byte access
  const auto* bytes = reinterpret_cast<const uint8_t*>(&frame);
  // Calculate CRC on bytes 0-2 (excluding CRC byte itself at position 3)
  return CalculateCrc8J1850(bytes, 3);
}
 
[[nodiscard]] inline bool VerifyFrameCrc(const tle92466ed::SPIFrame& frame) noexcept {
  tle92466ed::SPIFrame temp = frame;
  uint8_t received_crc = temp.tx_fields.crc;
  temp.tx_fields.crc = 0;
  uint8_t calculated_crc{}; // Initialize to zero
  calculated_crc = CalculateFrameCrc(temp);
  return (received_crc == calculated_crc);
}
 
//==============================================================================
// PHASE 2 / 4 / 5 / 6 - SHARED ENUMS AND STRUCTS
//==============================================================================
 
enum class ClockSource : uint8_t {
  InternalOscillator, 
  ExternalClockPll    
};
 
enum class VioLevel : uint8_t { V3_3 = 0, V5_0 = 1 };
 
struct SupplyVoltages {
  uint16_t vbat_mV{0};          
  uint16_t vio_mV{0};           
  uint16_t vdd_mV{0};           
  float    temperature_c{0.0F}; 
};
 
enum class OperationState : uint8_t {
  Reset,        
  Config,       
  Mission,      
  CriticalFault 
};
 
enum class FastMeasureMode : uint8_t {
  FullPeriod    = 0, 
  HalfPeriod    = 1, 
  QuarterPeriod = 2  
};
 
struct DitherSetup {
  float           amplitude_mA{0.0F};      
  float           frequency_Hz{0.0F};      
  bool            sync_with_pwm{false};    
  bool            sync_with_setpoint{false}; 
  bool            deep_dither{false};      
  FastMeasureMode fast_measure{FastMeasureMode::FullPeriod}; 
};
 
struct BistResult {
  bool done{false};                  
  bool pass{false};                  
  bool uncorrectable_reg_err{false};
  bool correctable_reg_err{false};
  uint16_t raw{0};                   
};
 
struct PinStatus {
  bool drv0{false};           
  bool drv1{false};           
  bool en{false};             
  bool faultn_driver{false};  
  bool faultn_fb{false};      
  uint16_t raw{0};            
};
 
enum class MaskableFault : uint32_t {
  // FAULT_MASK0 — per-channel error contribution
  Ch0Error          = (0u << 24) | (1u << 0),  
  Ch1Error          = (0u << 24) | (1u << 1),  
  Ch2Error          = (0u << 24) | (1u << 2),  
  Ch3Error          = (0u << 24) | (1u << 3),  
  Ch4Error          = (0u << 24) | (1u << 4),  
  Ch5Error          = (0u << 24) | (1u << 5),  
  EnPin             = (0u << 24) | (1u << 13), 
  SupplyNokInternal = (0u << 24) | (1u << 14), 
  SupplyNokExternal = (0u << 24) | (1u << 15), 
  // FAULT_MASK1 — per-channel warning and system warnings
  Ch0Warning        = (1u << 24) | (1u << 0),  
  Ch1Warning        = (1u << 24) | (1u << 1),  
  Ch2Warning        = (1u << 24) | (1u << 2),  
  Ch3Warning        = (1u << 24) | (1u << 3),  
  Ch4Warning        = (1u << 24) | (1u << 4),  
  Ch5Warning        = (1u << 24) | (1u << 5),  
  CentralOtWarning  = (1u << 24) | (1u << 12), 
  CentralOtError    = (1u << 24) | (1u << 13), 
  ClockLow          = (1u << 24) | (1u << 14), 
  // FAULT_MASK2 — supply UV/OV + POR-enabled DATA_ERR / SPI_WD
  VbatUv            = (2u << 24) | (1u << 0),  
  VbatOv            = (2u << 24) | (1u << 1),  
  VioUv             = (2u << 24) | (1u << 2),  
  VioOv             = (2u << 24) | (1u << 3),  
  VddUv             = (2u << 24) | (1u << 4),  
  VddOv             = (2u << 24) | (1u << 5),  
  DataErr           = (2u << 24) | (1u << 14), 
  SpiWatchdog       = (2u << 24) | (1u << 15), 
};
 
[[nodiscard]] constexpr uint8_t  FaultMaskIndex(MaskableFault f) noexcept {
  return static_cast<uint8_t>((static_cast<uint32_t>(f) >> 24) & 0x3u);
}
[[nodiscard]] constexpr uint16_t FaultMaskBit(MaskableFault f) noexcept {
  return static_cast<uint16_t>(static_cast<uint32_t>(f) & 0xFFFFu);
}
 
struct ChannelFeedback {
  int32_t  avg_current_mA{0};          
  uint16_t duty_cycle_permyriad{0};    
  uint32_t avg_vbat_mV{0};             
  int32_t  imin_mA{0};                 
  int32_t  imax_mA{0};                 
  uint32_t period_min_us{0};           
  uint32_t period_max_us{0};           
  int16_t  int_thresh_seed{0};         
  uint8_t  period_seq{0};              
  uint8_t  quad_seq{0};                
};
 
struct SupplyMonitorSelfTestResult {
  bool uv_ov_swap_ok{false};
  bool v1v5_uv_ok{false};
  bool v1v5_ov_ok{false};
  bool ot_test_ok{false};
  bool overall_pass{false};
};
 
} // namespace tle92466ed