STM32 I2C 驱动实现 / STM32 I2C driver implementation. More...

#include <stm32_i2c.hpp>

Inheritance diagram for LibXR::STM32I2C:

Collaboration diagram for LibXR::STM32I2C:

Classes
struct	HasClockSpeed

struct	HasClockSpeed< T, std::void_t< decltype(std::declval< T >() ->Init.ClockSpeed)> >

struct	HasTiming

struct	HasTiming< T, std::void_t< decltype(std::declval< T >() ->Init.Timing)> >

Public Member Functions
	STM32I2C (I2C_HandleTypeDef *hi2c, RawData dma_buff, uint32_t dma_enable_min_size=3)
	构造 I2C 对象 / Construct I2C object

ErrorCode	Read (uint16_t slave_addr, RawData read_data, ReadOperation &op, bool in_isr) override
	读取 I2C 设备的数据。 Reads data from an I2C device.

ErrorCode	Write (uint16_t slave_addr, ConstRawData write_data, WriteOperation &op, bool in_isr) override
	向 I2C 设备写入数据。 Writes data to an I2C device.

ErrorCode	MemRead (uint16_t slave_addr, uint16_t mem_addr, RawData read_data, ReadOperation &op, MemAddrLength mem_addr_size, bool in_isr) override
	从 I2C 设备指定寄存器读取数据。 Reads data from a specific register of an I2C device.

ErrorCode	MemWrite (uint16_t slave_addr, uint16_t mem_addr, ConstRawData write_data, WriteOperation &op, MemAddrLength mem_addr_size, bool in_isr) override
	向 I2C 设备指定寄存器写入数据。 Writes data to a specific register of an I2C device.

template<typename T >
std::enable_if<!HasClockSpeed< T >::value >::type	SetClockSpeed (T &, const Configuration &)

template<typename T >
std::enable_if< HasClockSpeed< T >::value >::type	SetClockSpeed (T &i2c_handle, const Configuration &config)

template<typename T >
std::enable_if< HasTiming< T >::value >::type	SetTiming (T &i2c_handle, uint32_t timing)

template<typename T >
std::enable_if<!HasTiming< T >::value >::type	SetTiming (T &, uint32_t)

ErrorCode	SetConfig (Configuration config) override
	配置 I2C 设备参数。 Configures the I2C device settings.

Public Member Functions inherited from LibXR::I2C
	I2C ()
	默认构造函数。 Default constructor.

Public Attributes
stm32_i2c_id_t	id_

I2C_HandleTypeDef *	i2c_handle_

uint32_t	dma_enable_min_size_

RawData	dma_buff_

ReadOperation	read_op_

WriteOperation	write_op_

RawData	read_buff_

bool	read_ = false

bool	recovering_ = false

AsyncBlockWait	block_wait_ {}

Static Public Attributes
static STM32I2C *	map [STM32_I2C_NUMBER] = {nullptr}

Additional Inherited Members
Public Types inherited from LibXR::I2C
enum class	MemAddrLength : uint8_t { BYTE_8 , BYTE_16 }

Detailed Description

STM32 I2C 驱动实现 / STM32 I2C driver implementation.

Definition at line 54 of file stm32_i2c.hpp.

Constructor & Destructor Documentation

◆ STM32I2C()

STM32I2C::STM32I2C	(	I2C_HandleTypeDef *	hi2c,
		RawData	dma_buff,
		uint32_t	dma_enable_min_size = 3 )

构造 I2C 对象 / Construct I2C object

Definition at line 639 of file stm32_i2c.cpp.

    : I2C(),
      id_(hi2c == nullptr ? STM32_I2C_ID_ERROR : STM32_I2C_GetID(hi2c->Instance)),
      i2c_handle_(hi2c),
      dma_enable_min_size_(dma_enable_min_size),
      dma_buff_(dma_buff)
{
  ASSERT(id_ != STM32_I2C_ID_ERROR);
  ASSERT(id_ < STM32_I2C_NUMBER);
  map[id_] = this;
}

