串行外设接口（SPI）抽象类。 Abstract class for Serial Peripheral Interface (SPI). More...

#include <spi.hpp>

Inheritance diagram for LibXR::SPI:

Classes
struct	Configuration
	存储 SPI 配置参数的结构体。 Structure for storing SPI configuration parameters. More...

struct	ReadWriteInfo
	存储 SPI 读写操作信息的结构体。 Structure for storing SPI read/write operation information. More...

Public Types
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.

Public Member Functions
	SPI (RawData rx_buffer, RawData tx_buffer)
	构造函数 / Constructor.

virtual ErrorCode	ReadAndWrite (RawData read_data, ConstRawData write_data, OperationRW &op, bool in_isr=false)=0
	进行 SPI 读写操作 / Performs SPI read and write operations.

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.

virtual ErrorCode	SetConfig (Configuration config)=0
	设置 SPI 配置参数 / Sets SPI configuration parameters.

virtual uint32_t	GetMaxBusSpeed () const =0
	获取 SPI 设备的最大时钟速度 / Gets the maximum clock speed of the SPI device.

virtual Prescaler	GetMaxPrescaler () const =0
	获取 SPI 设备的最大分频系数 / Gets the maximum prescaler of the SPI device.

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.

virtual ErrorCode	Transfer (size_t size, OperationRW &op, bool in_isr=false)=0
	进行一次SPI传输（使用当前缓冲区数据，零拷贝，支持双缓冲）。 Performs a SPI transfer (zero-copy, supports double buffering).

virtual ErrorCode	MemWrite (uint16_t reg, ConstRawData write_data, OperationRW &op, bool in_isr=false)=0
	向 SPI 设备的寄存器写入数据。 Writes data to a specific register of the SPI device.

virtual ErrorCode	MemRead (uint16_t reg, RawData read_data, OperationRW &op, bool in_isr=false)=0
	从 SPI 设备的寄存器读取数据。 Reads data from a specific register of the SPI device.

Configuration &	GetConfig ()
	获取 SPI 配置参数 / Gets the SPI configuration parameters.

bool	IsDoubleBuffer () const
	检查是否使用双缓冲区 / Checks if double buffering is enabled.

Static Public Member Functions
static constexpr uint32_t	PrescalerToDiv (Prescaler prescaler)
	将分频系数转换为除数 / Converts a prescaler to a divisor.

Detailed Description

串行外设接口（SPI）抽象类。 Abstract class for Serial Peripheral Interface (SPI).

Definition at line 14 of file spi.hpp.

Member Typedef Documentation

◆ OperationRW

using LibXR::SPI::OperationRW = WriteOperation

定义读写操作类型的别名 / Defines an alias for the read/write operation type.

Definition at line 63 of file spi.hpp.

Member Enumeration Documentation

◆ ClockPhase

enum class LibXR::SPI::ClockPhase : uint8_t

strong

定义 SPI 时钟相位 / Defines the SPI clock phase.

Enumerator
EDGE_1	在第一个时钟边沿采样数据 / Data sampled on the first clock edge.
EDGE_2	在第二个时钟边沿采样数据 / Data sampled on the second clock edge.

Definition at line 31 of file spi.hpp.

  {
    EDGE_1 = 0,  
    EDGE_2 = 1   
  };

◆ ClockPolarity

enum class LibXR::SPI::ClockPolarity : uint8_t

strong

定义 SPI 时钟极性 / Defines the SPI clock polarity.

Enumerator
LOW	时钟空闲时为低电平 / Clock idle low.
HIGH	时钟空闲时为高电平 / Clock idle high.

Definition at line 21 of file spi.hpp.

  {
    LOW = 0,  
    HIGH = 1  
  };

◆ Prescaler

enum class LibXR::SPI::Prescaler : uint8_t

strong

