tle92466ed_spi_interface.hpp

Go to the documentation of this file.

 
#pragma once
#include <cstdarg>
#include <cstdint>
#include <span>
 
#include "tle92466ed_expected.hpp"
 
namespace tle92466ed {
 
enum class CommError : uint8_t {
  None = 0,         
  BusError,         
  Timeout,          
  InvalidParameter, 
  TransferError,    
  HardwareNotReady, 
  BufferOverflow,   
  CRCError,         
  NoReply,
  UnknownError 
};
 
enum class CtrlPin : uint8_t {
  RESN,  
  EN,    
  FAULTN 
};
 
enum class GpioSignal : uint8_t {
  INACTIVE = 0, 
  ACTIVE = 1    
};
 
enum class LogLevel : uint8_t {
  Error = 0, 
  Warn,      
  Info,      
  Debug,     
  Verbose    
};
 
template <typename T>
using CommResult = tle::expected<T, CommError>;
 
struct SPIConfig {
  uint32_t frequency{1'000'000}; 
  uint8_t mode{1};               
  bool msb_first{true};          
  uint32_t timeout_ms{100};      
};
 
//==============================================================================
// SPI FRAME STRUCTURES (32-BIT)
//==============================================================================
 
union SPIFrame {
  uint32_t word; 
 
  struct {
    uint32_t data : 16;   
    uint32_t rw : 1;      
    uint32_t address : 7; 
    uint32_t crc : 8;     
  } tx_fields;
 
  struct {
    uint32_t _data_low : 16;   
    uint32_t _field_16 : 1;    
    uint32_t _field_17_21 : 5; 
    uint32_t reply_mode : 2;   
    uint32_t crc : 8;          
  } rx_common;
 
  struct {
    uint32_t data : 16;      
    uint32_t rw_echo : 1;    
    uint32_t status : 5;     
    uint32_t reply_mode : 2; 
    uint32_t crc : 8;        
  } rx_16bit;
 
  struct {
    uint32_t data : 22;      
    uint32_t reply_mode : 2; 
    uint32_t crc : 8;        
  } rx_22bit;
 
  struct {
    uint32_t fault_flags : 8; 
    uint32_t _reserved : 8;   
    uint32_t _reserved2 : 1;  
    uint32_t _reserved3 : 5;  
    uint32_t reply_mode : 2;  
    uint32_t _dont_care : 8;  
  } rx_fault;
 
  [[nodiscard]] static constexpr SPIFrame MakeRead(uint16_t addr) noexcept {
    SPIFrame frame{};
    frame.tx_fields.rw = 0;                 // Read (bit 16)
    frame.tx_fields.address = 0;            // Bits 23:17 are don't care for reads
    frame.tx_fields.data = (addr & 0xFFFF); // 16-bit address in bits 15:0 (full 16-bit address)
    frame.tx_fields.crc = 0;                // CRC calculated separately
    return frame;
  }
 
  [[nodiscard]] static constexpr SPIFrame MakeWrite(uint16_t addr, uint16_t data) noexcept {
    SPIFrame frame{};
    frame.tx_fields.rw = 1;                  // Write (bit 16)
    frame.tx_fields.address = (addr) & 0x7F; // Lower 7 bits [23:17]
    frame.tx_fields.data = data;             // Data in bits [15:0]
    frame.tx_fields.crc = 0;                 // CRC calculated separately
    return frame;
  }
};
 
static_assert(sizeof(SPIFrame) == 4, "SPIFrame must be exactly 4 bytes");
 
struct CriticalFaultFlags {
  bool wd_ref_clk_missing : 1; 
  bool dig_clk_too_fast : 1;   
  bool dig_clk_too_slow : 1;   
  bool clk_too_fast : 1;       
  bool clk_too_slow : 1;       
  bool adc_bandgap_ok : 1;     
  bool supply_2v5_ok : 1;      
  bool supply_1v5_ok : 1;      
 
