LibXR::ESP32SPI Class Reference

Inheritance diagram for LibXR::ESP32SPI:

Collaboration diagram for LibXR::ESP32SPI:

Public Member Functions
	ESP32SPI (spi_host_device_t host, int sclk_pin, int miso_pin, int mosi_pin, RawData dma_rx, RawData dma_tx, SPI::Configuration config={ SPI::ClockPolarity::LOW, SPI::ClockPhase::EDGE_1, SPI::Prescaler::DIV_8, false, }, uint32_t dma_enable_min_size=3U, bool enable_dma=true)
ErrorCode	ReadAndWrite (RawData read_data, ConstRawData write_data, OperationRW &op, bool in_isr=false) override
	进行 SPI 读写操作。Performs SPI read and write operations.
ErrorCode	SetConfig (SPI::Configuration config) override
	设置 SPI 配置参数。Sets SPI configuration parameters.
ErrorCode	MemRead (uint16_t reg, RawData read_data, OperationRW &op, bool in_isr=false) override
	从 SPI 设备的寄存器读取数据。 Reads data from a specific register of the SPI device.
ErrorCode	MemWrite (uint16_t reg, ConstRawData write_data, OperationRW &op, bool in_isr=false) override
	向 SPI 设备的寄存器写入数据。 Writes data to a specific register of the SPI device.
ErrorCode	Transfer (size_t size, OperationRW &op, bool in_isr=false) override
	进行一次SPI传输（使用当前缓冲区数据，零拷贝，支持双缓冲）。 Performs a SPI transfer (zero-copy, supports double buffering).
uint32_t	GetMaxBusSpeed () const override
	获取 SPI 设备的最大时钟速度。Gets the maximum clock speed of the SPI device.
Prescaler	GetMaxPrescaler () const override
	获取 SPI 设备的最大分频系数。Gets the maximum prescaler of the SPI device.
RawData	GetRxBuffer ()
RawData	GetTxBuffer ()
Public Member Functions inherited from LibXR::SPI
	SPI (RawData rx_buffer, RawData tx_buffer)
	构造函数。Constructor.
virtual ErrorCode	Read (RawData read_data, OperationRW &op, bool in_isr=false)
	进行 SPI 读取操作。Performs SPI read operation.
virtual ErrorCode	Write (ConstRawData write_data, OperationRW &op, bool in_isr=false)
	进行 SPI 写入操作。Performs SPI write operation.
uint32_t	GetBusSpeed () const
	获取 SPI 设备的当前总线速度。Gets the current bus speed of the SPI device.
Prescaler	CalcPrescaler (uint32_t target_max_bus_speed, uint32_t target_min_bus_speed, bool increase)
	计算 SPI 分频系数。Calculates the SPI prescaler.
RawData	GetRxBuffer ()
	获取接收数据的缓冲区。Gets the buffer for storing received data.
RawData	GetTxBuffer ()
	获取发送数据的缓冲区。Gets the buffer for storing data to be sent.
void	SwitchBuffer ()
	切换缓冲区。Switches the buffer.
void	SetActiveLength (size_t len)
	设置缓冲区的有效数据长度。Sets the length of valid data in the buffer.
size_t	GetActiveLength () const
	获取缓冲区的有效数据长度。Gets the length of valid data in the buffer.
Configuration &	GetConfig ()
	获取 SPI 配置参数。Gets the SPI configuration parameters.
bool	IsDoubleBuffer () const
	检查是否使用双缓冲区。Checks if double buffering is enabled.

Private Member Functions
bool	Acquire ()
void	Release ()
ErrorCode	InitializeHardware ()
ErrorCode	ConfigurePins ()
ErrorCode	ResolveClockSource (uint32_t &source_hz)
ErrorCode	InstallInterrupt ()
ErrorCode	InitDmaBackend ()
void	HandleInterrupt ()
void	FinishAsync (bool in_isr, ErrorCode ec)
bool	CanUseDma (size_t size) const
ErrorCode	EnsureReadyAndAcquire ()
ErrorCode	ReturnAsyncStartResult (ErrorCode ec, bool started)
ErrorCode	StartAsyncTransfer (const uint8_t *tx, uint8_t *rx, size_t size, bool enable_rx, RawData read_back, bool mem_read, OperationRW &op, bool &started)
void	ConfigureTransferRegisters (size_t size)
ErrorCode	ExecuteChunk (const uint8_t *tx, uint8_t *rx, size_t size, bool enable_rx)
ErrorCode	ExecuteTransfer (const uint8_t *tx, uint8_t *rx, size_t size, bool enable_rx)
bool	UseLocalDoubleBuffer () const
void	SwitchBufferLocal ()

Static Private Member Functions
static void	SpiIsrEntry (void *arg)
static ErrorCode	FinalizeSyncResult (OperationRW &op, bool in_isr, ErrorCode ec)
static ErrorCode	CompleteZeroSize (OperationRW &op, bool in_isr)

Private Attributes
spi_host_device_t	host_
spi_dev_t *	hw_ = nullptr
int	sclk_pin_
int	miso_pin_
int	mosi_pin_
uint32_t	source_clock_hz_ = 0
Flag::Atomic	busy_ {}
bool	initialized_ = false
uint32_t	dma_enable_min_size_ = 3U
bool	dma_requested_ = true
RawData	dma_rx_raw_ = {nullptr, 0}
RawData	dma_tx_raw_ = {nullptr, 0}
size_t	dbuf_rx_block_size_ = 0
size_t	dbuf_tx_block_size_ = 0
uint8_t	dbuf_active_block_ = 0
AsyncBlockWait	block_wait_ {}
bool	dbuf_enabled_ = false
intr_handle_t	intr_handle_ = nullptr
bool	intr_installed_ = false
bool	dma_enabled_ = false
void *	dma_ctx_ = nullptr
size_t	dma_max_transfer_bytes_ = 0
bool	async_running_ = false
size_t	async_dma_size_ = 0
bool	async_dma_rx_enabled_ = false
bool	mem_read_ = false
RawData	read_back_ = {nullptr, 0}
OperationRW	rw_op_