Member Function Documentation

◆ MemRead()

ErrorCode STM32I2C::MemRead	(	uint16_t	slave_addr,
		uint16_t	mem_addr,
		RawData	read_data,
		ReadOperation &	op,
		MemAddrLength	mem_addr_size,
		bool	in_isr )

overridevirtual

从 I2C 设备指定寄存器读取数据。 Reads data from a specific register of an I2C device.

该函数从指定 I2C 从设备的寄存器地址读取数据，并存储到 read_data 中。 This function reads data from the specified register of the I2C slave and stores it in read_data.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
mem_addr	寄存器地址（通常为 8 位或 16 位）。 Register address (typically 8-bit or 16-bit).
read_data	用于存储读取数据的 `RawData` 对象。 `RawData` object to store read data.
op	异步或同步的读取操作对象。 Read operation object (sync or async).
mem_addr_size	寄存器地址长度。 Size of register address in bytes.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns: 返回 ErrorCode，表示是否读取成功。 Returns ErrorCode indicating success or failure.

Implements LibXR::I2C.

Definition at line 774 of file stm32_i2c.cpp.

{
  ASSERT(read_data.size_ <= dma_buff_.size_);
 
  if (i2c_handle_->State != HAL_I2C_STATE_READY)
  {
    return ErrorCode::BUSY;
  }
 
  read_ = true;
 
  const uint16_t dev_addr = EncodeHalDevAddress(i2c_handle_, slave_addr);
 
  if (read_data.size_ > dma_enable_min_size_)
  {
    read_op_ = op;
    read_buff_ = read_data;
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      // Arm the BLOCK waiter before HAL exposes completion to IRQ context.
      block_wait_.Start(*op.data.sem_info.sem);
    }
    op.MarkAsRunning();
    const HAL_StatusTypeDef st = HAL_I2C_Mem_Read_DMA(
        i2c_handle_, dev_addr, mem_addr,
        mem_addr_size == MemAddrLength::BYTE_8 ? I2C_MEMADD_SIZE_8BIT
                                               : I2C_MEMADD_SIZE_16BIT,
        reinterpret_cast<uint8_t*>(dma_buff_.addr_), read_data.size_);
    if (st != HAL_OK)
    {
      if (op.type == ReadOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
        return MapHalStartFailure(i2c_handle_, st);
      }
      if (op.type == ReadOperation::OperationType::POLLING)
      {
        op.UpdateStatus(in_isr, ErrorCode::BUSY);
      }
      return ErrorCode::BUSY;
    }
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      return WaitBlockResultAndRecoverTimeout(this, op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
  else
  {
    auto ans =
        HAL_I2C_Mem_Read(i2c_handle_, dev_addr, mem_addr,
                         mem_addr_size == MemAddrLength::BYTE_8 ? I2C_MEMADD_SIZE_8BIT
                                                                : I2C_MEMADD_SIZE_16BIT,
                         reinterpret_cast<uint8_t*>(read_data.addr_), read_data.size_,
                         20) == HAL_OK
            ? ErrorCode::OK
            : ErrorCode::BUSY;
 
    if (op.type != ReadOperation::OperationType::BLOCK)
    {
      op.UpdateStatus(in_isr, ans);
    }
    return ans;
  }
}

◆ MemWrite()

ErrorCode STM32I2C::MemWrite	(	uint16_t	slave_addr,
		uint16_t	mem_addr,
		ConstRawData	write_data,
		WriteOperation &	op,
		MemAddrLength	mem_addr_size,
		bool	in_isr )

overridevirtual

向 I2C 设备指定寄存器写入数据。 Writes data to a specific register of an I2C device.

该函数将 write_data 写入指定 I2C 从设备的寄存器地址。 This function writes write_data to the specified register of the I2C slave.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
mem_addr	寄存器地址（通常为 8 位或 16 位）。 Register address (typically 8-bit or 16-bit).
write_data	要写入的数据，`ConstRawData` 类型。 Data to be written, of type `ConstRawData`.
op	异步或同步的写入操作对象。 Write operation object (sync or async).
mem_addr_size	寄存器地址长度。 Size of register address in bytes.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns: 返回 ErrorCode，表示是否写入成功。 Returns ErrorCode indicating success or failure.

Implements LibXR::I2C.

Definition at line 841 of file stm32_i2c.cpp.

{
  ASSERT(write_data.size_ <= dma_buff_.size_);
 
  if (i2c_handle_->State != HAL_I2C_STATE_READY)
  {
    return ErrorCode::BUSY;
  }
 
  read_ = false;
 
  const uint16_t dev_addr = EncodeHalDevAddress(i2c_handle_, slave_addr);
 
  Memory::FastCopy(dma_buff_.addr_, write_data.addr_, write_data.size_);
 
  if (write_data.size_ > dma_enable_min_size_)
  {
    write_op_ = op;
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      // Arm the BLOCK waiter before HAL exposes completion to IRQ context.
      block_wait_.Start(*op.data.sem_info.sem);
    }
    STM32_CleanDCacheByAddr(dma_buff_.addr_, write_data.size_);
    op.MarkAsRunning();
    const HAL_StatusTypeDef st = HAL_I2C_Mem_Write_DMA(
        i2c_handle_, dev_addr, mem_addr,
        mem_addr_size == MemAddrLength::BYTE_8 ? I2C_MEMADD_SIZE_8BIT
                                               : I2C_MEMADD_SIZE_16BIT,
        reinterpret_cast<uint8_t*>(dma_buff_.addr_), write_data.size_);
    if (st != HAL_OK)
    {
      if (op.type == WriteOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
        return MapHalStartFailure(i2c_handle_, st);
      }
      if (op.type == WriteOperation::OperationType::POLLING)
      {
        op.UpdateStatus(in_isr, ErrorCode::BUSY);
      }
      return ErrorCode::BUSY;
    }
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      return WaitBlockResultAndRecoverTimeout(this, op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
  else
  {
    auto ans =
        HAL_I2C_Mem_Write(i2c_handle_, dev_addr, mem_addr,
                          mem_addr_size == MemAddrLength::BYTE_8 ? I2C_MEMADD_SIZE_8BIT
                                                                 : I2C_MEMADD_SIZE_16BIT,
                          reinterpret_cast<uint8_t*>(dma_buff_.addr_), write_data.size_,
                          20) == HAL_OK
            ? ErrorCode::OK
            : ErrorCode::BUSY;
 
    if (op.type != WriteOperation::OperationType::BLOCK)
    {
      op.UpdateStatus(in_isr, ans);
    }
    return ans;
  }
}

◆ Read()

ErrorCode STM32I2C::Read	(	uint16_t	slave_addr,
		RawData	read_data,
		ReadOperation &	op,
		bool	in_isr )

overridevirtual

读取 I2C 设备的数据。 Reads data from an I2C device.

该函数从指定的 I2C 从设备地址读取数据，并存储到 read_data 中。 This function reads data from the specified I2C slave address and stores it in read_data.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
read_data	存储读取数据的 `RawData` 对象。 A `RawData` object to store the read data.
op	读取操作对象，包含同步或异步操作模式。 Read operation object containing synchronous or asynchronous operation mode.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns: 返回 ErrorCode，指示操作是否成功。 Returns an ErrorCode indicating whether the operation was successful.

Implements LibXR::I2C.

Definition at line 652 of file stm32_i2c.cpp.

{
  if (i2c_handle_->State != HAL_I2C_STATE_READY)
  {
    return ErrorCode::BUSY;
  }
 
  read_ = true;
 
  const uint16_t dev_addr = EncodeHalDevAddress(i2c_handle_, slave_addr);
 
  if (read_data.size_ > dma_enable_min_size_)
  {
    read_op_ = op;
    read_buff_ = read_data;
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      // Arm the BLOCK waiter before HAL exposes completion to IRQ context.
      block_wait_.Start(*op.data.sem_info.sem);
    }
    op.MarkAsRunning();
    const HAL_StatusTypeDef st = HAL_I2C_Master_Receive_DMA(
        i2c_handle_, dev_addr, reinterpret_cast<uint8_t*>(dma_buff_.addr_),
        read_data.size_);
    if (st != HAL_OK)
    {
      if (op.type == ReadOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
        return MapHalStartFailure(i2c_handle_, st);
      }
      if (op.type == ReadOperation::OperationType::POLLING)
      {
        op.UpdateStatus(in_isr, ErrorCode::BUSY);
      }
      return ErrorCode::BUSY;
    }
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      return WaitBlockResultAndRecoverTimeout(this, op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
  else
  {
    auto ans = HAL_I2C_Master_Receive(i2c_handle_, dev_addr,
                                      reinterpret_cast<uint8_t*>(read_data.addr_),
                                      read_data.size_, 20) == HAL_OK
                   ? ErrorCode::OK
                   : ErrorCode::BUSY;
    // BLOCK 模式下沿用统一状态更新路径。
    // Reuse the same status update path for BLOCK mode.
    if (op.type != ReadOperation::OperationType::BLOCK)
    {
      op.UpdateStatus(in_isr, ans);
    }
    return ans;
  }
}

◆ SetClockSpeed() [1/2]

template<typename T >

std::enable_if<!HasClockSpeed< T >::value >::type LibXR::STM32I2C::SetClockSpeed	(	T &	,
		const Configuration &	)

inline

Definition at line 98 of file stm32_i2c.hpp.

100 {

101 }

◆ SetClockSpeed() [2/2]

template<typename T >

std::enable_if< HasClockSpeed< T >::value >::type LibXR::STM32I2C::SetClockSpeed	(	T &	i2c_handle,
		const Configuration &	config )

inline

Definition at line 104 of file stm32_i2c.hpp.

  {
    i2c_handle->Init.ClockSpeed = config.clock_speed;
  }

◆ SetConfig()

ErrorCode STM32I2C::SetConfig ( Configuration config )

overridevirtual

配置 I2C 设备参数。 Configures the I2C device settings.

该函数用于设置 I2C 设备的参数，例如通信速率等。 This function sets the parameters of the I2C device, such as the communication speed.

Parameters

config 包含 I2C 设置信息的 Configuration 结构体。 A Configuration structure containing I2C settings.

Returns: 返回 ErrorCode，指示配置是否成功。 Returns an ErrorCode indicating whether the configuration was successful.

Implements LibXR::I2C.

Definition at line 911 of file stm32_i2c.cpp.

{
  if (i2c_handle_ == nullptr ||
      STM32_I2C_GetID(i2c_handle_->Instance) == STM32_I2C_ID_ERROR ||
      config.clock_speed == 0U)
  {
    return ErrorCode::ARG_ERR;
  }
  const auto is_busy = [this]()
  {
    return recovering_ || i2c_handle_->State != HAL_I2C_STATE_READY ||
           i2c_handle_->Lock == HAL_LOCKED ||
           __HAL_I2C_GET_FLAG(i2c_handle_, I2C_FLAG_BUSY) != RESET;
  };
  uint32_t timing = 0U;
  const auto old_init = i2c_handle_->Init;
  const I2CFilterState old_filter_state = CaptureI2CFilterState(i2c_handle_);
  if constexpr (HasClockSpeed<decltype(i2c_handle_)>::value)
  {
    if (config.clock_speed > 400000U)
    {
      return ErrorCode::NOT_SUPPORT;
    }
#if defined(I2C_CCR_CCR) && defined(HAL_RCC_MODULE_ENABLED)
    const uint32_t pclk = HAL_RCC_GetPCLK1Freq();
    const uint32_t factor =
        config.clock_speed <= 100000U
            ? 2U
            : (i2c_handle_->Init.DutyCycle == I2C_DUTYCYCLE_16_9 ? 25U : 3U);
    const uint64_t denominator = uint64_t(config.clock_speed) * factor;
    if (pclk == 0U || (uint64_t(pclk) + denominator - 1U) / denominator > I2C_CCR_CCR)
    {
      return ErrorCode::NOT_SUPPORT;
    }
#endif
  }
  else if constexpr (HasTiming<decltype(i2c_handle_)>::value)
  {
    if (!STM32I2CTiming::Compute(GetI2CClock(i2c_handle_->Instance), config.clock_speed,
                                 old_filter_state.analog_filter,
                                 old_filter_state.digital_filter, timing))
    {
      return ErrorCode::NOT_SUPPORT;
    }
  }
  else
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  // Report intrinsic configuration errors before transient controller state.
  // Calculation can be preempted, so re-check immediately before reset.
  if (is_busy())
  {
    return ErrorCode::BUSY;
  }
  if constexpr (HasClockSpeed<decltype(i2c_handle_)>::value)
  {
    SetClockSpeed(i2c_handle_, config);
  }
  else
  {
    SetTiming(i2c_handle_, timing);
  }
  if (!ResetI2CPeripheral(i2c_handle_->Instance))
  {
    i2c_handle_->Init = old_init;
    return ErrorCode::NOT_SUPPORT;
  }
  if (HAL_I2C_Init(i2c_handle_) != HAL_OK)
  {
    i2c_handle_->Init = old_init;
    if (ResetI2CPeripheral(i2c_handle_->Instance) && HAL_I2C_Init(i2c_handle_) == HAL_OK)
    {
      RestoreI2CFilterState(i2c_handle_, old_filter_state);
    }
    return ErrorCode::INIT_ERR;
  }
  RestoreI2CFilterState(i2c_handle_, old_filter_state);
  return ErrorCode::OK;
}

◆ SetTiming() [1/2]

template<typename T >

std::enable_if<!HasTiming< T >::value >::type LibXR::STM32I2C::SetTiming	(	T &	,
		uint32_t	)

inline

Definition at line 118 of file stm32_i2c.hpp.

119 {

120 }

◆ SetTiming() [2/2]

template<typename T >

std::enable_if< HasTiming< T >::value >::type LibXR::STM32I2C::SetTiming	(	T &	i2c_handle,
		uint32_t	timing )

inline

Definition at line 111 of file stm32_i2c.hpp.

  {
    i2c_handle->Init.Timing = timing;
  }

◆ Write()

ErrorCode STM32I2C::Write	(	uint16_t	slave_addr,
		ConstRawData	write_data,
		WriteOperation &	op,
		bool	in_isr )

overridevirtual

向 I2C 设备写入数据。 Writes data to an I2C device.

该函数将 write_data 写入指定的 I2C 从设备地址。 This function writes write_data to the specified I2C slave address.

Parameters

slave_addr	目标 I2C 从设备地址，不带 R/W 位。 Target I2C slave address, no R/W bit included.
write_data	需要写入的数据，`ConstRawData` 类型。 The data to be written, of type `ConstRawData`.
op	写入操作对象，包含同步或异步操作模式。 Write operation object containing synchronous or asynchronous operation mode.
in_isr	是否在中断中进行操作 / Whether the operation is performed in an ISR.

Returns: 返回 ErrorCode，指示操作是否成功。 Returns an ErrorCode indicating whether the operation was successful.

Implements LibXR::I2C.

Definition at line 713 of file stm32_i2c.cpp.

{
  if (i2c_handle_->State != HAL_I2C_STATE_READY)
  {
    return ErrorCode::BUSY;
  }
 
  read_ = false;
 
  const uint16_t dev_addr = EncodeHalDevAddress(i2c_handle_, slave_addr);
 
  Memory::FastCopy(dma_buff_.addr_, write_data.addr_, write_data.size_);
 
  if (write_data.size_ > dma_enable_min_size_)
  {
    write_op_ = op;
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      // Arm the BLOCK waiter before HAL exposes completion to IRQ context.
      block_wait_.Start(*op.data.sem_info.sem);
    }
    STM32_CleanDCacheByAddr(dma_buff_.addr_, write_data.size_);
    op.MarkAsRunning();
    const HAL_StatusTypeDef st = HAL_I2C_Master_Transmit_DMA(
        i2c_handle_, dev_addr, reinterpret_cast<uint8_t*>(dma_buff_.addr_),
        write_data.size_);
    if (st != HAL_OK)
    {
      if (op.type == WriteOperation::OperationType::BLOCK)
      {
        block_wait_.Cancel();
        return MapHalStartFailure(i2c_handle_, st);
      }
      if (op.type == WriteOperation::OperationType::POLLING)
      {
        op.UpdateStatus(in_isr, ErrorCode::BUSY);
      }
      return ErrorCode::BUSY;
    }
    if (op.type == WriteOperation::OperationType::BLOCK)
    {
      return WaitBlockResultAndRecoverTimeout(this, op.data.sem_info.timeout);
    }
    return ErrorCode::OK;
  }
  else
  {
    auto ans = HAL_I2C_Master_Transmit(i2c_handle_, dev_addr,
                                       reinterpret_cast<uint8_t*>(dma_buff_.addr_),
                                       write_data.size_, 20) == HAL_OK
                   ? ErrorCode::OK
                   : ErrorCode::BUSY;
    if (op.type != WriteOperation::OperationType::BLOCK)
    {
      op.UpdateStatus(in_isr, ans);
    }
    return ans;
  }
}

Member Data Documentation

◆ block_wait_

AsyncBlockWait LibXR::STM32I2C::block_wait_ {}

Definition at line 136 of file stm32_i2c.hpp.

136{};

◆ dma_buff_

RawData LibXR::STM32I2C::dma_buff_

Definition at line 128 of file stm32_i2c.hpp.

◆ dma_enable_min_size_

uint32_t LibXR::STM32I2C::dma_enable_min_size_

Definition at line 126 of file stm32_i2c.hpp.

◆ i2c_handle_

I2C_HandleTypeDef* LibXR::STM32I2C::i2c_handle_

Definition at line 125 of file stm32_i2c.hpp.

◆ id_

stm32_i2c_id_t LibXR::STM32I2C::id_

Definition at line 124 of file stm32_i2c.hpp.

◆ map

STM32I2C * STM32I2C::map = {nullptr}

static

Definition at line 138 of file stm32_i2c.hpp.

◆ read_

bool LibXR::STM32I2C::read_ = false

Definition at line 134 of file stm32_i2c.hpp.

◆ read_buff_

RawData LibXR::STM32I2C::read_buff_

Definition at line 132 of file stm32_i2c.hpp.

◆ read_op_

ReadOperation LibXR::STM32I2C::read_op_

Definition at line 130 of file stm32_i2c.hpp.

◆ recovering_

bool LibXR::STM32I2C::recovering_ = false

Definition at line 135 of file stm32_i2c.hpp.

◆ write_op_

WriteOperation LibXR::STM32I2C::write_op_

Definition at line 131 of file stm32_i2c.hpp.

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

driver/st/stm32_i2c.hpp
driver/st/stm32_i2c.cpp

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ STM32I2C()

Member Function Documentation

◆ MemRead()

◆ MemWrite()

◆ Read()

◆ SetClockSpeed() [1/2]

◆ SetClockSpeed() [2/2]

◆ SetConfig()

◆ SetTiming() [1/2]

◆ SetTiming() [2/2]

◆ Write()

Member Data Documentation

◆ block_wait_

◆ dma_buff_

◆ dma_enable_min_size_

◆ i2c_handle_

◆ id_

◆ map

◆ read_

◆ read_buff_

◆ read_op_

◆ recovering_

◆ write_op_