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.

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)
  {
    REQUIRE(false);
    return;
  }
 
  if (ConfigurePins() != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
 
  if (InstallInterrupt() != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
 
  if (dma_requested_)
  {
    const ErrorCode dma_ans = InitDmaBackend();
    REQUIRE(dma_ans == ErrorCode::OK);
    if (dma_ans != ErrorCode::OK)
    {
      return;
    }
  }
 
  if (SetConfig(config) != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
}

Member Function Documentation

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.

{ 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.

{ return Prescaler::DIV_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_;
}

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);
}

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;
}

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);
}

---

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

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