master.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/flags>
#include <idfxx/future>
#include <idfxx/gpio>
#include <idfxx/intr_alloc>
 
#include <atomic>
#include <chrono>
#include <cstdint>
#include <driver/spi_master.h>
#include <esp_idf_version.h>
#include <frequency/frequency>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <vector>
 
namespace idfxx::spi {
 
enum class host_device : int {
    spi1 = SPI1_HOST, 
    spi2 = SPI2_HOST, 
#if SOC_SPI_PERIPH_NUM > 2
    spi3 = SPI3_HOST, 
#endif
};
 
enum class dma_chan : int {
    disabled = SPI_DMA_DISABLED, 
#if CONFIG_IDF_TARGET_ESP32
    ch_1 = SPI_DMA_CH1, 
    ch_2 = SPI_DMA_CH2, 
#endif
    ch_auto = SPI_DMA_CH_AUTO, 
};
 
enum class bus_flags : uint32_t {
    slave = SPICOMMON_BUSFLAG_SLAVE,           
    master = SPICOMMON_BUSFLAG_MASTER,         
    iomux_pins = SPICOMMON_BUSFLAG_IOMUX_PINS, 
    sclk = SPICOMMON_BUSFLAG_SCLK,             
    miso = SPICOMMON_BUSFLAG_MISO,             
    mosi = SPICOMMON_BUSFLAG_MOSI,             
    dual =
        SPICOMMON_BUSFLAG_DUAL, 
    wphd = SPICOMMON_BUSFLAG_WPHD, 
    quad = SPICOMMON_BUSFLAG_QUAD, 
    io4_io7 = SPICOMMON_BUSFLAG_IO4_IO7, 
    octal = SPICOMMON_BUSFLAG_OCTAL, 
    native_pins = SPICOMMON_BUSFLAG_NATIVE_PINS,   
    slp_allow_pd = SPICOMMON_BUSFLAG_SLP_ALLOW_PD, 
};
 
enum class device_flags : uint32_t {
    txbit_lsbfirst = SPI_DEVICE_TXBIT_LSBFIRST,     
    rxbit_lsbfirst = SPI_DEVICE_RXBIT_LSBFIRST,     
    bit_lsbfirst = SPI_DEVICE_BIT_LSBFIRST,         
    three_wire = SPI_DEVICE_3WIRE,                  
    positive_cs = SPI_DEVICE_POSITIVE_CS,           
    halfduplex = SPI_DEVICE_HALFDUPLEX,             
    clk_as_cs = SPI_DEVICE_CLK_AS_CS,               
    no_dummy = SPI_DEVICE_NO_DUMMY,                 
    ddrclk = SPI_DEVICE_DDRCLK,                     
    no_return_result = SPI_DEVICE_NO_RETURN_RESULT, 
};
 
enum class trans_flags : uint32_t {
    mode_dio = SPI_TRANS_MODE_DIO,                               
    mode_qio = SPI_TRANS_MODE_QIO,                               
    mode_oct = SPI_TRANS_MODE_OCT,                               
    use_rxdata = SPI_TRANS_USE_RXDATA,                           
    use_txdata = SPI_TRANS_USE_TXDATA,                           
    multiline_addr = SPI_TRANS_MULTILINE_ADDR,                   
    multiline_cmd = SPI_TRANS_MULTILINE_CMD,                     
    variable_cmd = SPI_TRANS_VARIABLE_CMD,                       
    variable_addr = SPI_TRANS_VARIABLE_ADDR,                     
    variable_dummy = SPI_TRANS_VARIABLE_DUMMY,                   
    cs_keep_active = SPI_TRANS_CS_KEEP_ACTIVE,                   
    dma_buffer_align_manual = SPI_TRANS_DMA_BUFFER_ALIGN_MANUAL, 
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
    dma_use_psram = SPI_TRANS_DMA_USE_PSRAM, 
#endif
};
 
} // namespace idfxx::spi
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::spi::bus_flags> = true;
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::spi::device_flags> = true;
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::spi::trans_flags> = true;
 