  [[nodiscard]] static constexpr CriticalFaultFlags Extract(const SPIFrame& frame) noexcept {
    CriticalFaultFlags flags{};
    uint8_t fault_byte = frame.rx_fault.fault_flags;
    flags.wd_ref_clk_missing = (fault_byte & 0x01) != 0;
    flags.dig_clk_too_fast = (fault_byte & 0x02) != 0;
    flags.dig_clk_too_slow = (fault_byte & 0x04) != 0;
    flags.clk_too_fast = (fault_byte & 0x08) != 0;
    flags.clk_too_slow = (fault_byte & 0x10) != 0;
    flags.adc_bandgap_ok = (fault_byte & 0x20) != 0;
    flags.supply_2v5_ok = (fault_byte & 0x40) != 0;
    flags.supply_1v5_ok = (fault_byte & 0x80) != 0;
    return flags;
  }
};
 
enum class ReplyMode : uint8_t {
  REPLY_16BIT = 0b00,    
  REPLY_22BIT = 0b01,    
  CRITICAL_FAULT = 0b10, 
  RESERVED = 0b11        
};
 
enum class SPIStatus : uint8_t {
  NO_ERROR = 0b00000,          
  SPI_FRAME_ERROR = 0b00001,   
  CRC_ERROR = 0b00010,         
  WRITE_RO_REG = 0b00011,      
  INTERNAL_BUS_FAULT = 0b00100 
};
 
template <typename Derived>
class SpiInterface {
public:
 
  [[nodiscard]] CommResult<void> Init() noexcept {
    return static_cast<Derived*>(this)->Init();
  }
 
  [[nodiscard]] CommResult<void> Deinit() noexcept {
    return static_cast<Derived*>(this)->Deinit();
  }
 
  [[nodiscard]] CommResult<uint32_t> Transfer32(uint32_t tx_data) noexcept {
    return static_cast<Derived*>(this)->Transfer32(tx_data);
  }
 
  [[nodiscard]] CommResult<void> TransferMulti(std::span<const uint32_t> tx_data,
                                               std::span<uint32_t> rx_data) noexcept {
    return static_cast<Derived*>(this)->TransferMulti(tx_data, rx_data);
  }
 
  [[nodiscard]] CommResult<void> Delay(uint32_t microseconds) noexcept {
    return static_cast<Derived*>(this)->Delay(microseconds);
  }
 
  [[nodiscard]] CommResult<void> Configure(const SPIConfig& config) noexcept {
    return static_cast<Derived*>(this)->Configure(config);
  }
 
  [[nodiscard]] bool IsReady() const noexcept {
    return static_cast<const Derived*>(this)->IsReady();
  }
 
  [[nodiscard]] CommError GetLastError() const noexcept {
    return static_cast<const Derived*>(this)->GetLastError();
  }
 
  [[nodiscard]] CommResult<void> ClearErrors() noexcept {
    return static_cast<Derived*>(this)->ClearErrors();
  }
 
  [[nodiscard]] CommResult<void> GpioSet(CtrlPin pin, GpioSignal signal) noexcept {
    return static_cast<Derived*>(this)->GpioSet(pin, signal);
  }
 
  [[nodiscard]] CommResult<GpioSignal> GpioRead(CtrlPin pin) noexcept {
    return static_cast<Derived*>(this)->GpioRead(pin);
  }
 
  [[nodiscard]] CommResult<void> GpioSetActive(CtrlPin pin) noexcept {
    return GpioSet(pin, GpioSignal::ACTIVE);
  }
 
  [[nodiscard]] CommResult<void> GpioSetInactive(CtrlPin pin) noexcept {
    return GpioSet(pin, GpioSignal::INACTIVE);
  }
 
  void Log(LogLevel level, const char* tag, const char* format, ...) noexcept {
    va_list args{};
    va_start(args, format);
    static_cast<Derived*>(this)->Log(level, tag, format, args);
    va_end(args);
  }
 
  [[nodiscard]] CommResult<uint32_t> Read(uint16_t address, bool verify_crc = true) noexcept;
 
  static constexpr size_t kMaxPipelinedReads = 12;
 
  [[nodiscard]] CommResult<void> ReadMulti(std::span<const uint16_t> addresses,
                                           std::span<uint32_t> values,
                                           uint16_t& valid_mask) noexcept;
 
  [[nodiscard]] CommResult<void> Write(uint16_t address, uint16_t value,
                                       bool verify_crc = true) noexcept;
 
  [[nodiscard]] uint8_t LastCriticalFaultFlags() const noexcept {
    return last_critical_fault_flags_;
  }
 
  [[nodiscard]] bool SawCriticalFault() const noexcept {
    return saw_critical_fault_;
  }
 
  SpiInterface(const SpiInterface&) = delete;
  SpiInterface& operator=(const SpiInterface&) = delete;
 
protected:
  SpiInterface() = default;
 
  SpiInterface(SpiInterface&&) noexcept = default;
  SpiInterface& operator=(SpiInterface&&) noexcept = default;
 
  void NoteCriticalFault(const SPIFrame& frame) noexcept {
    last_critical_fault_flags_ = static_cast<uint8_t>(frame.rx_fault.fault_flags);
    saw_critical_fault_ = true;
  }
 
