EspTypes_SPI.h

Go to the documentation of this file.

 
#pragma once
 
#include "BaseSpi.h" // For hf_spi_err_t
#include "EspTypes_Base.h"
#include "HardwareTypes.h" // For basic hardware types
#include "McuSelect.h"     // Central MCU platform selection (includes all ESP-IDF)
 
// ESP-IDF C headers must be wrapped in extern "C" for C++ compatibility
#ifdef __cplusplus
extern "C" {
#endif
 
#include "driver/spi_master.h"
 
#ifdef __cplusplus
}
#endif
 
// Forward declarations for new SPI bus/device classes
class EspSpiBus;
class EspSpiDevice;
 
//==============================================================================
// ESP32 SPI TYPE MAPPINGS
//==============================================================================
 
// Direct ESP-IDF type usage - no unnecessary aliases
// These types are used internally by EspSpi implementation
using hf_spi_device_handle_t = spi_device_handle_t;
using hf_spi_device_interface_config_t = spi_device_interface_config_t;
using hf_spi_transaction_t = spi_transaction_t;
using hf_spi_clock_source_t = spi_clock_source_t;
using hf_spi_sampling_point_t = spi_sampling_point_t;
 
//==============================================================================
// ESP32 SPI ENUMS
//==============================================================================
 
enum class hf_spi_mode_t : uint8_t {
  HF_SPI_MODE_0 = 0, 
  HF_SPI_MODE_1 = 1, 
  HF_SPI_MODE_2 = 2, 
  HF_SPI_MODE_3 = 3, 
};
 
// /**
//  * @brief ESP32 SPI host device enumeration.
//  * @details ESP32 SPI controller mapping aligned with ESP-IDF.
//  *          SPI1 is reserved for flash and not exposed to users.
//  */
// enum class hf_spi_host_device_t : uint8_t {
//   HF_SPI2_HOST =
//       static_cast<uint8_t>(spi_host_device_t::SPI2_HOST), ///< SPI2 host (general purpose) -
//       ESP-IDF SPI2_HOST
// #ifdef HF_MCU_ESP32C6
//   // ESP32-C6 only has SPI2_HOST available for general purpose use
//   HF_SPI_HOST_MAX =
//       static_cast<uint8_t>(spi_host_device_t::SPI2_HOST + 1), ///< Maximum number of SPI hosts
//       for ESP32-C6
// #else
//   HF_SPI3_HOST =
//       static_cast<uint8_t>(spi_host_device_t::SPI3_HOST), ///< SPI3 host (general purpose) -
//       ESP-IDF SPI3_HOST
//   HF_SPI_HOST_MAX = static_cast<uint8_t>(spi_host_device_t::SPI_HOST_MAX), ///< Maximum number of
//   SPI hosts
// #endif
// };
 
enum class hf_spi_transfer_mode_t : uint8_t {
  HF_SPI_TRANSFER_MODE_SINGLE = 0, 
  HF_SPI_TRANSFER_MODE_DUAL = 1,   
  HF_SPI_TRANSFER_MODE_QUAD = 2,   
  HF_SPI_TRANSFER_MODE_OCTAL = 3   
};
 
enum class hf_spi_event_type_t : int {
  HF_SPI_EVENT_TRANSACTION_COMPLETE = 0, 
  HF_SPI_EVENT_TRANSACTION_ERROR = 1,    
  HF_SPI_EVENT_BUS_SUSPENDED = 2,        
  HF_SPI_EVENT_BUS_RESUMED = 3,          
  HF_SPI_EVENT_DMA_ERROR = 4             
};
 
//==============================================================================
// ESP32 SPI CONSTANTS AND VALIDATION MACROS
//==============================================================================
 
static constexpr uint32_t HF_SPI_MIN_CLOCK_SPEED = 1000;     
static constexpr uint32_t HF_SPI_MAX_CLOCK_SPEED = 80000000; 
static constexpr uint32_t HF_SPI_MAX_TRANSFER_SIZE = 4092;   
static constexpr uint8_t HF_SPI_MAX_HOSTS = 3;               
 