Static Private Attributes
static constexpr size_t	MAX_POLLING_TRANSFER_BYTES = SOC_SPI_MAXIMUM_BUFFER_SIZE
static constexpr size_t	MAX_DMA_TRANSFER_BYTES = SPI_LL_DMA_MAX_BIT_LEN / 8U

Additional Inherited Members
Public Types inherited from LibXR::SPI
enum class	ClockPolarity : uint8_t { LOW = 0 , HIGH = 1 }
	定义 SPI 时钟极性。Defines the SPI clock polarity. More...
enum class	ClockPhase : uint8_t { EDGE_1 = 0 , EDGE_2 = 1 }
	定义 SPI 时钟相位。Defines the SPI clock phase. More...
enum class	Prescaler : uint8_t {   DIV_1 = 0 , DIV_2 = 1 , DIV_4 = 2 , DIV_8 = 3 ,   DIV_16 = 4 , DIV_32 = 5 , DIV_64 = 6 , DIV_128 = 7 ,   DIV_256 = 8 , DIV_512 = 9 , DIV_1024 = 10 , DIV_2048 = 11 ,   DIV_4096 = 12 , DIV_8192 = 13 , DIV_16384 = 14 , DIV_32768 = 15 ,   DIV_65536 = 16 , UNKNOWN = 0xFF }
using	OperationRW = WriteOperation
	定义读写操作类型的别名。Defines an alias for the read/write operation type.
Static Public Member Functions inherited from LibXR::SPI
static constexpr uint32_t	PrescalerToDiv (Prescaler prescaler)
	将分频系数转换为除数。Converts a prescaler to a divisor.

Detailed Description

Definition at line 19 of file esp_spi.hpp.

Constructor & Destructor Documentation

ESP32SPI()

LibXR::ESP32SPI::ESP32SPI	(	spi_host_device_t	host,
		int	sclk_pin,
		int	miso_pin,
		int	mosi_pin,
		RawData	dma_rx,
		RawData	dma_tx,
		SPI::Configuration	config = { SPI::ClockPolarity::LOW, SPI::ClockPhase::EDGE_1, SPI::Prescaler::DIV_8, false, },
		uint32_t	dma_enable_min_size = 3U,
		bool	enable_dma = true )