  uint8_t last_critical_fault_flags_{0}; 
  bool saw_critical_fault_{false};       
 
  ~SpiInterface() = default;
};
 
#if __cpp_concepts >= 201907L
#include <concepts>
template <typename T>
concept SpiInterfaceLike =
    requires(T comm, uint32_t data, SPIConfig cfg, CtrlPin pin, GpioSignal signal) {
      { comm.Init() } -> std::same_as<CommResult<void>>;
      { comm.Transfer32(data) } -> std::same_as<CommResult<uint32_t>>;
      { comm.IsReady() } -> std::same_as<bool>;
      { comm.Configure(cfg) } -> std::same_as<CommResult<void>>;
      { comm.GpioSet(pin, signal) } -> std::same_as<CommResult<void>>;
      { comm.GpioRead(pin) } -> std::same_as<CommResult<GpioSignal>>;
    };
#endif // __cpp_concepts
 
} // namespace tle92466ed
 
// Include registers header for CRC functions (after SPIFrame is defined)
#include "tle92466ed_registers.hpp"
 
namespace tle92466ed {
 
//==============================================================================
// INLINE IMPLEMENTATIONS
//==============================================================================
 
template <typename Derived>
inline CommResult<uint32_t> SpiInterface<Derived>::Read(uint16_t address, bool verify_crc) noexcept {
  // Create read frame
  SPIFrame tx_frame = SPIFrame::MakeRead(address);
 
  // Calculate and set CRC
  tx_frame.tx_fields.crc = CalculateFrameCrc(tx_frame);
 
  /* Pipelined SPI: the reply to a command only appears on the NEXT CS window,
   * so the device always has one reply outstanding. That makes a bare
   * command+dummy pair depend on what the previous transaction left behind —
   * one dropped or extra frame anywhere shifts every later read by one slot,
   * and the caller silently gets the *previous* register's value (bench
   * 2026-08-12: PIN_STAT returning CH_CTRL's 0x8000, FB_VOLTAGE2 returning 0).
   *
   * Sending a leading dummy makes the transaction self-synchronising: it
   * absorbs whatever reply was outstanding, so the reply to `tx_frame` is
   * always in the last slot regardless of prior bus state.
   *
   * The dummies address 0, NOT `address`. Re-sending the same read as the
   * dummy queues a second reply and the part answers with a reserved
   * reply-mode instead of the register (bench 2026-08-12: ICVID never
   * validated, DriverError::SPIFrameError every attempt; MakeRead(0) restored
   * identity on the same hardware). TransferMulti keeps one bus-ownership
   * window across all three frames on shared multi-slave buses. */
  SPIFrame dummy_frame = SPIFrame::MakeRead(0);
  dummy_frame.tx_fields.crc = CalculateFrameCrc(dummy_frame);
 
  const uint32_t tx_words[3] = {dummy_frame.word, tx_frame.word,
                                dummy_frame.word};
 
  /* A reply is only believed when it is well formed: CRC valid *and* the reply
   * width the register is defined to answer with. Bench measurement
   * (2026-08-13, 150 frames) found 4 % of frames corrupt and 25 % of
   * FB_STAT reads carrying the preceding ICVID reply — the latter with a valid
   * CRC, so CRC alone does not reject it. Both used to be accepted as data,
   * which is the origin of the "sticky-zero CH_CTRL", the impossible IMAX, the
   * open-load reported on a fitted resistor, and INIT_DONE reading 0 on a
   * healthy device. Two CRC attempts keep freeze-complete (2× FB_UPD +
   * FB_I_AVG + FB_DC) inside a 2 ms host control-loop budget; four attempts ×
   * Mode1 IdleAll+30 µs per frame ran last_step ~9–11 ms on hold ticks.
   * ICVID Init has its own recovery path. */
  constexpr uint8_t kReadAttempts = 2;
  const ExpectedReply expected = ExpectedReplyFor(address);
  uint32_t rx_all[3] = {};
  uint32_t last_reply = 0;
  uint32_t last_flush = 0;
  bool saw_any_frame = false;
 
  for (uint8_t attempt = 0; attempt < kReadAttempts; ++attempt) {
    auto multi = static_cast<Derived*>(this)->TransferMulti(
        std::span<const uint32_t>{tx_words}, std::span<uint32_t>{rx_all});
    if (!multi) {
      return tle::unexpected(multi.error());
    }
    /* Slot 2 answers the command; slot 1 answers the flush dummy and is only
     * kept as a fallback for the ICVID scan below. */
    last_reply = rx_all[2];
    last_flush = rx_all[1];
 
    SPIFrame candidate{};
    candidate.word = last_reply;
 
    /* Undriven MISO — nothing to validate, and retrying is pointless if the
     * part is absent, but cheap if a single window was missed. */
    if (last_reply == 0U || last_reply == 0xFFFFFFFFU) {
      continue;
    }
    saw_any_frame = true;
 
    /* Critical fault frame (UV / clock / supplies) first: its bits 31:24 are
     * "don't care", not a CRC (datasheet 5.2.3.5), so a CRC check would reject
     * it and report CRCError instead of the fault. The device is answering
     * truthfully that it cannot serve the read, so this is not retried. */
    if (candidate.rx_common.reply_mode == 0x02) {
      NoteCriticalFault(candidate);
      return tle::unexpected(CommError::BusError);
    }
 
    if (!VerifyFrameCrc(candidate)) {
      continue;
    }
 
    const bool width_ok =
        (expected == ExpectedReply::Bits22) ? (candidate.rx_common.reply_mode == 0x01)
                                            : (candidate.rx_common.reply_mode == 0x00);
    if (!width_ok) {
      continue; /* Another register's reply landed in this slot. */
    }
 
    return (candidate.rx_common.reply_mode == 0x01)
               ? static_cast<uint32_t>(candidate.rx_22bit.data)
               : static_cast<uint32_t>(candidate.rx_16bit.data);
  }
 
  const uint32_t rx_words[2] = {last_flush, last_reply};
 
  /* ICVID-only: recover a valid device ID from a misaligned 32-bit MISO word
   * on long soft-CS / Mode1 buses (data may sit in bits[23:8], or appear one
   * bit early as 0x82xx/0x80xx/0xC0xx). Restricted to ICVID so lane noise
   * cannot false-match 0xC1xx inside other registers. */
  if (address == CentralReg::ICVID) {
    auto extract_icvid_candidate = [](uint32_t word) noexcept -> uint16_t {
      if (word == 0U || word == 0xFFFFFFFFU) {
        return 0;
      }
      SPIFrame f{};
      f.word = word;
      const uint16_t cands[] = {
          static_cast<uint16_t>(f.rx_16bit.data),
          static_cast<uint16_t>((word >> 8) & 0xFFFFU),
          static_cast<uint16_t>((word >> 16) & 0xFFFFU),
          static_cast<uint16_t>(word & 0xFFFFU),
      };
      for (uint16_t c : cands) {
        if (DeviceID::IsValidDevice(c)) {
          return c;
        }
        /* One-bit-early Mode1 phantoms of a real 0xC1xx ID. */
        if ((c & 0xFF00U) == 0x8200U || (c & 0xFF00U) == 0x8000U ||
            (c & 0xFF00U) == 0xC000U) {
          const uint16_t unshift =
              static_cast<uint16_t>((static_cast<uint32_t>(c) << 1) & 0xFFFFU);
          if (DeviceID::IsValidDevice(unshift)) {
            return unshift;
          }
        }
      }
      return 0;
    };
    for (uint32_t word : {rx_words[1], rx_words[0]}) {
      const uint16_t id = extract_icvid_candidate(word);
      if (id != 0U) {
        return static_cast<uint32_t>(id);
      }
    }
  }
 
  /* Every attempt produced a frame that could not be trusted. Reporting the
   * failure is the whole point: the caller can retry, hold its last known
   * value, or degrade — all of which beat decoding a corrupt word as state.
   *
   * `verify_crc` no longer gates this. It used to let callers opt out of
   * validation, and every diagnostic path did (`ReadRegister(addr, false)`),
   * which is why corrupt and stale frames reached the decoders in the first
   * place. The parameter is retained for API compatibility. */
  (void)verify_crc;
  return tle::unexpected(saw_any_frame ? CommError::CRCError
                                       : CommError::NoReply);
}
 
template <typename Derived>
inline CommResult<void> SpiInterface<Derived>::ReadMulti(
    std::span<const uint16_t> addresses, std::span<uint32_t> values,
    uint16_t& valid_mask) noexcept {
  valid_mask = 0U;
  const size_t n = addresses.size();
  if (n == 0U || n > kMaxPipelinedReads || values.size() != n) {
    return tle::unexpected(CommError::InvalidParameter);
  }
 
  SPIFrame dummy_frame = SPIFrame::MakeRead(0);
  dummy_frame.tx_fields.crc = CalculateFrameCrc(dummy_frame);
 
  /* [flush dummy][cmd 0..n-1][trailing dummy]: the reply to command i is
   * clocked out during frame i+2. See the ReadMulti doc comment. */
  uint32_t tx_words[kMaxPipelinedReads + 2] = {};
  uint32_t rx_words[kMaxPipelinedReads + 2] = {};
  tx_words[0] = dummy_frame.word;
  for (size_t i = 0; i < n; ++i) {
    SPIFrame cmd = SPIFrame::MakeRead(addresses[i]);
    cmd.tx_fields.crc = CalculateFrameCrc(cmd);
    tx_words[i + 1] = cmd.word;
    values[i] = 0U;
  }
  tx_words[n + 1] = dummy_frame.word;
 
  const size_t frames = n + 2U;
  auto multi = static_cast<Derived*>(this)->TransferMulti(
      std::span<const uint32_t>{tx_words, frames},
      std::span<uint32_t>{rx_words, frames});
  if (!multi) {
    return tle::unexpected(multi.error());
  }
 
  for (size_t i = 0; i < n; ++i) {
    SPIFrame candidate{};
    candidate.word = rx_words[i + 2U];
    if (candidate.word == 0U || candidate.word == 0xFFFFFFFFU) {
      continue; /* Undriven MISO. */
    }
    if (candidate.rx_common.reply_mode == 0x02) {
      /* Critical fault (UV / clock / supplies), checked before the CRC because
       * bits 31:24 of this frame are "don't care" (datasheet 5.2.3.5). The
       * device cannot serve any of these reads, so abandon the whole burst. */
      NoteCriticalFault(candidate);
      return tle::unexpected(CommError::BusError);
    }
    if (!VerifyFrameCrc(candidate)) {
      continue;
    }
    const ExpectedReply expected = ExpectedReplyFor(addresses[i]);
    const bool width_ok = (expected == ExpectedReply::Bits22)
                              ? (candidate.rx_common.reply_mode == 0x01)
                              : (candidate.rx_common.reply_mode == 0x00);
    if (!width_ok) {
      continue; /* Another register's reply landed in this slot. */
    }
    values[i] = (candidate.rx_common.reply_mode == 0x01)
                    ? static_cast<uint32_t>(candidate.rx_22bit.data)
                    : static_cast<uint32_t>(candidate.rx_16bit.data);
    valid_mask = static_cast<uint16_t>(valid_mask | (1U << i));
  }
  return {};
}
 
template <typename Derived>
inline CommResult<void> SpiInterface<Derived>::Write(uint16_t address, uint16_t value,
                                                      bool verify_crc) noexcept {
  // Create write frame
  SPIFrame tx_frame = SPIFrame::MakeWrite(address, value);
 
  // Calculate and set CRC
  tx_frame.tx_fields.crc = CalculateFrameCrc(tx_frame);
 
  /* Leading flush dummy then a trailing dummy to clock the write response —
   * same self-synchronising pattern as Read(), so the status bits checked
   * below belong to this write and not to whatever ran before it. (See Read()
   * for why the dummies must not repeat the accessed address.) */
  SPIFrame dummy_frame = SPIFrame::MakeRead(0);
  dummy_frame.tx_fields.crc = CalculateFrameCrc(dummy_frame);
 
  const uint32_t tx_words[3] = {dummy_frame.word, tx_frame.word,
                                dummy_frame.word};
  uint32_t rx_words[3] = {};
  auto multi = static_cast<Derived*>(this)->TransferMulti(
      std::span<const uint32_t>{tx_words}, std::span<uint32_t>{rx_words});
  if (!multi) {
    return tle::unexpected(multi.error());
  }
 
  // Response to the write frame lands in the last slot.
  SPIFrame rx_frame{};
  rx_frame.word = rx_words[2];
 
  // Critical fault frame first — keep the cause byte for the caller. Its bits
  // 31:24 are "don't care", not a CRC (datasheet 5.2.3.5), so checking the CRC
  // first turned a supply/clock fault into CommError::CRCError.
  if (rx_frame.rx_common.reply_mode == 0x02) {
    NoteCriticalFault(rx_frame);
    return tle::unexpected(CommError::BusError);
  }
 
  // Verify CRC if requested
  if (verify_crc && !VerifyFrameCrc(rx_frame)) {
    return tle::unexpected(CommError::CRCError);
  }
 
  // Check for errors in status field (for 16-bit reply frames)
  if (rx_frame.rx_common.reply_mode == 0x00) {
    // Check status field for errors
    if (rx_frame.rx_16bit.status != 0x00) {
      // Status indicates an error
      return tle::unexpected(CommError::TransferError);
    }
  }
 
  return {};
}
 
} // namespace tle92466ed