Enumerator
DIV_1	分频系数为 1 / Division factor is 1.
DIV_2	分频系数为 2 / Division factor is 2.
DIV_4	分频系数为 4 / Division factor is 4.
DIV_8	分频系数为 8 / Division factor is 8.
DIV_16	分频系数为 16 / Division factor is 16.
DIV_32	分频系数为 32 / Division factor is 32.
DIV_64	分频系数为 64 / Division factor is 64.
DIV_128	分频系数为 128 / Division factor is 128.
DIV_256	分频系数为 256 / Division factor is 256.
DIV_512	分频系数为 512 / Division factor is 512.
DIV_1024	分频系数为 1024 / Division factor is 1024.
DIV_2048	分频系数为 2048 / Division factor is 2048.
DIV_4096	分频系数为 4096 / Division factor is 4096.
DIV_8192	分频系数为 8192 / Division factor is 8192.
DIV_16384	分频系数为 16384 / Division factor is 16384.
DIV_32768	分频系数为 32768 / Division factor is 32768.
DIV_65536	分频系数为 65536 / Division factor is 65536.
UNKNOWN	未知分频系数 / Unknown prescaler.

Definition at line 37 of file spi.hpp.

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

Constructor & Destructor Documentation

◆ SPI()

LibXR::SPI::SPI	(	RawData	rx_buffer,
		RawData	tx_buffer )

inline

构造函数 / Constructor.

Parameters

rx_buffer	存储接收数据的缓冲区 / Buffer to store received data.
tx_buffer	存储发送数据的缓冲区 / Buffer to store data to be sent.

Definition at line 111 of file spi.hpp.

      : rx_buffer_(rx_buffer),
        tx_buffer_(tx_buffer),
        double_buffer_rx_(rx_buffer),
        double_buffer_tx_(tx_buffer)
  {
  }

Member Function Documentation

◆ CalcPrescaler()

Prescaler LibXR::SPI::CalcPrescaler	(	uint32_t	target_max_bus_speed,
		uint32_t	target_min_bus_speed,
		bool	increase )

inline

计算 SPI 分频系数 / Calculates the SPI prescaler.

Parameters

target_max_bus_speed	目标最大总线速度（单位：Hz）。 Target maximum bus speed (in Hz).
target_min_bus_speed	目标最小总线速度（单位：Hz）。 Target minimum bus speed (in Hz).
increase	是否从最小分频系数开始 / Whether to start from the minimum prescaler.

Returns: 计算得到的分频系数 / The calculated prescaler.

Definition at line 199 of file spi.hpp.

  {
    const uint32_t SRC = GetMaxBusSpeed();
    if (SRC == 0u)
    {
      return Prescaler::UNKNOWN;
    }
 
    if (target_max_bus_speed && target_min_bus_speed &&
        target_min_bus_speed > target_max_bus_speed)
    {
      uint32_t t = target_min_bus_speed;
      target_min_bus_speed = target_max_bus_speed;
      target_max_bus_speed = t;
    }
 
    const uint8_t MAX_IDX = static_cast<uint8_t>(GetMaxPrescaler());
 
    ASSERT(MAX_IDX != static_cast<uint8_t>(Prescaler::UNKNOWN));
 
    auto fits = [&](Prescaler p) -> bool
    {
      const uint32_t DIV = PrescalerToDiv(p);
      if (DIV == 0u)
      {
        return false;
      }
      const uint32_t F = SRC / DIV;
      if (target_max_bus_speed && F > target_max_bus_speed)
      {
        return false;
      }
      if (target_min_bus_speed && F < target_min_bus_speed)
      {
        return false;
      }
      return true;
    };
 
    if (increase)
    {
      for (uint8_t i = 0; i <= MAX_IDX; ++i)
      {
        Prescaler p = static_cast<Prescaler>(i);
        if (fits(p))
        {
          return p;
        }
      }
    }
    else
    {
      for (int i = static_cast<int>(MAX_IDX); i >= 0; --i)
      {
        Prescaler p = static_cast<Prescaler>(i);
        if (fits(p))
        {
          return p;
        }
      }
    }
 
    const uint32_t F_FASTEST = SRC / PrescalerToDiv(Prescaler::DIV_1);
    const Prescaler P_SLOWEST = static_cast<Prescaler>(MAX_IDX);
    const uint32_t F_SLOWEST = SRC / PrescalerToDiv(P_SLOWEST);
 
    if (target_min_bus_speed && F_FASTEST < target_min_bus_speed)
    {
      return Prescaler::DIV_1;
    }
    if (target_max_bus_speed && F_SLOWEST > target_max_bus_speed)
    {
      return P_SLOWEST;
    }
 
    if (increase)
    {
      for (uint8_t i = 0; i <= MAX_IDX; ++i)
      {
        Prescaler p = static_cast<Prescaler>(i);
        const uint32_t F = SRC / PrescalerToDiv(p);
        if (!target_max_bus_speed || F <= target_max_bus_speed)
        {
          return p;
        }
      }
      return P_SLOWEST;
    }
    else
    {
      for (int i = static_cast<int>(MAX_IDX); i >= 0; --i)
      {
        Prescaler p = static_cast<Prescaler>(i);
        const uint32_t F = SRC / PrescalerToDiv(p);
        if (!target_min_bus_speed || F >= target_min_bus_speed)
        {
          return p;
        }
      }
      return Prescaler::DIV_1;
    }
  }

