BasePio.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
//--------------------------------------
//  HardFOC PIO Error Codes (Table)
//--------------------------------------
#define HF_PIO_ERR_LIST(X)                                                                         \
  /* Success codes */                                                                              \
  X(PIO_SUCCESS, 0, "Success")                                                                     \
  /* General errors */                                                                             \
  X(PIO_ERR_FAILURE, 1, "General failure")                                                         \
  X(PIO_ERR_NOT_INITIALIZED, 2, "Not initialized")                                                 \
  X(PIO_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                         \
  X(PIO_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                             \
  X(PIO_ERR_NULL_POINTER, 5, "Null pointer")                                                       \
  X(PIO_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                     \
  /* Channel errors */                                                                             \
  X(PIO_ERR_INVALID_CHANNEL, 7, "Invalid PIO channel")                                             \
  X(PIO_ERR_CHANNEL_BUSY, 8, "Channel already in use")                                             \
  X(PIO_ERR_CHANNEL_NOT_AVAILABLE, 9, "Channel not available")                                     \
  X(PIO_ERR_INSUFFICIENT_CHANNELS, 10, "Insufficient channels available")                          \
  /* Timing errors */                                                                              \
  X(PIO_ERR_INVALID_RESOLUTION, 11, "Invalid time resolution")                                     \
  X(PIO_ERR_RESOLUTION_TOO_HIGH, 12, "Time resolution too high")                                   \
  X(PIO_ERR_RESOLUTION_TOO_LOW, 13, "Time resolution too low")                                     \
  X(PIO_ERR_DURATION_TOO_LONG, 14, "Duration too long")                                            \
  X(PIO_ERR_DURATION_TOO_SHORT, 15, "Duration too short")                                          \
  /* Buffer errors */                                                                              \
  X(PIO_ERR_BUFFER_OVERFLOW, 16, "Buffer overflow")                                                \
  X(PIO_ERR_BUFFER_UNDERFLOW, 17, "Buffer underflow")                                              \
  X(PIO_ERR_BUFFER_TOO_SMALL, 18, "Buffer too small")                                              \
  X(PIO_ERR_BUFFER_TOO_LARGE, 19, "Buffer too large")                                              \
  /* Hardware errors */                                                                            \
  X(PIO_ERR_HARDWARE_FAULT, 20, "Hardware fault")                                                  \
  X(PIO_ERR_COMMUNICATION_TIMEOUT, 21, "Communication timeout")                                    \
  X(PIO_ERR_COMMUNICATION_FAILURE, 22, "Communication failure")                                    \
  X(PIO_ERR_DEVICE_NOT_RESPONDING, 23, "Device not responding")                                    \
  /* Configuration errors */                                                                       \
  X(PIO_ERR_INVALID_CONFIGURATION, 24, "Invalid configuration")                                    \
  X(PIO_ERR_UNSUPPORTED_OPERATION, 25, "Unsupported operation")                                    \
  X(PIO_ERR_PIN_CONFLICT, 26, "Pin already in use")                                                \
  X(PIO_ERR_RESOURCE_BUSY, 27, "Resource busy")                                                    \
  /* System errors */                                                                              \
  X(PIO_ERR_SYSTEM_ERROR, 28, "System error")                                                      \
  X(PIO_ERR_PERMISSION_DENIED, 29, "Permission denied")                                            \
  X(PIO_ERR_OPERATION_ABORTED, 30, "Operation aborted")                                            \
  X(PIO_ERR_UNKNOWN, 31, "Unknown error")
 
enum class hf_pio_err_t : hf_u8_t {
#define X(NAME, VALUE, DESC) NAME = VALUE,
  HF_PIO_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfPioErrToString(hf_pio_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_pio_err_t::NAME:                                                                         \
    return DESC;
    HF_PIO_ERR_LIST(X)
#undef X
  default:
    return HfPioErrToString(hf_pio_err_t::PIO_ERR_UNKNOWN);
  }
}
 
//--------------------------------------
//  PIO Configuration Structures
//--------------------------------------
 
enum class hf_pio_direction_t : hf_u8_t {
  Transmit = 0,     
  Receive = 1,      
  Bidirectional = 2 
};
 
enum class hf_pio_polarity_t : hf_u8_t {
  Normal = 0,  
  Inverted = 1 
};
 
enum class hf_pio_idle_state_t : hf_u8_t {
  Low = 0, 
  High = 1 
};
 
struct hf_pio_channel_config_t {
  hf_pin_num_t gpio_pin;          
  hf_pio_direction_t direction;   
  hf_u32_t resolution_ns;         
  hf_pio_polarity_t polarity;     
  hf_pio_idle_state_t idle_state; 
  hf_u32_t timeout_us;            
  size_t buffer_size;             
 
  hf_pio_channel_config_t() noexcept
      : gpio_pin(-1), direction(hf_pio_direction_t::Transmit), resolution_ns(1000), // 1µs default
        polarity(hf_pio_polarity_t::Normal), idle_state(hf_pio_idle_state_t::Low),
        timeout_us(10000), buffer_size(64) {}
};
 
struct hf_pio_symbol_t {
  hf_u32_t duration; 
  bool level;        
 
  hf_pio_symbol_t() noexcept : duration(0), level(false) {}
  hf_pio_symbol_t(hf_u32_t dur, bool lvl) noexcept : duration(dur), level(lvl) {}
};
 
struct hf_pio_channel_status_t {
  bool is_initialized;      
  bool is_busy;             
  bool is_transmitting;     
  bool is_receiving;        
  size_t symbols_queued;    
  size_t symbols_processed; 
  hf_pio_err_t last_error;  
  hf_u32_t timestamp_us;    
};
 
struct hf_pio_capabilities_t {
  hf_u8_t max_channels;        
  hf_u32_t min_resolution_ns;  
  hf_u32_t max_resolution_ns;  
  hf_u32_t max_duration;       
  size_t max_buffer_size;      
  bool supports_bidirectional; 
  bool supports_loopback;      
  bool supports_carrier;       
};
 
struct hf_pio_statistics_t {
  hf_u32_t totalTransmissions;        
  hf_u32_t successfulTransmissions;   
  hf_u32_t failedTransmissions;       
  hf_u32_t totalReceptions;           
  hf_u32_t successfulReceptions;      
  hf_u32_t failedReceptions;          
  hf_u32_t symbolsTransmitted;        
  hf_u32_t symbolsReceived;           
  hf_u32_t averageTransmissionTimeUs; 
  hf_u32_t maxTransmissionTimeUs;     
  hf_u32_t minTransmissionTimeUs;     
  hf_u32_t timingErrors;              
  hf_u32_t bufferOverflows;           
 
  hf_pio_statistics_t()
      : totalTransmissions(0), successfulTransmissions(0), failedTransmissions(0),
        totalReceptions(0), successfulReceptions(0), failedReceptions(0), symbolsTransmitted(0),
        symbolsReceived(0), averageTransmissionTimeUs(0), maxTransmissionTimeUs(0),
        minTransmissionTimeUs(UINT32_MAX), timingErrors(0), bufferOverflows(0) {}
};
 
struct hf_pio_diagnostics_t {
  bool pioHealthy;              
  hf_pio_err_t lastErrorCode;   
  hf_u32_t lastErrorTimestamp;  
  hf_u32_t consecutiveErrors;   
  bool pioInitialized;          
  hf_u8_t activeChannels;       
  hf_u32_t currentResolutionNs; 
  bool bidirectionalSupported;  
 
  hf_pio_diagnostics_t()
      : pioHealthy(true), lastErrorCode(hf_pio_err_t::PIO_SUCCESS), lastErrorTimestamp(0),
        consecutiveErrors(0), pioInitialized(false), activeChannels(0), currentResolutionNs(0),
        bidirectionalSupported(false) {}
};
 
//--------------------------------------
//  Callback Types
//--------------------------------------
 
using hf_pio_transmit_callback_t =
    void(*)(hf_u8_t channel_id, size_t symbols_sent, void* user_data);
 
using hf_pio_receive_callback_t = void(*)(    hf_u8_t channel_id, const hf_pio_symbol_t* symbols, size_t symbol_count, void* user_data);
 
using hf_pio_error_callback_t =
    void(*)(hf_u8_t channel_id, hf_pio_err_t error, void* user_data);
 
//--------------------------------------
//  Abstract Base Class
//--------------------------------------
 
class BasePio {
public:
  virtual ~BasePio() noexcept = default;
 
  // Disable copy constructor and assignment operator for safety
  BasePio(const BasePio&) = delete;
  BasePio& operator=(const BasePio&) = delete;
 
  // Allow move operations
  BasePio(BasePio&&) noexcept = default;
  BasePio& operator=(BasePio&&) noexcept = default;
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS - MUST BE OVERRIDDEN  //
  //==============================================//
 
  virtual hf_pio_err_t Initialize() noexcept = 0;
 
  virtual hf_pio_err_t Deinitialize() noexcept = 0;
 
  [[nodiscard]] bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  bool EnsureInitialized() noexcept {
    if (!initialized_) {
      initialized_ = (Initialize() == hf_pio_err_t::PIO_SUCCESS);
    }
    return initialized_;
  }
 
  bool EnsureDeinitialized() noexcept {
    if (initialized_) {
      initialized_ = !(Deinitialize() == hf_pio_err_t::PIO_SUCCESS);
      return !initialized_;
    }
    return true;
  }
 
  virtual hf_pio_err_t ConfigureChannel(hf_u8_t channel_id,
                                        const hf_pio_channel_config_t& config) noexcept = 0;
 
  virtual hf_pio_err_t Transmit(hf_u8_t channel_id, const hf_pio_symbol_t* symbols,
                                size_t symbol_count, bool wait_completion = false) noexcept = 0;
 
  virtual hf_pio_err_t StartReceive(hf_u8_t channel_id, hf_pio_symbol_t* buffer, size_t buffer_size,
                                    hf_u32_t timeout_us = 0) noexcept = 0;
 
  virtual hf_pio_err_t StopReceive(hf_u8_t channel_id, size_t& symbols_received) noexcept = 0;
 
  virtual bool IsChannelBusy(hf_u8_t channel_id) const noexcept = 0;
 
  virtual hf_pio_err_t GetChannelStatus(hf_u8_t channel_id,
                                        hf_pio_channel_status_t& status) const noexcept = 0;
 
  virtual hf_pio_err_t GetCapabilities(hf_pio_capabilities_t& capabilities) const noexcept = 0;
 
  virtual void SetTransmitCallback(hf_u8_t channel_id, hf_pio_transmit_callback_t callback,
                                   void* user_data = nullptr) noexcept = 0;
 
  virtual void SetReceiveCallback(hf_u8_t channel_id, hf_pio_receive_callback_t callback,
                                  void* user_data = nullptr) noexcept = 0;
 
  virtual void SetErrorCallback(hf_u8_t channel_id, hf_pio_error_callback_t callback,
                                void* user_data = nullptr) noexcept = 0;
 
  virtual void ClearChannelCallbacks(hf_u8_t channel_id) noexcept = 0;
 
  virtual void ClearCallbacks() noexcept = 0;
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS
  //==============================================//
 
  virtual hf_pio_err_t ResetStatistics() noexcept {
    statistics_ = hf_pio_statistics_t{}; // Reset statistics to default values
    return hf_pio_err_t::PIO_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pio_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_pio_diagnostics_t{}; // Reset diagnostics to default values
    return hf_pio_err_t::PIO_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pio_err_t GetStatistics(hf_u8_t channel_id,
                                     hf_pio_statistics_t& statistics) const noexcept {
    // This method needs to be implemented to return platform-specific statistics
    return hf_pio_err_t::PIO_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_pio_err_t GetDiagnostics(hf_u8_t channel_id,
                                      hf_pio_diagnostics_t& diagnostics) const noexcept {
    // This method needs to be implemented to return platform-specific diagnostics
    return hf_pio_err_t::PIO_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  BasePio() noexcept : initialized_(false), statistics_{}, diagnostics_{} {}
 
  bool initialized_;
  hf_pio_statistics_t statistics_;   
  hf_pio_diagnostics_t diagnostics_; 
};