Definition at line 113 of file esp_spi.cpp.

    : SPI(dma_rx, dma_tx),
      host_(host),
      sclk_pin_(sclk_pin),
      miso_pin_(miso_pin),
      mosi_pin_(mosi_pin),
      dma_enable_min_size_(dma_enable_min_size),
      dma_requested_(enable_dma),
      dma_rx_raw_(dma_rx),
      dma_tx_raw_(dma_tx),
      dbuf_rx_block_size_(dma_rx.size_ / 2U),
      dbuf_tx_block_size_(dma_tx.size_ / 2U)
{
  ASSERT(host_ != SPI1_HOST);
  ASSERT(host_ < SPI_HOST_MAX);
  ASSERT(static_cast<int>(host_) < SOC_SPI_PERIPH_NUM);
  ASSERT(dma_rx_raw_.addr_ != nullptr);
  ASSERT(dma_tx_raw_.addr_ != nullptr);
  ASSERT(dma_rx_raw_.size_ > 0U);
  ASSERT(dma_tx_raw_.size_ > 0U);
 
  if (InitializeHardware() != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
 
  if (ConfigurePins() != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
 
  if (InstallInterrupt() != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
 
  if (dma_requested_)
  {
    const ErrorCode dma_ans = InitDmaBackend();
    ASSERT(dma_ans == ErrorCode::OK);
    if (dma_ans != ErrorCode::OK)
    {
      return;
    }
  }
 
  if (SetConfig(config) != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
}

Member Function Documentation

Acquire()

bool LibXR::ESP32SPI::Acquire ( )

private

Definition at line 171 of file esp_spi.cpp.

{ return !busy_.TestAndSet(); }

CanUseDma()

bool LibXR::ESP32SPI::CanUseDma ( size_t size ) const

private

Definition at line 542 of file esp_spi.cpp.

{
  return dma_requested_ && dma_enabled_ && (dma_ctx_ != nullptr) &&
         (size > dma_enable_min_size_) && (size <= dma_max_transfer_bytes_);
}

CompleteZeroSize()

ErrorCode LibXR::ESP32SPI::CompleteZeroSize ( OperationRW & op, bool in_isr )

staticprivate

Definition at line 570 of file esp_spi.cpp.

{
  return FinalizeSyncResult(op, in_isr, ErrorCode::OK);
}

ConfigurePins()

ErrorCode LibXR::ESP32SPI::ConfigurePins ( )

private

Definition at line 236 of file esp_spi.cpp.

{
  if (!initialized_ || (hw_ == nullptr))
  {
    return ErrorCode::STATE_ERR;
  }
 
  const auto& signal = spi_periph_signal[host_];
 
  if (sclk_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_OUTPUT_GPIO(sclk_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    esp_rom_gpio_pad_select_gpio(static_cast<uint32_t>(sclk_pin_));
    esp_rom_gpio_connect_out_signal(sclk_pin_, signal.spiclk_out, false, false);
    gpio_input_enable(static_cast<gpio_num_t>(sclk_pin_));
    esp_rom_gpio_connect_in_signal(sclk_pin_, signal.spiclk_in, false);
  }
 
  if (mosi_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_OUTPUT_GPIO(mosi_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    esp_rom_gpio_pad_select_gpio(static_cast<uint32_t>(mosi_pin_));
    esp_rom_gpio_connect_out_signal(mosi_pin_, signal.spid_out, false, false);
    gpio_input_enable(static_cast<gpio_num_t>(mosi_pin_));
    esp_rom_gpio_connect_in_signal(mosi_pin_, signal.spid_in, false);
  }
 
  if (miso_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_GPIO(miso_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    gpio_input_enable(static_cast<gpio_num_t>(miso_pin_));
    esp_rom_gpio_connect_in_signal(miso_pin_, signal.spiq_in, false);
  }
 
  return ErrorCode::OK;
}

ConfigureTransferRegisters()

void LibXR::ESP32SPI::ConfigureTransferRegisters ( size_t size )

private

Definition at line 584 of file esp_spi.cpp.

{
  static constexpr spi_line_mode_t LINE_MODE = {
      .cmd_lines = 1,
      .addr_lines = 1,
      .data_lines = 1,
  };
  const size_t bitlen = size * 8U;
 
  spi_ll_master_set_line_mode(hw_, LINE_MODE);
  spi_ll_set_mosi_bitlen(hw_, bitlen);
  spi_ll_set_miso_bitlen(hw_, bitlen);
  spi_ll_set_command_bitlen(hw_, 0);
  spi_ll_set_addr_bitlen(hw_, 0);
  spi_ll_set_command(hw_, 0, 0, false);
  spi_ll_set_address(hw_, 0, 0, false);
  hw_->user.usr_command = 0;
  hw_->user.usr_addr = 0;
}

EnsureReadyAndAcquire()

ErrorCode LibXR::ESP32SPI::EnsureReadyAndAcquire ( )

private

Definition at line 548 of file esp_spi.cpp.

{
  if (!initialized_)
  {
    return ErrorCode::INIT_ERR;
  }
  if (!Acquire())
  {
    return ErrorCode::BUSY;
  }
  return ErrorCode::OK;
}

ExecuteChunk()

ErrorCode LibXR::ESP32SPI::ExecuteChunk ( const uint8_t * tx, uint8_t * rx, size_t size, bool enable_rx )

private

Definition at line 700 of file esp_spi.cpp.

{
  if ((size == 0U) || (size > MAX_POLLING_TRANSFER_BYTES))
  {
    return ErrorCode::SIZE_ERR;
  }
 
  static constexpr std::array<uint8_t, MAX_POLLING_TRANSFER_BYTES> ZERO = {};
  const uint8_t* tx_data = (tx != nullptr) ? tx : ZERO.data();
 
  ConfigureTransferRegisters(size);
  spi_ll_enable_mosi(hw_, 1);
  spi_ll_enable_miso(hw_, enable_rx ? 1 : 0);
  spi_ll_write_buffer(hw_, tx_data, size * 8U);
  spi_ll_clear_int_stat(hw_);
  spi_ll_apply_config(hw_);
  spi_ll_user_start(hw_);
 
  const uint64_t timeout_us = CalcPollingTimeoutUs(size, GetBusSpeed());
  const uint64_t start_us = GetNowUs();
  while (!spi_ll_usr_is_done(hw_))
  {
    if ((GetNowUs() - start_us) > timeout_us)
    {
      return ErrorCode::TIMEOUT;
    }
  }
 
  if (enable_rx && (rx != nullptr))
  {
    spi_ll_read_buffer(hw_, rx, size * 8U);
  }
  spi_ll_clear_int_stat(hw_);
  return ErrorCode::OK;
}

ExecuteTransfer()

ErrorCode LibXR::ESP32SPI::ExecuteTransfer ( const uint8_t * tx, uint8_t * rx, size_t size, bool enable_rx )

private

Definition at line 737 of file esp_spi.cpp.

{
  size_t offset = 0U;
  while (offset < size)
  {
    const size_t remain = size - offset;
    const size_t chunk = std::min(remain, MAX_POLLING_TRANSFER_BYTES);
    const uint8_t* tx_chunk = (tx != nullptr) ? (tx + offset) : nullptr;
    uint8_t* rx_chunk = (enable_rx && (rx != nullptr)) ? (rx + offset) : nullptr;
 
    const ErrorCode ec = ExecuteChunk(tx_chunk, rx_chunk, chunk, enable_rx);
    if (ec != ErrorCode::OK)
    {
      return ec;
    }
    offset += chunk;
  }
 
  return ErrorCode::OK;
}

FinalizeSyncResult()

ErrorCode LibXR::ESP32SPI::FinalizeSyncResult ( OperationRW & op, bool in_isr, ErrorCode ec )

staticprivate

Definition at line 561 of file esp_spi.cpp.

{
  if (op.type != OperationRW::OperationType::BLOCK)
  {
    op.UpdateStatus(in_isr, ec);
  }
  return ec;
}

FinishAsync()

void IRAM_ATTR LibXR::ESP32SPI::FinishAsync ( bool in_isr, ErrorCode ec )

private

Definition at line 380 of file esp_spi.cpp.

{
  if (!async_running_)
  {
    return;
  }
 
#if CONFIG_IDF_TARGET_ESP32
  // Keep ESP32 SPI DMA workaround state in sync with transfer lifecycle.
  if (dma_enabled_)
  {
    spi_dma_ctx_t* ctx = ToDmaCtx(dma_ctx_);
    if (ctx != nullptr)
    {
      spicommon_dmaworkaround_idle(ctx->tx_dma_chan.chan_id);
    }
  }
#endif
 
  spi_ll_disable_int(hw_);
  spi_ll_clear_int_stat(hw_);
 
  RawData rx = {nullptr, 0U};
  const RawData read_back = read_back_;
  const bool mem_read = mem_read_;
  if ((ec == ErrorCode::OK) && async_dma_rx_enabled_)
  {
    rx = GetRxBuffer();
#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE || SOC_PSRAM_DMA_CAPABLE
    if (!CacheSyncDmaBuffer(rx.addr_, async_dma_size_, false))
    {
      ec = ErrorCode::FAILED;
    }
#endif
  }
 
  if ((ec == ErrorCode::OK) && (read_back.size_ > 0U))
  {
    if (rx.addr_ == nullptr)
    {
      rx = GetRxBuffer();
    }
    uint8_t* src = static_cast<uint8_t*>(rx.addr_);
    if (mem_read)
    {
      ASSERT(rx.size_ >= (read_back.size_ + 1U));
      src += 1;
    }
    else
    {
      ASSERT(rx.size_ >= read_back.size_);
    }
    Memory::FastCopy(read_back.addr_, src, read_back.size_);
  }
 
  if (ec == ErrorCode::OK)
  {
    SwitchBufferLocal();
  }
 
  async_running_ = false;
  async_dma_size_ = 0U;
  async_dma_rx_enabled_ = false;
  mem_read_ = false;
  read_back_ = {nullptr, 0};
  Release();
  if (rw_op_.type == OperationRW::OperationType::BLOCK)
  {
    (void)block_wait_.TryPost(in_isr, ec);
  }
  else
  {
    rw_op_.UpdateStatus(in_isr, ec);
  }
}

GetMaxBusSpeed()

uint32_t LibXR::ESP32SPI::GetMaxBusSpeed ( ) const

overridevirtual

获取 SPI 设备的最大时钟速度。Gets the maximum clock speed of the SPI device.

Returns

SPI 设备的最大时钟速度（单位：Hz）。The maximum clock speed of the SPI device (in Hz).

Implements LibXR::SPI.

Definition at line 935 of file esp_spi.cpp.

{ return source_clock_hz_; }

GetMaxPrescaler()

SPI::Prescaler LibXR::ESP32SPI::GetMaxPrescaler ( ) const

overridevirtual

获取 SPI 设备的最大分频系数。Gets the maximum prescaler of the SPI device.

Returns

SPI 设备的最大分频系数。The maximum prescaler of the SPI device.

Implements LibXR::SPI.

Definition at line 937 of file esp_spi.cpp.

{ return Prescaler::DIV_65536; }

GetRxBuffer()

RawData LibXR::ESP32SPI::GetRxBuffer

(

)

Definition at line 512 of file esp_spi.cpp.

{
  if (UseLocalDoubleBuffer())
  {
    auto* base = static_cast<uint8_t*>(dma_rx_raw_.addr_);
    return {base + static_cast<size_t>(dbuf_active_block_) * dbuf_rx_block_size_,
            dbuf_rx_block_size_};
  }
  return dma_rx_raw_;
}

GetTxBuffer()

RawData LibXR::ESP32SPI::GetTxBuffer

(

)

Definition at line 523 of file esp_spi.cpp.

{
  if (UseLocalDoubleBuffer())
  {
    auto* base = static_cast<uint8_t*>(dma_tx_raw_.addr_);
    return {base + static_cast<size_t>(dbuf_active_block_) * dbuf_tx_block_size_,
            dbuf_tx_block_size_};
  }
  return dma_tx_raw_;
}

HandleInterrupt()

void IRAM_ATTR LibXR::ESP32SPI::HandleInterrupt ( )

private

Definition at line 359 of file esp_spi.cpp.

{
  if ((hw_ == nullptr) || !initialized_)
  {
    return;
  }
 
  if (!async_running_)
  {
    spi_ll_clear_int_stat(hw_);
    return;
  }
 
  if (!spi_ll_usr_is_done(hw_))
  {
    return;
  }
 
  FinishAsync(true, ErrorCode::OK);
}

InitDmaBackend()

ErrorCode LibXR::ESP32SPI::InitDmaBackend ( )

private

Definition at line 314 of file esp_spi.cpp.

{
  if (dma_enabled_)
  {
    return ErrorCode::OK;
  }
 
  spi_dma_ctx_t* ctx = nullptr;
  if (spicommon_dma_chan_alloc(host_, SPI_DMA_CH_AUTO, &ctx) != ESP_OK)
  {
    return ErrorCode::INIT_ERR;
  }
 
  const size_t cfg_max_size = std::max(dma_rx_raw_.size_, dma_tx_raw_.size_);
  int actual_max_size = 0;
  if (spicommon_dma_desc_alloc(ctx, static_cast<int>(cfg_max_size), &actual_max_size) !=
      ESP_OK)
  {
    (void)spicommon_dma_chan_free(ctx);
    return ErrorCode::INIT_ERR;
  }
 
  dma_ctx_ = ctx;
  dma_enabled_ = true;
  dma_max_transfer_bytes_ =
      std::min<size_t>({static_cast<size_t>(actual_max_size), dma_rx_raw_.size_,
                        dma_tx_raw_.size_, MAX_DMA_TRANSFER_BYTES});
 
  if (dma_max_transfer_bytes_ == 0U)
  {
    return ErrorCode::INIT_ERR;
  }
 
  return ErrorCode::OK;
}

InitializeHardware()

ErrorCode LibXR::ESP32SPI::InitializeHardware ( )

private

Definition at line 175 of file esp_spi.cpp.

{
  if (initialized_)
  {
    return ErrorCode::OK;
  }
 
  if ((host_ <= SPI1_HOST) || (host_ >= SPI_HOST_MAX) ||
      (static_cast<int>(host_) >= SOC_SPI_PERIPH_NUM))
  {
    return ErrorCode::ARG_ERR;
  }
 
  const auto& signal = spi_periph_signal[host_];
  hw_ = signal.hw;
  if (hw_ == nullptr)
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  PERIPH_RCC_ATOMIC()
  {
    (void)__DECLARE_RCC_ATOMIC_ENV;
    spi_ll_enable_bus_clock(host_, true);
    spi_ll_reset_register(host_);
  }
  spi_ll_enable_clock(host_, true);
  spi_ll_master_init(hw_);
 
  const spi_line_mode_t line_mode = {
      .cmd_lines = 1,
      .addr_lines = 1,
      .data_lines = 1,
  };
  spi_ll_master_set_line_mode(hw_, line_mode);
  spi_ll_set_half_duplex(hw_, false);
  spi_ll_set_tx_lsbfirst(hw_, false);
  spi_ll_set_rx_lsbfirst(hw_, false);
  spi_ll_set_mosi_delay(hw_, 0, 0);
  spi_ll_enable_mosi(hw_, 1);
  spi_ll_enable_miso(hw_, 1);
  spi_ll_set_dummy(hw_, 0);
  spi_ll_set_command_bitlen(hw_, 0);
  spi_ll_set_addr_bitlen(hw_, 0);
  spi_ll_set_command(hw_, 0, 0, false);
  spi_ll_set_address(hw_, 0, 0, false);
  hw_->user.usr_command = 0;
  hw_->user.usr_addr = 0;
 
  spi_ll_set_clk_source(hw_, SPI_CLK_SRC_DEFAULT);
  if (ResolveClockSource(source_clock_hz_) != ErrorCode::OK)
  {
    return ErrorCode::INIT_ERR;
  }
 
  spi_ll_disable_int(hw_);
  spi_ll_clear_int_stat(hw_);
  initialized_ = true;
  return ErrorCode::OK;
}

InstallInterrupt()

ErrorCode LibXR::ESP32SPI::InstallInterrupt ( )

private

Definition at line 295 of file esp_spi.cpp.

{
  if (intr_installed_)
  {
    return ErrorCode::OK;
  }
 
  const int irq_source = static_cast<int>(spi_periph_signal[host_].irq);
  if (esp_intr_alloc(irq_source, ESP_INTR_FLAG_IRAM, &ESP32SPI::SpiIsrEntry, this,
                     &intr_handle_) != ESP_OK)
  {
    intr_handle_ = nullptr;
    return ErrorCode::INIT_ERR;
  }
 
  intr_installed_ = true;
  return ErrorCode::OK;
}

MemRead()

ErrorCode LibXR::ESP32SPI::MemRead ( uint16_t reg, RawData read_data, OperationRW & op, bool in_isr = false )

overridevirtual

从 SPI 设备的寄存器读取数据。 Reads data from a specific register of the SPI device.

Parameters

reg	寄存器地址。Register address.
read_data	读取的数据缓冲区。Buffer to store read data.
op	操作类型（同步/异步）。Operation mode (sync/async).
in_isr	是否在中断中进行操作。Whether the operation is performed in an ISR.

Returns

操作结果的错误码。Error code indicating success or failure.

Implements LibXR::SPI.

Definition at line 812 of file esp_spi.cpp.

{
  if (read_data.size_ == 0U)
  {
    return CompleteZeroSize(op, in_isr);
  }
 
  const ErrorCode lock_ec = EnsureReadyAndAcquire();
  if (lock_ec != ErrorCode::OK)
  {
    return lock_ec;
  }
 
  RawData rx = GetRxBuffer();
  RawData tx = GetTxBuffer();
  const size_t total = read_data.size_ + 1U;
 
  ASSERT(rx.size_ >= total);
  ASSERT(tx.size_ >= total);
 
  auto* tx_ptr = static_cast<uint8_t*>(tx.addr_);
  tx_ptr[0] = static_cast<uint8_t>(reg | 0x80U);
  Memory::FastSet(tx_ptr + 1, 0x00, read_data.size_);
 
  if (CanUseDma(total))
  {
    bool started = false;
    const ErrorCode ec = StartAsyncTransfer(tx_ptr, static_cast<uint8_t*>(rx.addr_),
                                            total, true, read_data, true, op, started);
    return ReturnAsyncStartResult(ec, started);
  }
 
  const ErrorCode ec =
      ExecuteTransfer(tx_ptr, static_cast<uint8_t*>(rx.addr_), total, true);
  if (ec == ErrorCode::OK)
  {
    auto* rx_ptr = static_cast<uint8_t*>(rx.addr_);
    Memory::FastCopy(read_data.addr_, rx_ptr + 1, read_data.size_);
    SwitchBufferLocal();
  }
 
  Release();
  return FinalizeSyncResult(op, in_isr, ec);
}

MemWrite()

ErrorCode LibXR::ESP32SPI::MemWrite ( uint16_t reg, ConstRawData write_data, OperationRW & op, bool in_isr = false )

overridevirtual

向 SPI 设备的寄存器写入数据。 Writes data to a specific register of the SPI device.

Parameters

reg	寄存器地址。Register address.
write_data	写入的数据缓冲区。Buffer containing data to write.
op	操作类型（同步/异步）。Operation mode (sync/async).
in_isr	是否在中断中进行操作。Whether the operation is performed in an ISR.

Returns

操作结果的错误码。Error code indicating success or failure.

Implements LibXR::SPI.

Definition at line 857 of file esp_spi.cpp.

{
  if (write_data.size_ == 0U)
  {
    return CompleteZeroSize(op, in_isr);
  }
 
  const ErrorCode lock_ec = EnsureReadyAndAcquire();
  if (lock_ec != ErrorCode::OK)
  {
    return lock_ec;
  }
 
  RawData tx = GetTxBuffer();
  const size_t total = write_data.size_ + 1U;
  ASSERT(tx.size_ >= total);
 
  auto* tx_ptr = static_cast<uint8_t*>(tx.addr_);
  tx_ptr[0] = static_cast<uint8_t>(reg & 0x7FU);
  Memory::FastCopy(tx_ptr + 1, write_data.addr_, write_data.size_);
 
  if (CanUseDma(total))
  {
    bool started = false;
    const ErrorCode ec = StartAsyncTransfer(tx_ptr, nullptr, total, false, {nullptr, 0},
                                            false, op, started);
    return ReturnAsyncStartResult(ec, started);
  }
 
  const ErrorCode ec = ExecuteTransfer(tx_ptr, nullptr, total, false);
  if (ec == ErrorCode::OK)
  {
    SwitchBufferLocal();
  }
 
  Release();
  return FinalizeSyncResult(op, in_isr, ec);
}

ReadAndWrite()

ErrorCode LibXR::ESP32SPI::ReadAndWrite ( RawData read_data, ConstRawData write_data, OperationRW & op, bool in_isr = false )

overridevirtual

进行 SPI 读写操作。Performs SPI read and write operations.

Parameters

read_data	存储读取数据的缓冲区。Buffer to store the read data.
write_data	需要写入的数据缓冲区。Buffer containing the data to be written.
op	读写操作类型。Type of read/write operation.
in_isr	是否在中断中进行操作。Whether the operation is performed in an ISR.

Returns

操作结果的错误码。Error code indicating the result of the operation.

Implements LibXR::SPI.

Definition at line 759 of file esp_spi.cpp.

{
  const size_t need = std::max(read_data.size_, write_data.size_);
  if (need == 0U)
  {
    return CompleteZeroSize(op, in_isr);
  }
 
  const ErrorCode lock_ec = EnsureReadyAndAcquire();
  if (lock_ec != ErrorCode::OK)
  {
    return lock_ec;
  }
 
  RawData rx = GetRxBuffer();
  RawData tx = GetTxBuffer();
  ASSERT(rx.size_ >= need);
  ASSERT(tx.size_ >= need);
 
  auto* tx_ptr = static_cast<uint8_t*>(tx.addr_);
  if (write_data.size_ > 0U)
  {
    Memory::FastCopy(tx_ptr, write_data.addr_, write_data.size_);
  }
  if (need > write_data.size_)
  {
    Memory::FastSet(tx_ptr + write_data.size_, 0x00, need - write_data.size_);
  }
 
  if (CanUseDma(need))
  {
    bool started = false;
    const ErrorCode ec = StartAsyncTransfer(tx_ptr, static_cast<uint8_t*>(rx.addr_), need,
                                            true, read_data, false, op, started);
    return ReturnAsyncStartResult(ec, started);
  }
 
  const ErrorCode ec =
      ExecuteTransfer(tx_ptr, static_cast<uint8_t*>(rx.addr_), need, true);
  if (ec == ErrorCode::OK)
  {
    if (read_data.size_ > 0U)
    {
      Memory::FastCopy(read_data.addr_, rx.addr_, read_data.size_);
    }
    SwitchBufferLocal();
  }
 
  Release();
  return FinalizeSyncResult(op, in_isr, ec);
}

Release()

void LibXR::ESP32SPI::Release ( )

private

Definition at line 173 of file esp_spi.cpp.

{ busy_.Clear(); }

ResolveClockSource()

ErrorCode LibXR::ESP32SPI::ResolveClockSource ( uint32_t & source_hz )

private

Definition at line 282 of file esp_spi.cpp.

{
  source_hz = 0;
  const esp_err_t err =
      esp_clk_tree_src_get_freq_hz(static_cast<soc_module_clk_t>(SPI_CLK_SRC_DEFAULT),
                                   ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED, &source_hz);
  if ((err != ESP_OK) || (source_hz == 0))
  {
    return ErrorCode::INIT_ERR;
  }
  return ErrorCode::OK;
}

ReturnAsyncStartResult()

ErrorCode LibXR::ESP32SPI::ReturnAsyncStartResult ( ErrorCode ec, bool started )

private

Definition at line 575 of file esp_spi.cpp.

{
  if (!started)
  {
    Release();
  }
  return ec;
}

SetConfig()

ErrorCode LibXR::ESP32SPI::SetConfig ( SPI::Configuration config )

overridevirtual

设置 SPI 配置参数。Sets SPI configuration parameters.

Parameters

config

需要应用的 SPI 配置。The SPI configuration to apply.

Returns

操作结果的错误码。Error code indicating the result of the operation.

Implements LibXR::SPI.

Definition at line 456 of file esp_spi.cpp.

{
  if (!initialized_ || (hw_ == nullptr))
  {
    return ErrorCode::STATE_ERR;
  }
  if (busy_.IsSet())
  {
    return ErrorCode::BUSY;
  }
 
  if (config.prescaler == Prescaler::UNKNOWN)
  {
    return ErrorCode::ARG_ERR;
  }
  if (config.double_buffer &&
      ((dbuf_rx_block_size_ == 0U) || (dbuf_tx_block_size_ == 0U)))
  {
    return ErrorCode::ARG_ERR;
  }
 
  const uint32_t div = PrescalerToDiv(config.prescaler);
  if ((div == 0) || (source_clock_hz_ == 0))
  {
    return ErrorCode::ARG_ERR;
  }
 
  const uint32_t target_hz = source_clock_hz_ / div;
  if (target_hz == 0)
  {
    return ErrorCode::ARG_ERR;
  }
 
  const uint8_t mode = ResolveSpiMode(config.clock_polarity, config.clock_phase);
  spi_ll_master_set_mode(hw_, mode);
 
  const int applied_hz = spi_ll_master_set_clock(hw_, static_cast<int>(source_clock_hz_),
                                                 static_cast<int>(target_hz), 128);
  if (applied_hz <= 0)
  {
    return ErrorCode::INIT_ERR;
  }
 
  spi_ll_apply_config(hw_);
  GetConfig() = config;
  dbuf_enabled_ = config.double_buffer;
  dbuf_active_block_ = 0U;
 
  return ErrorCode::OK;
}

SpiIsrEntry()

void IRAM_ATTR LibXR::ESP32SPI::SpiIsrEntry ( void * arg )

staticprivate

Definition at line 350 of file esp_spi.cpp.

{
  auto* spi = static_cast<ESP32SPI*>(arg);
  if (spi != nullptr)
  {
    spi->HandleInterrupt();
  }
}

StartAsyncTransfer()

ErrorCode LibXR::ESP32SPI::StartAsyncTransfer ( const uint8_t * tx, uint8_t * rx, size_t size, bool enable_rx, RawData read_back, bool mem_read, OperationRW & op, bool & started )

private

Definition at line 604 of file esp_spi.cpp.

{
  started = false;
 
  if (!CanUseDma(size))
  {
    return ErrorCode::NOT_SUPPORT;
  }
  if ((tx == nullptr) || (size == 0U))
  {
    return ErrorCode::ARG_ERR;
  }
 
  spi_dma_ctx_t* ctx = ToDmaCtx(dma_ctx_);
  if (ctx == nullptr)
  {
    return ErrorCode::INIT_ERR;
  }
 
  const bool rx_enabled = enable_rx && (rx != nullptr);
  ConfigureTransferRegisters(size);
 
#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE || SOC_PSRAM_DMA_CAPABLE
  if (!CacheSyncDmaBuffer(tx, size, true))
  {
    return ErrorCode::FAILED;
  }
#endif
 
  if (enable_rx && (rx != nullptr))
  {
    spicommon_dma_desc_setup_link(ctx->dmadesc_rx, rx, static_cast<int>(size), true);
    if (DmaReset(ctx->rx_dma_chan) != ESP_OK)
    {
      return ErrorCode::INIT_ERR;
    }
    spi_hal_hw_prepare_rx(hw_);
    if (DmaStart(ctx->rx_dma_chan, ctx->dmadesc_rx) != ESP_OK)
    {
      return ErrorCode::INIT_ERR;
    }
  }
#if CONFIG_IDF_TARGET_ESP32
  else
  {
    // Keep ESP32 full-duplex TX-only DMA behavior aligned with IDF workaround.
    spi_ll_dma_rx_enable(hw_, true);
    (void)DmaStart(ctx->rx_dma_chan, nullptr);
  }
#endif
 
  spicommon_dma_desc_setup_link(ctx->dmadesc_tx, tx, static_cast<int>(size), false);
  if (DmaReset(ctx->tx_dma_chan) != ESP_OK)
  {
    return ErrorCode::INIT_ERR;
  }
  spi_hal_hw_prepare_tx(hw_);
  if (DmaStart(ctx->tx_dma_chan, ctx->dmadesc_tx) != ESP_OK)
  {
    return ErrorCode::INIT_ERR;
  }
 
#if CONFIG_IDF_TARGET_ESP32
  spicommon_dmaworkaround_transfer_active(ctx->tx_dma_chan.chan_id);
#endif
 
  rw_op_ = op;
  read_back_ = read_back;
  mem_read_ = mem_read;
  async_dma_size_ = size;
  async_dma_rx_enabled_ = rx_enabled;
  if (op.type == OperationRW::OperationType::BLOCK)
  {
    block_wait_.Start(*op.data.sem_info.sem);
  }
  started = true;
 
  // On ESP32 classic, enable data lines only after DMA descriptors/channels are ready.
  spi_ll_enable_mosi(hw_, 1);
  spi_ll_enable_miso(hw_, rx_enabled ? 1 : 0);
  spi_ll_clear_int_stat(hw_);
  spi_ll_enable_int(hw_);
  async_running_ = true;
  spi_ll_apply_config(hw_);
  spi_ll_user_start(hw_);
 
  op.MarkAsRunning();
  if (op.type == OperationRW::OperationType::BLOCK)
  {
    return block_wait_.Wait(op.data.sem_info.timeout);
  }
  return ErrorCode::OK;
}

SwitchBufferLocal()

void LibXR::ESP32SPI::SwitchBufferLocal ( )

private

Definition at line 534 of file esp_spi.cpp.

{
  if (UseLocalDoubleBuffer())
  {
    dbuf_active_block_ ^= 1U;
  }
}

Transfer()

ErrorCode LibXR::ESP32SPI::Transfer ( size_t size, OperationRW & op, bool in_isr = false )

overridevirtual

进行一次SPI传输（使用当前缓冲区数据，零拷贝，支持双缓冲）。 Performs a SPI transfer (zero-copy, supports double buffering).

Parameters

size	需要传输的数据大小。The size of the data to be transferred.
op	读写操作类型。Type of read/write operation.
in_isr	是否在中断中进行操作。Whether the operation is performed in an ISR.

Returns

操作结果的错误码。Error code indicating the result of the operation.

Implements LibXR::SPI.

Definition at line 897 of file esp_spi.cpp.

{
  if (size == 0U)
  {
    return CompleteZeroSize(op, in_isr);
  }
 
  const ErrorCode lock_ec = EnsureReadyAndAcquire();
  if (lock_ec != ErrorCode::OK)
  {
    return lock_ec;
  }
 
  RawData rx = GetRxBuffer();
  RawData tx = GetTxBuffer();
  ASSERT(rx.size_ >= size);
  ASSERT(tx.size_ >= size);
 
  if (CanUseDma(size))
  {
    bool started = false;
    const ErrorCode ec = StartAsyncTransfer(static_cast<const uint8_t*>(tx.addr_),
                                            static_cast<uint8_t*>(rx.addr_), size, true,
                                            {nullptr, 0}, false, op, started);
    return ReturnAsyncStartResult(ec, started);
  }
 
  const ErrorCode ec = ExecuteTransfer(static_cast<const uint8_t*>(tx.addr_),
                                       static_cast<uint8_t*>(rx.addr_), size, true);
  if (ec == ErrorCode::OK)
  {
    SwitchBufferLocal();
  }
 
  Release();
  return FinalizeSyncResult(op, in_isr, ec);
}

UseLocalDoubleBuffer()

bool LibXR::ESP32SPI::UseLocalDoubleBuffer ( ) const

private

Definition at line 507 of file esp_spi.cpp.

{
  return dbuf_enabled_ && (dbuf_rx_block_size_ > 0U) && (dbuf_tx_block_size_ > 0U);
}

Field Documentation

async_dma_rx_enabled_

bool LibXR::ESP32SPI::async_dma_rx_enabled_ = false

private

Definition at line 130 of file esp_spi.hpp.

async_dma_size_

size_t LibXR::ESP32SPI::async_dma_size_ = 0

private

Definition at line 129 of file esp_spi.hpp.

async_running_

bool LibXR::ESP32SPI::async_running_ = false

private

Definition at line 128 of file esp_spi.hpp.

block_wait_

AsyncBlockWait LibXR::ESP32SPI::block_wait_ {}

private

Definition at line 121 of file esp_spi.hpp.

{};

busy_

Flag::Atomic LibXR::ESP32SPI::busy_ {}

private

Definition at line 112 of file esp_spi.hpp.

{};

dbuf_active_block_

uint8_t LibXR::ESP32SPI::dbuf_active_block_ = 0

private

Definition at line 120 of file esp_spi.hpp.

dbuf_enabled_

bool LibXR::ESP32SPI::dbuf_enabled_ = false

private

Definition at line 122 of file esp_spi.hpp.

dbuf_rx_block_size_

size_t LibXR::ESP32SPI::dbuf_rx_block_size_ = 0

private

Definition at line 118 of file esp_spi.hpp.

dbuf_tx_block_size_

size_t LibXR::ESP32SPI::dbuf_tx_block_size_ = 0

private

Definition at line 119 of file esp_spi.hpp.

dma_ctx_

void* LibXR::ESP32SPI::dma_ctx_ = nullptr

private

Definition at line 126 of file esp_spi.hpp.

dma_enable_min_size_

uint32_t LibXR::ESP32SPI::dma_enable_min_size_ = 3U

private

Definition at line 114 of file esp_spi.hpp.

dma_enabled_

bool LibXR::ESP32SPI::dma_enabled_ = false

private

Definition at line 125 of file esp_spi.hpp.

dma_max_transfer_bytes_

size_t LibXR::ESP32SPI::dma_max_transfer_bytes_ = 0

private

Definition at line 127 of file esp_spi.hpp.

dma_requested_

bool LibXR::ESP32SPI::dma_requested_ = true

private

Definition at line 115 of file esp_spi.hpp.

dma_rx_raw_

RawData LibXR::ESP32SPI::dma_rx_raw_ = {nullptr, 0}

private

Definition at line 116 of file esp_spi.hpp.

{nullptr, 0};

dma_tx_raw_

RawData LibXR::ESP32SPI::dma_tx_raw_ = {nullptr, 0}

private

Definition at line 117 of file esp_spi.hpp.

{nullptr, 0};

host_

spi_host_device_t LibXR::ESP32SPI::host_

private

Definition at line 106 of file esp_spi.hpp.

hw_

spi_dev_t* LibXR::ESP32SPI::hw_ = nullptr

private

Definition at line 107 of file esp_spi.hpp.

initialized_

bool LibXR::ESP32SPI::initialized_ = false

private

Definition at line 113 of file esp_spi.hpp.

intr_handle_

intr_handle_t LibXR::ESP32SPI::intr_handle_ = nullptr

private

Definition at line 123 of file esp_spi.hpp.

intr_installed_

bool LibXR::ESP32SPI::intr_installed_ = false

private

Definition at line 124 of file esp_spi.hpp.

MAX_DMA_TRANSFER_BYTES

size_t LibXR::ESP32SPI::MAX_DMA_TRANSFER_BYTES = SPI_LL_DMA_MAX_BIT_LEN / 8U

staticconstexprprivate

Definition at line 57 of file esp_spi.hpp.

MAX_POLLING_TRANSFER_BYTES

size_t LibXR::ESP32SPI::MAX_POLLING_TRANSFER_BYTES = SOC_SPI_MAXIMUM_BUFFER_SIZE

staticconstexprprivate

Definition at line 56 of file esp_spi.hpp.

mem_read_

bool LibXR::ESP32SPI::mem_read_ = false

private

Definition at line 131 of file esp_spi.hpp.

miso_pin_

int LibXR::ESP32SPI::miso_pin_

private

Definition at line 109 of file esp_spi.hpp.

mosi_pin_

int LibXR::ESP32SPI::mosi_pin_

private

Definition at line 110 of file esp_spi.hpp.

read_back_

RawData LibXR::ESP32SPI::read_back_ = {nullptr, 0}

private

Definition at line 132 of file esp_spi.hpp.

{nullptr, 0};

rw_op_

OperationRW LibXR::ESP32SPI::rw_op_

private

Definition at line 133 of file esp_spi.hpp.

sclk_pin_

int LibXR::ESP32SPI::sclk_pin_

private

Definition at line 108 of file esp_spi.hpp.

source_clock_hz_

uint32_t LibXR::ESP32SPI::source_clock_hz_ = 0

private

Definition at line 111 of file esp_spi.hpp.

---

The documentation for this class was generated from the following files:

• driver/esp/esp_spi.hpp
• driver/esp/esp_spi.cpp