#define HF_SPI_IS_VALID_HOST(host)                                                                 \
  ((host) < static_cast<uint8_t>(spi_host_device_t::HF_SPI_HOST_MAX))
#define HF_SPI_IS_VALID_CLOCK_SPEED(speed)                                                         \
  ((speed) >= HF_SPI_MIN_CLOCK_SPEED && (speed) <= HF_SPI_MAX_CLOCK_SPEED)
#define HF_SPI_IS_VALID_MODE(mode) ((mode) >= 0 && (mode) <= 3)
#define HF_SPI_IS_VALID_TRANSFER_SIZE(size) ((size) > 0 && (size) <= HF_SPI_MAX_TRANSFER_SIZE)
 
//==============================================================================
// ESP32 SPI BUS CONFIG STRUCT
//==============================================================================
struct hf_spi_bus_config_t {
  hf_host_id_t host;          
  hf_pin_num_t mosi_pin;      
  hf_pin_num_t miso_pin;      
  hf_pin_num_t sclk_pin;      
  hf_u32_t clock_speed_hz;    
  hf_u8_t dma_channel;        
  hf_timeout_ms_t timeout_ms; 
  bool use_iomux;             
 
  hf_spi_bus_config_t() noexcept
      : host(HF_INVALID_HOST), mosi_pin(HF_INVALID_PIN), miso_pin(HF_INVALID_PIN),
        sclk_pin(HF_INVALID_PIN), clock_speed_hz(1000000), dma_channel(0), timeout_ms(1000),
        use_iomux(true) {}
};
 
//==============================================================================
// ESP32 SPI DEVICE CONFIG STRUCT
//==============================================================================
struct hf_spi_device_config_t {
  hf_u32_t clock_speed_hz;                
  hf_spi_mode_t mode;                     
  hf_pin_num_t cs_pin;                    
  hf_u8_t queue_size;                     
  hf_u8_t command_bits;                   
  hf_u8_t address_bits;                   
  hf_u8_t dummy_bits;                     
  hf_u16_t duty_cycle_pos;                
  hf_u16_t cs_ena_pretrans;               
  hf_u8_t cs_ena_posttrans;               
  hf_u32_t flags;                         
  hf_u32_t input_delay_ns;                
  void (*pre_cb)(void*);                  
  void (*post_cb)(void*);                 
  void* user_ctx;                         
  hf_spi_clock_source_t clock_source;     
  hf_spi_sampling_point_t sampling_point; 
 
  hf_spi_device_config_t() noexcept
      : clock_speed_hz(1000000), mode(hf_spi_mode_t::HF_SPI_MODE_0), cs_pin(HF_INVALID_PIN),
        queue_size(32), command_bits(0), address_bits(0), dummy_bits(0), duty_cycle_pos(128),
        cs_ena_pretrans(2), cs_ena_posttrans(2), flags(0), input_delay_ns(0), pre_cb(nullptr),
        post_cb(nullptr), user_ctx(nullptr),
        clock_source(static_cast<hf_spi_clock_source_t>(SPI_CLK_SRC_DEFAULT)),
#ifdef HF_MCU_ESP32C6
        sampling_point(static_cast<hf_spi_sampling_point_t>(SPI_SAMPLING_POINT_PHASE_0)){
#else
        sampling_point(static_cast<hf_spi_sampling_point_t>(SPI_SAMPLING_POINT_PHASE_1)) {
#endif
        }
};
 
// ESP-IDF SPI device flags (matching ESP-IDF example patterns)
#define HF_SPI_DEVICE_HALFDUPLEX (1 << 0)  // Half-duplex mode
#define HF_SPI_DEVICE_POSITIVE_CS (1 << 1) // CS active high
#define HF_SPI_DEVICE_CLK_AS_CS (1 << 2)   // Clock idle state
#define HF_SPI_DEVICE_NO_DUMMY (1 << 3)    // No dummy bits
#define HF_SPI_DEVICE_DDRCLK (1 << 4)      // DDR clock mode
 
//==============================================================================
// END OF ESPSPI TYPES - MINIMAL AND ESSENTIAL ONLY
//==============================================================================