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

#include <spi.hpp>

Inheritance diagram for LibXR::SPI:

Collaboration diagram for LibXR::SPI:

Data Structures
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)=0
	进行 SPI 读写操作。Performs SPI read and write operations.

virtual ErrorCode	Read (RawData read_data, OperationRW &op)
	进行 SPI 读取操作。Performs SPI read operation.

virtual ErrorCode	Write (ConstRawData write_data, OperationRW &op)
	进行 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)=0
	进行一次SPI传输（使用当前缓冲区数据，零拷贝，支持双缓冲）。 Performs a SPI transfer (zero-copy, supports double buffering).

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

virtual ErrorCode	MemRead (uint16_t reg, RawData read_data, OperationRW &op)=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.

Private Attributes
Configuration	config_

RawData	rx_buffer_

RawData	tx_buffer_

DoubleBuffer	double_buffer_rx_

DoubleBuffer	double_buffer_tx_

Detailed Description

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

Definition at line 13 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 30 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 20 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 36 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 110 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 195 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 351 of file spi.hpp.

351{ 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:116

◆ 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 175 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 388 of file spi.hpp.

388{ 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, 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, 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 303 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 319 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 396 of file spi.hpp.

396{ return config_.double_buffer; }

LibXR::SPI::Configuration::double_buffer

bool double_buffer

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

Definition spi.hpp:90

◆ MemRead()

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

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

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

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

◆ MemWrite()

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

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

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

Implemented in LibXR::CH32SPI, 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 )

inlinevirtual

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

Parameters

read_data	存储读取数据的缓冲区。Buffer to store the read data.
op	读写操作类型。Type of read/write operation.

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

Definition at line 134 of file spi.hpp.

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

◆ ReadAndWrite()

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

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.

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

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

◆ SetActiveLength()

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

inline

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

Definition at line 346 of file spi.hpp.

346{ double_buffer_tx_.SetActiveLength(len); }

LibXR::DoubleBuffer::SetActiveLength

void SetActiveLength(size_t length)

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

Definition double_buffer.hpp:132

◆ 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, and LibXR::STM32SPI.

◆ SwitchBuffer()

void LibXR::SPI::SwitchBuffer ( )

inline

切换缓冲区。Switches the buffer.

Definition at line 334 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 )

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.

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

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

◆ Write()

virtual ErrorCode LibXR::SPI::Write	(	ConstRawData	write_data,
		OperationRW &	op )

inlinevirtual

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

Parameters

write_data	需要写入的数据缓冲区。Buffer containing the data to be written.
op	读写操作类型。Type of read/write operation.

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

Definition at line 145 of file spi.hpp.

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

Field Documentation

◆ config_

Configuration LibXR::SPI::config_

private

Definition at line 399 of file spi.hpp.

◆ double_buffer_rx_

DoubleBuffer LibXR::SPI::double_buffer_rx_

private

Definition at line 401 of file spi.hpp.

◆ double_buffer_tx_

DoubleBuffer LibXR::SPI::double_buffer_tx_

private

Definition at line 401 of file spi.hpp.

◆ rx_buffer_

RawData LibXR::SPI::rx_buffer_

private

Definition at line 400 of file spi.hpp.

◆ tx_buffer_

RawData LibXR::SPI::tx_buffer_

private

Definition at line 400 of file spi.hpp.

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

src/driver/spi.hpp

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

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()

Field Documentation

◆ config_

◆ double_buffer_rx_

◆ double_buffer_tx_

◆ rx_buffer_

◆ tx_buffer_