namespace idfxx::spi {
 
struct transaction {
    idfxx::flags<trans_flags> flags = {};    
    uint16_t cmd = 0;                        
    uint64_t addr = 0;                       
    std::span<const uint8_t> tx_buffer = {}; 
    std::span<uint8_t> rx_buffer = {};       
    size_t length = 0;                       
    size_t rx_length = 0;                    
    freq::hertz override_freq{0};            
    uint8_t command_bits = 0;                
    uint8_t address_bits = 0;                
    uint8_t dummy_bits = 0;                  
};
 
class master_device;
 
struct bus_config {
    union {
        idfxx::gpio mosi = gpio::nc(); 
        idfxx::gpio data0;             
    };
    union {
        idfxx::gpio miso = gpio::nc(); 
        idfxx::gpio data1;             
    };
    idfxx::gpio sclk = gpio::nc(); 
    union {
        idfxx::gpio quadwp = gpio::nc(); 
        idfxx::gpio data2; 
    };
    union {
        idfxx::gpio quadhd = gpio::nc(); 
        idfxx::gpio data3; 
    };
    idfxx::gpio data4 = gpio::nc(); 
    idfxx::gpio data5 = gpio::nc(); 
    idfxx::gpio data6 = gpio::nc(); 
    idfxx::gpio data7 = gpio::nc(); 
 
    gpio::level data_idle_level = gpio::level::low; 
    size_t max_transfer_sz = 0; 
 
    idfxx::flags<bus_flags> flags = {}; 
 
    std::optional<idfxx::core_id> isr_cpu_id = std::nullopt; 
 
    idfxx::intr_levels intr_levels = {};            
    idfxx::flags<idfxx::intr_flag> intr_flags = {}; 
};
 
class master_bus {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_bus(enum host_device host, enum dma_chan dma_chan, struct bus_config config);
#endif
 
    [[nodiscard]] static result<master_bus>
    make(enum host_device host, enum dma_chan dma_chan, struct bus_config config);
 
    ~master_bus();
 
    master_bus(const master_bus&) = delete;
    master_bus& operator=(const master_bus&) = delete;
 
    master_bus(master_bus&& other) noexcept;
 
    master_bus& operator=(master_bus&& other) noexcept;
 
    [[nodiscard]] enum host_device host() const { return _host; }
 
    [[nodiscard]] size_t max_transaction_length() const;
 
private:
    explicit master_bus(enum host_device host);
 
    enum host_device _host;
    bool _initialized = true;
};
 
class master_device {
public:
    struct config {
        uint8_t command_bits = 0;     
        uint8_t address_bits = 0;     
        uint8_t dummy_bits = 0;       
        uint8_t mode = 0;             
        uint16_t duty_cycle_pos = 0;  
        uint16_t cs_ena_pretrans = 0; 
        uint8_t cs_ena_posttrans = 0; 
        freq::hertz clock_speed{0};   
        std::chrono::nanoseconds input_delay{0}; 
        idfxx::gpio cs = gpio::nc();             
        idfxx::flags<device_flags> flags = {};   
        int queue_size = 1;                      
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit master_device(master_bus& bus, const struct config& config);
#endif
 
    [[nodiscard]] static result<master_device> make(master_bus& bus, const struct config& config);
 
    ~master_device();
 
    master_device(const master_device&) = delete;
    master_device& operator=(const master_device&) = delete;
    master_device(master_device&& other) noexcept;
    master_device& operator=(master_device&& other) noexcept;
 
    // =========================================================================
    // Accessors
    // =========================================================================
 
    [[nodiscard]] master_bus& bus() const {
        assert(_bus != nullptr);
        return *_bus;
    }
 
    [[nodiscard]] spi_device_handle_t idf_handle() const { return _handle; }
 
    [[nodiscard]] freq::hertz frequency() const;
 
    // =========================================================================
    // Simple API (byte-oriented, blocking)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void transmit(std::span<const uint8_t> tx_data) { unwrap(try_transmit(tx_data)); }
 
    void receive(std::span<uint8_t> rx_data) { unwrap(try_receive(rx_data)); }
 
    [[nodiscard]] std::vector<uint8_t> receive(size_t size) { return unwrap(try_receive(size)); }
 
    void transfer(std::span<const uint8_t> tx_data, std::span<uint8_t> rx_data) {
        unwrap(try_transfer(tx_data, rx_data));
    }
#endif
 
    [[nodiscard]] result<void> try_transmit(std::span<const uint8_t> tx_data);
 
    [[nodiscard]] result<void> try_receive(std::span<uint8_t> rx_data);
 
    [[nodiscard]] result<std::vector<uint8_t>> try_receive(size_t size);
 
    [[nodiscard]] result<void> try_transfer(std::span<const uint8_t> tx_data, std::span<uint8_t> rx_data);
 