◆ GetActiveLength()

size_t LibXR::SPI::GetActiveLength ( ) const

inline

获取缓冲区的有效数据长度 / Gets the length of valid data in the buffer.

Definition at line 355 of file spi.hpp.

355{ return double_buffer_tx_.GetActiveLength(); }

LibXR::DoubleBuffer::GetActiveLength

size_t GetActiveLength() const

获取当前活动缓冲区中准备好的数据长度 Gets the size of valid data in active buffer

Definition double_buffer.hpp:149

◆ GetBusSpeed()

uint32_t LibXR::SPI::GetBusSpeed ( ) const

inline

获取 SPI 设备的当前总线速度 / Gets the current bus speed of the SPI device.

Returns: SPI 设备的当前总线速度（单位：Hz）。 The current bus speed of the SPI device (in Hz).

Definition at line 179 of file spi.hpp.

  {
    const uint32_t DIV = PrescalerToDiv(config_.prescaler);
    const uint32_t SRC = GetMaxBusSpeed();
    if (DIV == 0u || SRC == 0u)
    {
      return 0u;
    }
    return SRC / DIV;
  }

◆ GetConfig()

Configuration & LibXR::SPI::GetConfig ( )

inline

获取 SPI 配置参数 / Gets the SPI configuration parameters.

Returns: SPI 配置参数 / The SPI configuration parameters.

Definition at line 397 of file spi.hpp.

397{ return config_; }

◆ GetMaxBusSpeed()

virtual uint32_t LibXR::SPI::GetMaxBusSpeed ( ) const

pure virtual

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

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

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ GetMaxPrescaler()

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

pure virtual

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

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

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ GetRxBuffer()

RawData LibXR::SPI::GetRxBuffer ( )

inline

获取接收数据的缓冲区 / Gets the buffer for storing received data.

Returns: 接收数据的缓冲区 / The buffer for storing received data.

Definition at line 307 of file spi.hpp.

  {
    if (IsDoubleBuffer())
    {
      return {double_buffer_rx_.ActiveBuffer(), double_buffer_rx_.Size()};
    }
    else
    {
      return rx_buffer_;
    }
  }

◆ GetTxBuffer()

RawData LibXR::SPI::GetTxBuffer ( )

inline

获取发送数据的缓冲区 / Gets the buffer for storing data to be sent.

Returns: 发送数据的缓冲区 / The buffer for storing data to be sent.

Definition at line 323 of file spi.hpp.

  {
    if (IsDoubleBuffer())
    {
      return {double_buffer_tx_.ActiveBuffer(), double_buffer_tx_.Size()};
    }
    else
    {
      return tx_buffer_;
    }
  }

◆ IsDoubleBuffer()

