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 18 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 108 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 166 of file esp_spi.cpp.

166{ return !busy_.TestAndSet(); }

LibXR::Flag::Atomic::TestAndSet

bool TestAndSet() noexcept

测试并置位：置位并返回旧状态 / Test-and-set: set and return previous state

Definition flag.hpp:66

◆ CanUseDma()

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

private

Definition at line 537 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 565 of file esp_spi.cpp.

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

◆ ConfigurePins()

ErrorCode LibXR::ESP32SPI::ConfigurePins ( )

private

Definition at line 231 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 579 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 543 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 696 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 733 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 556 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 375 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 931 of file esp_spi.cpp.

931{ 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 933 of file esp_spi.cpp.

933{ return Prescaler::DIV_65536; }

LibXR::SPI::Prescaler::DIV_65536

@ DIV_65536

分频系数为 65536。Division factor is 65536.

◆ GetRxBuffer()

RawData LibXR::ESP32SPI::GetRxBuffer ( )

Definition at line 507 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 518 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 354 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 309 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 170 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 290 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 808 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 853 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 755 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 168 of file esp_spi.cpp.

168{ busy_.Clear(); }

LibXR::Flag::Atomic::Clear

void Clear() noexcept

清除标志 / Clear the flag

Definition flag.hpp:47

◆ ResolveClockSource()

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

private

Definition at line 277 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 570 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 451 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 345 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 599 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 529 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 893 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 502 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 125 of file esp_spi.hpp.

◆ async_dma_size_

size_t LibXR::ESP32SPI::async_dma_size_ = 0

private

Definition at line 124 of file esp_spi.hpp.

◆ async_running_

bool LibXR::ESP32SPI::async_running_ = false

private

Definition at line 123 of file esp_spi.hpp.

◆ block_wait_

AsyncBlockWait LibXR::ESP32SPI::block_wait_ {}

private

Definition at line 116 of file esp_spi.hpp.

116{};

◆ busy_

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

private

Definition at line 107 of file esp_spi.hpp.

107{};

◆ dbuf_active_block_

uint8_t LibXR::ESP32SPI::dbuf_active_block_ = 0

private

Definition at line 115 of file esp_spi.hpp.

◆ dbuf_enabled_

bool LibXR::ESP32SPI::dbuf_enabled_ = false

private

Definition at line 117 of file esp_spi.hpp.

◆ dbuf_rx_block_size_

size_t LibXR::ESP32SPI::dbuf_rx_block_size_ = 0

private

Definition at line 113 of file esp_spi.hpp.

◆ dbuf_tx_block_size_

size_t LibXR::ESP32SPI::dbuf_tx_block_size_ = 0

private

Definition at line 114 of file esp_spi.hpp.

◆ dma_ctx_

void* LibXR::ESP32SPI::dma_ctx_ = nullptr

private

Definition at line 121 of file esp_spi.hpp.

◆ dma_enable_min_size_

uint32_t LibXR::ESP32SPI::dma_enable_min_size_ = 3U

private

Definition at line 109 of file esp_spi.hpp.

◆ dma_enabled_

bool LibXR::ESP32SPI::dma_enabled_ = false

private

Definition at line 120 of file esp_spi.hpp.

◆ dma_max_transfer_bytes_

size_t LibXR::ESP32SPI::dma_max_transfer_bytes_ = 0

private

Definition at line 122 of file esp_spi.hpp.

◆ dma_requested_

bool LibXR::ESP32SPI::dma_requested_ = true

private

Definition at line 110 of file esp_spi.hpp.

◆ dma_rx_raw_

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

private

Definition at line 111 of file esp_spi.hpp.

111{nullptr, 0};

◆ dma_tx_raw_

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

private

Definition at line 112 of file esp_spi.hpp.

112{nullptr, 0};

◆ host_

spi_host_device_t LibXR::ESP32SPI::host_

private

Definition at line 101 of file esp_spi.hpp.

◆ hw_

spi_dev_t* LibXR::ESP32SPI::hw_ = nullptr

private

Definition at line 102 of file esp_spi.hpp.

◆ initialized_

bool LibXR::ESP32SPI::initialized_ = false

private

Definition at line 108 of file esp_spi.hpp.

◆ intr_handle_

intr_handle_t LibXR::ESP32SPI::intr_handle_ = nullptr

private

Definition at line 118 of file esp_spi.hpp.

◆ intr_installed_

bool LibXR::ESP32SPI::intr_installed_ = false

private

Definition at line 119 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 55 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 54 of file esp_spi.hpp.

◆ mem_read_

bool LibXR::ESP32SPI::mem_read_ = false

private

Definition at line 126 of file esp_spi.hpp.

◆ miso_pin_

int LibXR::ESP32SPI::miso_pin_

private

Definition at line 104 of file esp_spi.hpp.

◆ mosi_pin_

int LibXR::ESP32SPI::mosi_pin_

private

Definition at line 105 of file esp_spi.hpp.

◆ read_back_

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

private

Definition at line 127 of file esp_spi.hpp.

127{nullptr, 0};

◆ rw_op_

OperationRW LibXR::ESP32SPI::rw_op_

private

Definition at line 128 of file esp_spi.hpp.

◆ sclk_pin_

int LibXR::ESP32SPI::sclk_pin_

private

Definition at line 103 of file esp_spi.hpp.

◆ source_clock_hz_

uint32_t LibXR::ESP32SPI::source_clock_hz_ = 0

private

Definition at line 106 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

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ESP32SPI()

Member Function Documentation

◆ Acquire()

◆ CanUseDma()

◆ CompleteZeroSize()

◆ ConfigurePins()

◆ ConfigureTransferRegisters()

◆ EnsureReadyAndAcquire()

◆ ExecuteChunk()

◆ ExecuteTransfer()

◆ FinalizeSyncResult()

◆ FinishAsync()

◆ GetMaxBusSpeed()

◆ GetMaxPrescaler()

◆ GetRxBuffer()

◆ GetTxBuffer()

◆ HandleInterrupt()

◆ InitDmaBackend()

◆ InitializeHardware()

◆ InstallInterrupt()

◆ MemRead()

◆ MemWrite()

◆ ReadAndWrite()

◆ Release()

◆ ResolveClockSource()

◆ ReturnAsyncStartResult()

◆ SetConfig()

◆ SpiIsrEntry()

◆ StartAsyncTransfer()

◆ SwitchBufferLocal()

◆ Transfer()

◆ UseLocalDoubleBuffer()

Field Documentation

◆ async_dma_rx_enabled_

◆ async_dma_size_

◆ async_running_

◆ block_wait_

◆ busy_

◆ dbuf_active_block_

◆ dbuf_enabled_

◆ dbuf_rx_block_size_

◆ dbuf_tx_block_size_

◆ dma_ctx_

◆ dma_enable_min_size_

◆ dma_enabled_

◆ dma_max_transfer_bytes_

◆ dma_requested_

◆ dma_rx_raw_

◆ dma_tx_raw_

◆ host_

◆ hw_

◆ initialized_

◆ intr_handle_

◆ intr_installed_

◆ MAX_DMA_TRANSFER_BYTES

◆ MAX_POLLING_TRANSFER_BYTES

◆ mem_read_

◆ miso_pin_

◆ mosi_pin_

◆ read_back_

◆ rw_op_

◆ sclk_pin_

◆ source_clock_hz_