    // =========================================================================
    // Full transaction API (blocking)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void transmit(const transaction& trans) { unwrap(try_transmit(trans)); }
#endif
 
    [[nodiscard]] result<void> try_transmit(const transaction& trans);
 
    // =========================================================================
    // Polling API (busy-wait)
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void polling_transmit(std::span<const uint8_t> tx_data) { unwrap(try_polling_transmit(tx_data)); }
 
    void polling_receive(std::span<uint8_t> rx_data) { unwrap(try_polling_receive(rx_data)); }
 
    [[nodiscard]] std::vector<uint8_t> polling_receive(size_t size) { return unwrap(try_polling_receive(size)); }
 
    void polling_transfer(std::span<const uint8_t> tx_data, std::span<uint8_t> rx_data) {
        unwrap(try_polling_transfer(tx_data, rx_data));
    }
 
    void polling_transmit(const transaction& trans) { unwrap(try_polling_transmit(trans)); }
#endif
 
    [[nodiscard]] result<void> try_polling_transmit(std::span<const uint8_t> tx_data);
 
    [[nodiscard]] result<void> try_polling_receive(std::span<uint8_t> rx_data);
 
    [[nodiscard]] result<std::vector<uint8_t>> try_polling_receive(size_t size);
 
    [[nodiscard]] result<void> try_polling_transfer(std::span<const uint8_t> tx_data, std::span<uint8_t> rx_data);
 
    [[nodiscard]] result<void> try_polling_transmit(const transaction& trans);
 
    // =========================================================================
    // Async queue API
    // =========================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] idfxx::future<void> queue_trans(const transaction& trans) { return unwrap(try_queue_trans(trans)); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] idfxx::future<void>
    queue_trans(const transaction& trans, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_queue_trans(trans, timeout));
    }
 
#endif
 
    [[nodiscard]] result<idfxx::future<void>> try_queue_trans(const transaction& trans);
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<idfxx::future<void>>
    try_queue_trans(const transaction& trans, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_queue_trans(trans, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    // =========================================================================
    // Bus exclusivity (Lockable interface)
    // =========================================================================
 
    void lock() const;
 
    [[nodiscard]] bool try_lock() const noexcept;
 
    void unlock() const;
 
private:
    // Opaque async state held in the .cpp. master_device keeps a single
    // unique_ptr to it, so the class stays cheap to move while the mutexes,
    // condition variable, and slot pool keep a stable address across the
    // device's lifetime.
    struct async_state;
 
    explicit master_device(master_bus* bus, spi_device_handle_t handle, size_t queue_size);
 
    void _delete() noexcept;
 
    using _trans_fn = esp_err_t (*)(spi_device_handle_t, spi_transaction_t*);
 
    [[nodiscard]] result<void> _simple_trans(std::span<const uint8_t> tx, std::span<uint8_t> rx, _trans_fn fn);
    [[nodiscard]] result<void> _full_trans(const transaction& trans, _trans_fn fn);
 
    [[nodiscard]] result<idfxx::future<void>>
    _try_queue_trans(const transaction& trans, std::optional<std::chrono::milliseconds> timeout);
    [[nodiscard]] result<void> _try_wait_for(
        const std::shared_ptr<std::atomic<bool>>& done_flag,
        std::optional<std::chrono::milliseconds> timeout
    );
 
    [[nodiscard]] result<uint16_t> _acquire_slot(std::optional<std::chrono::milliseconds> timeout);
    void _release_slot(uint16_t slot_idx) noexcept;
 
    static void _prepare_idf_trans(spi_transaction_t& idf_trans, const transaction& trans);
    static void _prepare_idf_trans_ext(spi_transaction_ext_t& idf_ext, const transaction& trans);
 
    master_bus* _bus = nullptr;
    spi_device_handle_t _handle = nullptr;
    std::unique_ptr<async_state> _async;
};
 
 
} // namespace idfxx::spi
 
namespace idfxx {
 
[[nodiscard]] inline std::string to_string(spi::host_device h) {
    switch (h) {
    case spi::host_device::spi1:
        return "SPI1";
    case spi::host_device::spi2:
        return "SPI2";
#if SOC_SPI_PERIPH_NUM > 2
    case spi::host_device::spi3:
        return "SPI3";
#endif
    default:
        return "unknown(" + std::to_string(static_cast<int>(h)) + ")";
    }
}
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
template<>
struct formatter<idfxx::spi::host_device> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::spi::host_device h, FormatContext& ctx) const {
        auto s = idfxx::to_string(h);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT