BaseSpi.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC SPI Error Codes (Table)
//--------------------------------------
#define HF_SPI_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(SPI_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(SPI_ERR_FAILURE, 1, "General failure")                                                         \
  X(SPI_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(SPI_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(SPI_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(SPI_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(SPI_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Bus errors */                                                                                 \
  X(SPI_ERR_BUS_BUSY, 7, "Bus busy")                                                               \
  X(SPI_ERR_BUS_ERROR, 8, "Bus error")                                                             \
  X(SPI_ERR_BUS_NOT_AVAILABLE, 9, "Bus not available")                                             \
  X(SPI_ERR_BUS_TIMEOUT, 10, "Bus timeout")                                                        \
  /* Transfer errors */                                                                            \
  X(SPI_ERR_TRANSFER_FAILED, 11, "Transfer failed")                                                \
  X(SPI_ERR_TRANSFER_TIMEOUT, 12, "Transfer timeout")                                              \
  X(SPI_ERR_TRANSFER_TOO_LONG, 13, "Transfer too long")                                            \
  X(SPI_ERR_TRANSFER_SIZE_MISMATCH, 14, "Transfer size mismatch")                                  \
  /* Device errors */                                                                              \
  X(SPI_ERR_DEVICE_NOT_FOUND, 15, "Device not found")                                              \
  X(SPI_ERR_DEVICE_NOT_RESPONDING, 16, "Device not responding")                                    \
  X(SPI_ERR_CS_CONTROL_FAILED, 17, "Chip select control failed")                                   \
  /* Hardware errors */                                                                            \
  X(SPI_ERR_HARDWARE_FAULT, 18, "Hardware fault")                                                  \
  X(SPI_ERR_COMMUNICATION_FAILURE, 19, "Communication failure")                                    \
  X(SPI_ERR_VOLTAGE_OUT_OF_RANGE, 20, "Voltage out of range")                                      \
  X(SPI_ERR_CLOCK_ERROR, 21, "Clock error")                                                        \
  /* Configuration errors */                                                                       \
  X(SPI_ERR_INVALID_CONFIGURATION, 22, "Invalid configuration")                                    \
  X(SPI_ERR_UNSUPPORTED_OPERATION, 23, "Unsupported operation")                                    \
  X(SPI_ERR_INVALID_CLOCK_SPEED, 24, "Invalid clock speed")                                        \
  X(SPI_ERR_INVALID_MODE, 25, "Invalid SPI mode")                                                  \
  X(SPI_ERR_PIN_CONFIGURATION_ERROR, 26, "Pin configuration error")                                \
  /* System errors */                                                                              \
  X(SPI_ERR_SYSTEM_ERROR, 27, "System error")                                                      \
  X(SPI_ERR_PERMISSION_DENIED, 28, "Permission denied")                                            \
  X(SPI_ERR_OPERATION_ABORTED, 29, "Operation aborted")                                            \
  X(SPI_ERR_UNKNOWN, 30, "Unknown error")
 
enum class hf_spi_err_t : hf_u8_t {
#define X(NAME, VALUE, DESC) NAME = VALUE,
  HF_SPI_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfSpiErrToString(hf_spi_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_spi_err_t::NAME:                                                                         \
    return DESC;
    HF_SPI_ERR_LIST(X)
#undef X
  default:
    return HfSpiErrToString(hf_spi_err_t::SPI_ERR_UNKNOWN);
  }
}
 
struct hf_spi_statistics_t {
  hf_u32_t total_transactions;       
  hf_u32_t successful_transactions;  
  hf_u32_t failed_transactions;      
  hf_u32_t timeout_transactions;     
  hf_u32_t total_bytes_sent;         
  hf_u32_t total_bytes_received;     
  hf_u32_t max_transaction_time_us;  
  hf_u32_t min_transaction_time_us;  
  hf_u64_t last_activity_timestamp;  
  hf_u64_t initialization_timestamp; 
 
  hf_spi_statistics_t() noexcept
      : total_transactions(0), successful_transactions(0), failed_transactions(0),
        timeout_transactions(0), total_bytes_sent(0), total_bytes_received(0),
        max_transaction_time_us(0), min_transaction_time_us(0xFFFFFFFF), last_activity_timestamp(0),
        initialization_timestamp(0) {}
};
 
struct hf_spi_diagnostics_t {
  bool is_initialized;          
  bool is_bus_suspended;        
  bool dma_enabled;             
  hf_u32_t current_clock_speed; 
  hf_u8_t current_mode;         
  hf_u16_t max_transfer_size;   
  hf_u8_t device_count;         
  hf_u32_t last_error;          
  hf_u64_t total_transactions;  
  hf_u64_t failed_transactions; 
 
  hf_spi_diagnostics_t() noexcept
      : is_initialized(false), is_bus_suspended(false), dma_enabled(false), current_clock_speed(0),
        current_mode(0), max_transfer_size(0), device_count(0), last_error(0),
        total_transactions(0), failed_transactions(0) {}
};
 
//--------------------------------------
//  Abstract Base Class
//--------------------------------------
 
class BaseSpi {
public:
  virtual ~BaseSpi() noexcept = default;
 
  // Non-copyable, non-movable (can be changed in derived classes if needed)
  BaseSpi(const BaseSpi&) = delete;
  BaseSpi& operator=(const BaseSpi&) = delete;
  BaseSpi(BaseSpi&&) = delete;
  BaseSpi& operator=(BaseSpi&&) = delete;
 
  bool EnsureInitialized() noexcept {
    if (!initialized_) {
      initialized_ = Initialize();
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() noexcept {
    if (initialized_) {
      initialized_ = !Deinitialize();
    }
    return !initialized_;
  }
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS - MUST BE OVERRIDDEN  //
  //==============================================//
 
  virtual bool Initialize() noexcept = 0;
 
  virtual bool Deinitialize() noexcept = 0;
 
  virtual hf_spi_err_t Transfer(const hf_u8_t* tx_data, hf_u8_t* rx_data, hf_u16_t length,
                                hf_u32_t timeout_ms = 0) noexcept = 0;
 
  virtual void IdleChipSelect() noexcept {}
 
  virtual void HoldChipSelectMs(hf_u32_t /*ms*/) noexcept {}
 
  virtual bool SetTransferMode(hf_u8_t /*mode_0_to_3*/) noexcept { return false; }
 
  virtual bool SetIoSwap(bool /*enable*/) noexcept { return false; }
 
  virtual hf_spi_err_t TransferChain(const hf_u8_t* const* tx_frames, hf_u8_t* const* rx_frames,
                                     hf_u16_t frame_length, hf_u16_t frame_count,
                                     hf_u32_t inter_frame_gap_us,
                                     hf_u32_t timeout_ms = 0) noexcept {
    if (frame_count == 0U || frame_length == 0U) {
      return hf_spi_err_t::SPI_ERR_INVALID_PARAMETER;
    }
    if (tx_frames == nullptr && rx_frames == nullptr) {
      return hf_spi_err_t::SPI_ERR_INVALID_PARAMETER;
    }
    for (hf_u16_t i = 0; i < frame_count; ++i) {
      const hf_u8_t* tx = (tx_frames != nullptr) ? tx_frames[i] : nullptr;
      hf_u8_t* rx = (rx_frames != nullptr) ? rx_frames[i] : nullptr;
      const hf_spi_err_t err = Transfer(tx, rx, frame_length, timeout_ms);
      if (err != hf_spi_err_t::SPI_SUCCESS) {
        return err;
      }
      if (inter_frame_gap_us > 0U && (i + 1U) < frame_count) {
        /* Portable busy-wait; STM32 override uses a tighter spin. */
        for (hf_u32_t spin = inter_frame_gap_us * 50U; spin > 0U; --spin) {
          __asm__ volatile("" ::: "memory");
        }
      }
    }
    return hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual const void* GetDeviceConfig() const noexcept = 0;
 
  //==============================================//
  // CONVENIENCE METHODS WITH DEFAULT IMPLEMENTATIONS //
  //==============================================//
 
  virtual bool Open() noexcept {
    return EnsureInitialized();
  }
 
  virtual bool Close() noexcept {
    if (initialized_) {
      initialized_ = !Deinitialize();
      return !initialized_;
    }
    return true;
  }
 
  virtual bool Transfer(const hf_u8_t* tx_data, hf_u8_t* rx_data, hf_u16_t length) noexcept {
    if (!EnsureInitialized()) {
      return false;
    }
    return Transfer(tx_data, rx_data, length, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual hf_spi_err_t Write(const hf_u8_t* data, hf_u16_t length,
                             hf_u32_t timeout_ms = 0) noexcept {
    return Transfer(data, nullptr, length, timeout_ms);
  }
 
  virtual hf_spi_err_t Read(hf_u8_t* data, hf_u16_t length, hf_u32_t timeout_ms = 0) noexcept {
    return Transfer(nullptr, data, length, timeout_ms);
  }
 
  virtual bool Write(const hf_u8_t* data, hf_u16_t length) noexcept {
    if (!EnsureInitialized()) {
      return false;
    }
    return Write(data, length, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual bool Read(hf_u8_t* data, hf_u16_t length) noexcept {
    if (!EnsureInitialized()) {
      return false;
    }
    return Read(data, length, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual bool WriteByte(hf_u8_t data) noexcept {
    return Write(&data, 1, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual bool ReadByte(hf_u8_t& data) noexcept {
    return Read(&data, 1, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  virtual bool TransferByte(hf_u8_t tx_data, hf_u8_t& rx_data) noexcept {
    return Transfer(&tx_data, &rx_data, 1, 0) == hf_spi_err_t::SPI_SUCCESS;
  }
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS
  //==============================================//
 
  virtual hf_spi_err_t ResetStatistics() noexcept {
    statistics_ = hf_spi_statistics_t{}; // Reset statistics to default values
    return hf_spi_err_t::SPI_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_spi_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_spi_diagnostics_t{}; // Reset diagnostics to default values
    return hf_spi_err_t::SPI_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_spi_err_t GetStatistics(hf_spi_statistics_t& statistics) const noexcept {
    statistics = statistics_; // Return statistics by default
    return hf_spi_err_t::SPI_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_spi_err_t GetDiagnostics(hf_spi_diagnostics_t& diagnostics) const noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_spi_err_t::SPI_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  BaseSpi() noexcept : initialized_(false), statistics_{}, diagnostics_{} {}
 
  bool initialized_;                 
  hf_spi_statistics_t statistics_;   
  hf_spi_diagnostics_t diagnostics_; 
};