bool LibXR::SPI::IsDoubleBuffer ( ) const

inline

检查是否使用双缓冲区 / Checks if double buffering is enabled.

Returns: true; false

Definition at line 405 of file spi.hpp.

405{ return config_.double_buffer; }

LibXR::SPI::Configuration::double_buffer

bool double_buffer

是否使用双缓冲区 / Whether to use double buffer.

Definition spi.hpp:91

◆ MemRead()

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

pure virtual

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

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ MemWrite()

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

pure virtual

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

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ PrescalerToDiv()

static constexpr uint32_t LibXR::SPI::PrescalerToDiv ( Prescaler prescaler )

inlinestaticconstexpr

将分频系数转换为除数 / Converts a prescaler to a divisor.

Parameters

prescaler 分频系数 / Prescaler.

Returns: 除数 / Divisor.

Definition at line 70 of file spi.hpp.

  {
    if (prescaler == Prescaler::UNKNOWN)
    {
      return 0u;
    }
    const uint8_t ORD = static_cast<uint8_t>(prescaler);
    return (ORD <= 30) ? (1u << ORD) : 0u;
  }

◆ Read()

virtual ErrorCode LibXR::SPI::Read	(	RawData	read_data,
		OperationRW &	op,
		bool	in_isr = false )

inlinevirtual

进行 SPI 读取操作 / Performs SPI read operation.

Parameters

read_data	存储读取数据的缓冲区 / Buffer to store the read data.
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.

Definition at line 137 of file spi.hpp.

  {
    return ReadAndWrite(read_data, ConstRawData(nullptr, 0), op, in_isr);
  }

◆ ReadAndWrite()

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

pure virtual

进行 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.

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ SetActiveLength()

void LibXR::SPI::SetActiveLength ( size_t len )

inline

设置缓冲区的有效数据长度 / Sets the length of valid data in the buffer.

Definition at line 350 of file spi.hpp.

350{ double_buffer_tx_.SetActiveLength(len); }

LibXR::DoubleBuffer::SetActiveLength

void SetActiveLength(size_t length)

设置当前活动缓冲区的数据长度 Sets the size of the active buffer

Definition double_buffer.hpp:165

◆ SetConfig()

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

pure virtual

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

Parameters

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

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

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ SwitchBuffer()

void LibXR::SPI::SwitchBuffer ( )

inline

切换缓冲区 / Switches the buffer.

Definition at line 338 of file spi.hpp.

  {
    if (IsDoubleBuffer())
    {
      double_buffer_rx_.Switch();
      double_buffer_tx_.Switch();
    }
  }

◆ Transfer()

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

pure virtual

进行一次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.

Implemented in LibXR::CH32SPI, LibXR::ESP32SPI, LibXR::MSPM0SPI, and LibXR::STM32SPI.

◆ Write()

virtual ErrorCode LibXR::SPI::Write	(	ConstRawData	write_data,
		OperationRW &	op,
		bool	in_isr = false )

inlinevirtual

进行 SPI 写入操作 / Performs SPI write operation.

Parameters

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.

Definition at line 149 of file spi.hpp.

  {
    return ReadAndWrite(RawData(nullptr, 0), write_data, op, in_isr);
  }

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

src/driver/spi.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ OperationRW

Member Enumeration Documentation

◆ ClockPhase

◆ ClockPolarity

◆ Prescaler

Constructor & Destructor Documentation

◆ SPI()

Member Function Documentation

◆ CalcPrescaler()

◆ GetActiveLength()

◆ GetBusSpeed()

◆ GetConfig()

◆ GetMaxBusSpeed()

◆ GetMaxPrescaler()

◆ GetRxBuffer()

◆ GetTxBuffer()

◆ IsDoubleBuffer()

◆ MemRead()

◆ MemWrite()

◆ PrescalerToDiv()

◆ Read()

◆ ReadAndWrite()

◆ SetActiveLength()

◆ SetConfig()

◆ SwitchBuffer()

◆ Transfer()

◆ Write()