HPM SDK I2C 主机驱动，适配 LibXR I2C 接口 / HPM SDK based I2C master driver for the LibXR I2C interface. More...

#include <hpm_i2c.hpp>

Inheritance diagram for LibXR::HPMI2C:

Collaboration diagram for LibXR::HPMI2C:

Classes
struct	WaitPolicy
	HPM I2C 忙等超时策略 / HPM I2C busy-wait timeout policy. More...

Public Types
enum class	AddressMode : uint8_t { ADDR_7BIT , ADDR_10BIT }
	HPM I2C 主机寻址模式 / HPM I2C master addressing mode. More...

enum class	SequenceFrame : uint8_t { FIRST , NEXT , LAST }
	HPM 主机顺序事务分段类型 / HPM master sequential transfer frame type. More...

enum class	TransferFlag : uint16_t { NONE = 0 , READ = 0x0001U , ADDR_10BIT = 0x0002U , NO_START = 0x0004U , NO_ADDRESS = 0x0008U , NO_READ_ACK = 0x0010U , NO_STOP = 0x0020U , WRITE_CHECK_ACK = 0x0040U }
	HPM 主机扩展事务标志 / HPM master extended transfer flags. More...

enum class	AsyncTransferKind : uint8_t { NONE , READ , WRITE , MEM_READ }
	HPM I2C 后台事务类型 / HPM I2C asynchronous transfer kind. More...

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

Public Member Functions
	HPMI2C (LibXRHpmI2cType *i2c, clock_name_t clock, I2C::Configuration config)
	构造 HPM I2C 主机对象 / Construct an HPM I2C master object.

ErrorCode	SetAddressMode (AddressMode mode)
	设置 HPM 主机寻址模式并重建控制器 / Set HPM master addressing mode and rebuild the controller.

ErrorCode	SetWaitPolicy (WaitPolicy policy)
	设置当前实例的忙等超时策略 / Set the busy-wait timeout policy for this instance.

WaitPolicy	GetWaitPolicy () const
	获取当前实例的忙等超时策略 / Get the current busy-wait timeout policy.

AddressMode	GetAddressMode () const
	获取当前 HPM 主机寻址模式 / Get current HPM master addressing mode.

ErrorCode	SequenceWrite (uint16_t slave_addr, ConstRawData write_data, SequenceFrame frame, bool check_ack, WriteOperation &op, bool in_isr=false)
	执行一段 HPM 主机顺序写事务 / Execute one HPM master sequential write frame.

ErrorCode	SequenceRead (uint16_t slave_addr, RawData read_data, SequenceFrame frame, ReadOperation &op, bool in_isr=false)
	执行一段 HPM 主机顺序读事务 / Execute one HPM master sequential read frame.

ErrorCode	TransferWithFlags (uint16_t slave_addr, RawData data, uint16_t flags, ReadOperation &op, bool in_isr=false)
	执行一段 HPM 扩展标志主机事务 / Execute one HPM master transfer with extended SDK flags.

ErrorCode	TransferWithFlags (uint16_t slave_addr, ConstRawData data, uint16_t flags, WriteOperation &op, bool in_isr=false)
	执行一段 HPM 扩展标志主机写事务 / Execute one HPM master write transfer with extended SDK flags.

ErrorCode	Read (uint16_t slave_addr, RawData read_data, ReadOperation &op, bool in_isr=false) override
	从 I2C 从设备读取字节 / Read bytes from an I2C slave.

ErrorCode	Write (uint16_t slave_addr, ConstRawData write_data, WriteOperation &op, bool in_isr=false) override
	向 I2C 从设备写入字节 / Write bytes to an I2C slave.

ErrorCode	MemRead (uint16_t slave_addr, uint16_t mem_addr, RawData read_data, ReadOperation &op, MemAddrLength mem_addr_size=MemAddrLength::BYTE_8, bool in_isr=false) override
	从 I2C 从设备寄存器或存储器地址读取字节 / Read bytes from an I2C slave register or memory address.

ErrorCode	MemWrite (uint16_t slave_addr, uint16_t mem_addr, ConstRawData write_data, WriteOperation &op, MemAddrLength mem_addr_size=MemAddrLength::BYTE_8, bool in_isr=false) override
	向 I2C 从设备寄存器或存储器地址写入字节 / Write bytes to an I2C slave register or memory address.

ErrorCode	SetConfig (Configuration config) override
	应用 I2C 时序配置 / Apply I2C timing configuration.

uint32_t	GetClockFreq () const
	获取当前缓存的 I2C 源时钟频率 / Get cached I2C source clock frequency.

void	CompleteAsyncTransfer (bool in_isr, ErrorCode ans)
	供 DMA / 中断完成路径调用的完成入口 / Completion entry used by DMA / interrupt driven paths.

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

Static Public Member Functions
static constexpr WaitPolicy	DefaultWaitPolicy ()
	返回默认 HPM I2C 忙等超时策略 / Return the default HPM I2C wait policy.

Detailed Description

HPM SDK I2C 主机驱动，适配 LibXR I2C 接口 / HPM SDK based I2C master driver for the LibXR I2C interface.

该类持有一个 HPM I2C 外设实例，并通过 LibXR::I2C 提供普通字节流传输和寄存器/存储器地址式传输。 This class owns one HPM I2C peripheral instance and exposes byte-stream transfers and register/memory-address transfers through LibXR::I2C.

默认按 7-bit 主机寻址模式启动，也可通过 HPMI2C::SetAddressMode() 切到 HPM SDK 已支持的 10-bit 主机寻址模式；若遇到超时、总线忙或无响应等典型主机故障，驱动会尝试用最近一次成功配置重建控制器。 The driver starts in 7-bit master addressing mode by default and can switch to the HPM SDK supported 10-bit master addressing mode through HPMI2C::SetAddressMode(). On typical master-side failures such as timeout, bus busy, or no response, the driver attempts to rebuild the controller with the most recent successful configuration.

BLOCK 模式保持同步阻塞式传输；POLLING / CALLBACK / NONE 的 Write / Read / MemRead 走 DMA 后台路径。DMA 通道和共享 HDMA 中断由 HPM SDK dma_mgr 组件管理，该组件是必需依赖（CONFIG_DMA_MGR=1，见 hpm_dma.hpp），构造函数通过 HPMDmaManager::EnsureInitialized() 完成一次性初始化。MemWrite 始终保持阻塞路径。对 10-bit / 扩展 flags 的 blocking 手工 phase 路径，地址阶段会显式等待 ADDRHIT，失败时按适配层策略强制 cleanup 并按原始 HPM 状态触发恢复链路。 BLOCK mode stays on synchronous blocking transfers. POLLING / CALLBACK / NONE use the DMA backed path for Write / Read / MemRead. DMA channels and the shared HDMA interrupt are managed by the HPM SDK dma_mgr component, which is a required dependency (CONFIG_DMA_MGR=1, see hpm_dma.hpp); the constructor performs the one-time initialization through HPMDmaManager::EnsureInitialized(). MemWrite always stays on the blocking path. For the blocking manual phase path used by 10-bit / extended-flag transfers, the address phase explicitly waits for ADDRHIT; failures force adapter-level cleanup and preserve the original HPM status for recovery handling.

后台 DMA 完成并不直接代表事务成功，驱动会在 DMA 结束后继续确认 I2C CMPL 和后置状态，再通过 UpdateStatus() 或 AsyncBlockWait 报告最终结果。 DMA completion alone is not treated as transfer success. After DMA finishes, the driver still verifies I2C CMPL and post-transfer status before reporting the final result through UpdateStatus() or AsyncBlockWait. 异步完成路径的 dma_done、cmpl_done、final_status 和 should_recover 原子状态由内部 AsyncCompletionStateMachine helper 统一更新，IRQ 和 DMA 回调只声明发生的事件。 The asynchronous completion atomics dma_done, cmpl_done, final_status, and should_recover are updated through the internal AsyncCompletionStateMachine helper, leaving IRQ and DMA callbacks to report events only.

当 DMA 后台事务正在进行时，同步 Read / Write / MemRead / MemWrite、顺序 SequenceRead / SequenceWrite 以及扩展 flags 手动 phase 入口会返回 BUSY；低层手动 helper 在清 FIFO、改 CTRL/INTEN 或发 START 前返回 HPM SDK 的 status_i2c_bus_busy，再由 ConvertStatus() 映射到 LibXR 错误码。 While a DMA-backed transfer is active, synchronous Read / Write / MemRead / MemWrite, sequential SequenceRead / SequenceWrite, and extended-flag manual phase entry points return BUSY. The low-level manual helper returns the HPM SDK status_i2c_bus_busy before clearing FIFO, changing CTRL/INTEN, or issuing START, and ConvertStatus() maps that status to the LibXR error code.

忙等路径统一经实现文件内部的 WaitUntil() 处理；工程可提供强定义 extern "C" void libxr_hpm_i2c_wait_relax_hook(void)，在等待 ADDRHIT、CMPL 或 FIFO 状态时插入调度让出、低功耗等待或板级短延时。默认实现仅执行一个 nop，不改变无 RTOS 裸机场景的时序假设。WaitUntil() 缓存首次读取的 clock_get_core_clock_ticks_per_us() 结果，并使用 unsigned elapsed ticks 比较以避免 deadline 加法回绕；HPM SDK hpm_csr_get_core_cycle() 返回 64-bit CYCLE 值，事务期间仍假设 core clock 不被动态改频。 Busy-wait paths are centralized through the implementation-local WaitUntil(). A project may provide a strong extern "C" void libxr_hpm_i2c_wait_relax_hook(void) definition to yield to a scheduler, enter a low-power wait, or add a board-level short delay while waiting for ADDRHIT, CMPL, or FIFO status. The default fallback only executes one nop, preserving bare-metal timing assumptions when no hook is supplied. WaitUntil() caches the first clock_get_core_clock_ticks_per_us() result and uses an unsigned elapsed-tick comparison to avoid deadline-addition wrap-around. The HPM SDK hpm_csr_get_core_cycle() API returns a 64-bit CYCLE value; the core clock is still assumed not to be dynamically retuned during I2C transfers. 每个实例可通过 SetWaitPolicy() 调整这些超时值。 Per-instance timeout values can be adjusted with SetWaitPolicy().

默认 ISR wrapper 按 HPM_I2Cn、IRQn_I2Cn 和 HPM_DMA_SRC_I2Cn 等 HPM SDK header 宏构建同一个实例资源表；该表已拆到 hpm_i2c_platform.hpp 内部 helper，并由该 helper 解析 index、IRQ 和 DMA request source；若项目层后续要自行接管同一 IRQ，需要单独调整 ownership 方案。 The default ISR wrapper adapts to multi-series instances through HPM SDK header macros such as HPM_I2Cn, IRQn_I2Cn, and HPM_DMA_SRC_I2Cn. The shared instance resource table lives in the internal hpm_i2c_platform.hpp helper, which resolves index, IRQ, and DMA request source. If project code needs to own the same IRQ later, the ownership scheme should be revised in a separate change.

编译期支持由 HPMSOC_HAS_HPMSDK_I2C 和 __has_include("hpm_i2c_drv.h") 同时 gate；缺少能力宏或裁剪 SDK 头时仍保留 LibXR API 形状，但所有事务返回 NOT_SUPPORT，避免 driver/hpm glob 构建在无 I2C SoC 上因 SDK 头缺失失败。 Compile-time support is gated by both HPMSOC_HAS_HPMSDK_I2C and __has_include("hpm_i2c_drv.h"). When the capability macro or trimmed SDK header is missing, the LibXR API shape remains available but transfer APIs return NOT_SUPPORT, preventing the driver/hpm glob build from failing on SoCs without I2C.

Definition at line 142 of file hpm_i2c.hpp.

Member Enumeration Documentation

◆ AddressMode

enum class LibXR::HPMI2C::AddressMode : uint8_t

strong

HPM I2C 主机寻址模式 / HPM I2C master addressing mode.

Enumerator
ADDR_7BIT	7-bit 从地址 / 7-bit slave addressing.
ADDR_10BIT	10-bit 从地址 / 10-bit slave addressing.

Definition at line 148 of file hpm_i2c.hpp.

  {
    ADDR_7BIT,  
    ADDR_10BIT  
  };

◆ AsyncTransferKind

enum class LibXR::HPMI2C::AsyncTransferKind : uint8_t

strong

HPM I2C 后台事务类型 / HPM I2C asynchronous transfer kind.

Definition at line 192 of file hpm_i2c.hpp.

  {
    NONE,
    READ,
    WRITE,
    MEM_READ
  };

◆ SequenceFrame

enum class LibXR::HPMI2C::SequenceFrame : uint8_t

strong

HPM 主机顺序事务分段类型 / HPM master sequential transfer frame type.

Enumerator
FIRST	带 START 和地址阶段 / Includes START and address phase.
NEXT	中间段，不带 START/STOP / Middle frame without START/STOP.
LAST	末段，带 STOP / Final frame with STOP.

Definition at line 157 of file hpm_i2c.hpp.

  {
    FIRST,  
    NEXT,   
    LAST    
  };

◆ TransferFlag

enum class LibXR::HPMI2C::TransferFlag : uint16_t

strong

HPM 主机扩展事务标志 / HPM master extended transfer flags.

Definition at line 167 of file hpm_i2c.hpp.

  {
    NONE = 0,
#if LIBXR_HPM_I2C_SUPPORTED
    READ = I2C_RD,
    ADDR_10BIT = I2C_ADDR_10BIT,
    NO_START = I2C_NO_START,
    NO_ADDRESS = I2C_NO_ADDRESS,
    NO_READ_ACK = I2C_NO_READ_ACK,
    NO_STOP = I2C_NO_STOP,
    WRITE_CHECK_ACK = I2C_WRITE_CHECK_ACK
#else
    READ = 0x0001U,
    ADDR_10BIT = 0x0002U,
    NO_START = 0x0004U,
    NO_ADDRESS = 0x0008U,
    NO_READ_ACK = 0x0010U,
    NO_STOP = 0x0020U,
    WRITE_CHECK_ACK = 0x0040U
#endif
  };

Constructor & Destructor Documentation

◆ HPMI2C()

HPMI2C::HPMI2C	(	LibXRHpmI2cType *	i2c,
		clock_name_t	clock,
		I2C::Configuration	config )

构造 HPM I2C 主机对象 / Construct an HPM I2C master object.

Parameters

i2c	HPM I2C 外设基地址，不能为空 / HPM I2C peripheral base address. Must not be nullptr.
clock	HPM 时钟树名称，用于开启并查询外设源时钟。引脚复用和时钟源/分频由 BSP 在构造前配置（例如 HPM Pinmux Tool 生成的函数），驱动不调用板级 helper / HPM clock name used to enable and query the peripheral source clock. The BSP sets up the pin mux and the clock source/divider before construction (for example with the functions generated by the HPM Pinmux Tool); the driver calls no board helper.
config	初始 I2C 总线配置；当前 HPM 后端只接受 100 kHz、400 kHz、1 MHz 三个固定速率，其他速率由 SetConfig() 返回 NOT_SUPPORT。默认地址模式为 7-bit，如需 10-bit 可在构造后调用 SetAddressMode() / Initial I2C bus configuration. The current HPM backend accepts only three fixed rates: 100 kHz, 400 kHz, and 1 MHz. Other rates are rejected by SetConfig(). The default address mode is 7-bit; call SetAddressMode() after construction to switch to 10-bit when needed.

Note: 构造函数会在外设指针为空、源时钟无法解析或初始配置无效时断言失败 / The constructor asserts when the peripheral pointer is null, the source clock cannot be resolved, or the initial configuration is invalid.

Definition at line 2232 of file hpm_i2c.cpp.

    : i2c_(i2c), clock_(clock), current_config_(config)
{
  (void)i2c_;
  (void)clock_;
}

Member Function Documentation

◆ CompleteAsyncTransfer()

void LibXR::HPMI2C::CompleteAsyncTransfer	(	bool	in_isr,
		ErrorCode	ans )

供 DMA / 中断完成路径调用的完成入口 / Completion entry used by DMA / interrupt driven paths.

Parameters

in_isr	当前是否位于中断上下文 / Whether current context is ISR.
ans	事务最终错误码 / Final transfer error code.

◆ DefaultWaitPolicy()

static constexpr WaitPolicy LibXR::HPMI2C::DefaultWaitPolicy ( )

inlinestaticconstexpr

返回默认 HPM I2C 忙等超时策略 / Return the default HPM I2C wait policy.

Returns: 默认超时策略 / Default timeout policy.

Definition at line 222 of file hpm_i2c.hpp.

  {
    return {500ULL, 1000ULL, 1000ULL, 500000ULL};
  }

◆ GetAddressMode()

AddressMode LibXR::HPMI2C::GetAddressMode ( ) const

inline

获取当前 HPM 主机寻址模式 / Get current HPM master addressing mode.

Returns: 当前地址模式 / Current address mode.

Definition at line 287 of file hpm_i2c.hpp.

287{ return address_mode_; }

◆ GetClockFreq()

uint32_t LibXR::HPMI2C::GetClockFreq ( ) const

inline

获取当前缓存的 I2C 源时钟频率 / Get cached I2C source clock frequency.

Returns: 源时钟频率，单位 Hz；成功解析时钟前为 0 / Source clock frequency in Hz, or 0 before successful clock discovery.

Definition at line 491 of file hpm_i2c.hpp.

491{ return source_clock_hz_; }

◆ GetWaitPolicy()

WaitPolicy LibXR::HPMI2C::GetWaitPolicy ( ) const

inline

获取当前实例的忙等超时策略 / Get the current busy-wait timeout policy.

Returns: 当前策略 / Current policy.

Definition at line 281 of file hpm_i2c.hpp.

281{ return wait_policy_; }

◆ MemRead()

ErrorCode HPMI2C::MemRead	(	uint16_t	slave_addr,
		uint16_t	mem_addr,
		RawData	read_data,
		ReadOperation &	op,
		MemAddrLength	mem_addr_size = MemAddrLength::BYTE_8,
		bool	in_isr = false )

overridevirtual

从 I2C 从设备寄存器或存储器地址读取字节 / Read bytes from an I2C slave register or memory address.

该接口先发送寄存器/存储器地址，再进入读阶段。BYTE_8 只发送 mem_addr 低 8 位； BYTE_16 按高字节在前、低字节在后的顺序发送。 This API sends the register/memory address before the read phase. BYTE_8 sends only the low 8 bits of mem_addr; BYTE_16 sends the high byte first, then the low byte.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address for the current addressing mode, without the R/W bit.
mem_addr	读阶段前发送的寄存器或存储器地址 / Register or memory address sent before reading.
read_data	目标缓冲区；size_ 为 0 时不访问总线并返回 OK。非零长度时 addr_ 必须非空，且 size_ 不超过 I2C_SOC_TRANSFER_COUNT_MAX / Destination buffer. A zero-size buffer completes with OK without bus access. For non-zero size, addr_ must be non-null and size_ must not exceed I2C_SOC_TRANSFER_COUNT_MAX.
op	LibXR 读操作描述符，见类注释中的操作模式说明 / LibXR read operation descriptor. See class-level operation mode notes.
mem_addr_size	寄存器地址宽度：BYTE_8 或 BYTE_16 / Register address width: BYTE_8 or BYTE_16.
in_isr	仅用于 CALLBACK/POLLING 完成分发的中断上下文标志 / ISR-context flag forwarded only to CALLBACK/POLLING completion handling.

Returns: 成功返回 OK；空缓冲指针返回 PTR_NULL；从地址超出当前寻址模式范围返回 ARG_ERR；寄存器地址长度枚举无效时返回 ARG_ERR；读载荷长度超限返回 SIZE_ERR；其余返回 HPM SDK 状态转换后的错误码 / Returns OK on success, PTR_NULL for null non-empty buffer, SIZE_ERR for oversized read payload, ARG_ERR for slave addresses beyond the active addressing range or invalid register-address enum, or converted HPM SDK status otherwise.

Implements LibXR::I2C.

Definition at line 2333 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(mem_addr);
  UNUSED(read_data);
  UNUSED(mem_addr_size);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ MemWrite()

ErrorCode HPMI2C::MemWrite	(	uint16_t	slave_addr,
		uint16_t	mem_addr,
		ConstRawData	write_data,
		WriteOperation &	op,
		MemAddrLength	mem_addr_size = MemAddrLength::BYTE_8,
		bool	in_isr = false )

overridevirtual

向 I2C 从设备寄存器或存储器地址写入字节 / Write bytes to an I2C slave register or memory address.

该接口先发送寄存器/存储器地址，再发送载荷。BYTE_8 只发送 mem_addr 低 8 位； BYTE_16 按高字节在前、低字节在后的顺序发送。零长度载荷合法，只写地址字节。 This API sends the register/memory address before the payload. BYTE_8 sends only the low 8 bits of mem_addr; BYTE_16 sends the high byte first, then the low byte. A zero-size payload is valid and writes only the address bytes.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address for the current addressing mode, without the R/W bit.
mem_addr	载荷前发送的寄存器或存储器地址 / Register or memory address sent before the payload.
write_data	源载荷缓冲区；非零长度时 addr_ 必须非空；地址字节加载荷长度不能超过 I2C_SOC_TRANSFER_COUNT_MAX / Source payload buffer. For non-zero size, addr_ must be non-null. Address bytes plus payload size must not exceed I2C_SOC_TRANSFER_COUNT_MAX.
op	LibXR 写操作描述符，见类注释中的操作模式说明 / LibXR write operation descriptor. See class-level operation mode notes.
mem_addr_size	寄存器地址宽度：BYTE_8 或 BYTE_16 / Register address width: BYTE_8 or BYTE_16.
in_isr	仅用于 CALLBACK/POLLING 完成分发的中断上下文标志 / ISR-context flag forwarded only to CALLBACK/POLLING completion handling.

Returns: 成功返回 OK；空载荷指针返回 PTR_NULL；从地址超出当前寻址模式范围返回 ARG_ERR；寄存器地址长度枚举无效时返回 ARG_ERR；地址加载荷长度超限返回 SIZE_ERR；其余返回 HPM SDK 状态转换后的错误码 / Returns OK on success, PTR_NULL for null non-empty payload, SIZE_ERR when address bytes plus payload exceed the hardware limit, ARG_ERR for slave addresses beyond the active addressing range or invalid register-address enum, or converted HPM SDK status otherwise.

Implements LibXR::I2C.

Definition at line 2343 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(mem_addr);
  UNUSED(write_data);
  UNUSED(mem_addr_size);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ Read()

ErrorCode HPMI2C::Read	(	uint16_t	slave_addr,
		RawData	read_data,
		ReadOperation &	op,
		bool	in_isr = false )

overridevirtual

从 I2C 从设备读取字节 / Read bytes from an I2C slave.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address for the current addressing mode, without the R/W bit.
read_data	目标缓冲区；size_ 为 0 时不访问总线并返回 OK。非零长度时 addr_ 必须非空，且 size_ 不超过 I2C_SOC_TRANSFER_COUNT_MAX / Destination buffer. A zero-size buffer completes with OK without bus access. For non-zero size, addr_ must be non-null and size_ must not exceed I2C_SOC_TRANSFER_COUNT_MAX.
op	LibXR 读操作描述符，见类注释中的操作模式说明 / LibXR read operation descriptor. See class-level operation mode notes.
in_isr	仅用于 CALLBACK/POLLING 完成分发的中断上下文标志 / ISR-context flag forwarded only to CALLBACK/POLLING completion handling.

Returns: 成功返回 OK；空缓冲指针返回 PTR_NULL；从地址超出当前寻址模式范围返回 ARG_ERR；长度超限返回 SIZE_ERR；其余返回 HPM SDK 状态转换后的 TIMEOUT、BUSY、 NO_RESPONSE、CHECK_ERR 或 FAILED / Returns OK on success, PTR_NULL for null non-empty buffer, SIZE_ERR for oversized transfer, ARG_ERR for slave addresses beyond the active addressing range, or converted HPM SDK status such as TIMEOUT, BUSY, NO_RESPONSE, CHECK_ERR, or FAILED.

Implements LibXR::I2C.

Definition at line 2317 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(read_data);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ SequenceRead()

ErrorCode HPMI2C::SequenceRead	(	uint16_t	slave_addr,
		RawData	read_data,
		SequenceFrame	frame,
		ReadOperation &	op,
		bool	in_isr = false )

执行一段 HPM 主机顺序读事务 / Execute one HPM master sequential read frame.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address in the current addressing mode, without the R/W bit.
read_data	当前分段要读入的数据缓冲区，长度必须大于 0 / Destination buffer for this frame. Size must be greater than 0.
frame	分段类型：FIRST/NEXT/LAST / Frame type: FIRST, NEXT, or LAST.
op	LibXR 读操作描述符 / LibXR read operation descriptor.
in_isr	仅用于状态分发的中断上下文标志 / ISR-context flag for status dispatch.

Returns: 返回本段事务的最终错误码 / Final error code for this frame.

Definition at line 2365 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(read_data);
  UNUSED(frame);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ SequenceWrite()

ErrorCode HPMI2C::SequenceWrite	(	uint16_t	slave_addr,
		ConstRawData	write_data,
		SequenceFrame	frame,
		bool	check_ack,
		WriteOperation &	op,
		bool	in_isr = false )

执行一段 HPM 主机顺序写事务 / Execute one HPM master sequential write frame.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address in the current addressing mode, without the R/W bit.
write_data	当前分段要写出的数据，长度必须大于 0 / Payload for this frame. Size must be greater than 0.
frame	分段类型：FIRST/NEXT/LAST / Frame type: FIRST, NEXT, or LAST.
check_ack	是否逐字节检查从机 ACK / Whether to check slave ACK byte by byte.
op	LibXR 写操作描述符 / LibXR write operation descriptor.
in_isr	仅用于状态分发的中断上下文标志 / ISR-context flag for status dispatch.

Returns: 返回本段事务的最终错误码 / Final error code for this frame.

Definition at line 2354 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(write_data);
  UNUSED(frame);
  UNUSED(check_ack);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ SetAddressMode()

ErrorCode HPMI2C::SetAddressMode ( AddressMode mode )

设置 HPM 主机寻址模式并重建控制器 / Set HPM master addressing mode and rebuild the controller.

Parameters

mode	目标寻址模式，ADDR_7BIT 或 ADDR_10BIT / Target addressing mode, either ADDR_7BIT or ADDR_10BIT.

Returns: 成功返回 OK；外设指针为空返回 PTR_NULL；时钟/配置重建失败时返回相应错误码 / Returns OK on success, PTR_NULL for null peripheral, or the underlying clock / configuration failure otherwise.

Note: LibXR::I2C 的通用 Configuration 目前只描述总线速率，因此 10-bit 控制以 HPMI2C 扩展接口暴露，而不是塞进基类配置里 / LibXR::I2C::Configuration currently describes only bus speed, so 10-bit control is exposed as an HPMI2C extension instead of being packed into the generic base configuration.

Definition at line 2239 of file hpm_i2c.cpp.

{
  address_mode_ = mode;
  return ErrorCode::NOT_SUPPORT;
}

◆ SetConfig()

ErrorCode HPMI2C::SetConfig ( Configuration config )

overridevirtual

应用 I2C 时序配置 / Apply I2C timing configuration.

Parameters

config 目标 I2C 时钟配置 / Desired I2C clock configuration.

Returns: 成功返回 OK；外设指针为空返回 PTR_NULL；源时钟无法解析返回 INIT_ERR；时钟为 0 返回 ARG_ERR；非 100 kHz / 400 kHz / 1 MHz 的速率返回 NOT_SUPPORT；其余返回 HPM SDK 初始化状态 / Returns OK on success, PTR_NULL for null peripheral pointer, INIT_ERR when source clock cannot be resolved, ARG_ERR for zero clock, NOT_SUPPORT for rates other than 100 kHz / 400 kHz / 1 MHz, or converted HPM SDK initialization status otherwise.

Implements LibXR::I2C.

Definition at line 2310 of file hpm_i2c.cpp.

{
  current_config_ = config;
  configured_ = false;
  return ErrorCode::NOT_SUPPORT;
}

◆ SetWaitPolicy()

ErrorCode HPMI2C::SetWaitPolicy ( WaitPolicy policy )

设置当前实例的忙等超时策略 / Set the busy-wait timeout policy for this instance.

Parameters

policy 新策略；所有字段必须非零 / New policy. Every field must be nonzero.

Returns: 成功返回 OK；字段为 0 返回 ARG_ERR；后台 DMA 事务在途时返回 BUSY / Returns OK on success, ARG_ERR when any field is zero, or BUSY while a DMA-backed transfer is active.

Definition at line 76 of file hpm_i2c.cpp.

{
  if (policy.addr_hit_timeout_us == 0U || policy.stop_timeout_us == 0U ||
      policy.bus_idle_timeout_us == 0U || policy.transfer_timeout_us == 0U)
  {
    return ErrorCode::ARG_ERR;
  }
 
  if (AsyncTransferActive())
  {
    return ErrorCode::BUSY;
  }
 
  wait_policy_ = policy;
  return ErrorCode::OK;
}

◆ TransferWithFlags() [1/2]

ErrorCode HPMI2C::TransferWithFlags	(	uint16_t	slave_addr,
		ConstRawData	data,
		uint16_t	flags,
		WriteOperation &	op,
		bool	in_isr = false )

执行一段 HPM 扩展标志主机写事务 / Execute one HPM master write transfer with extended SDK flags.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address in the current addressing mode, without the R/W bit.
data	要写出的数据缓冲区 / Data buffer to be transmitted.
flags	HPM 扩展事务标志组合；READ 位若被传入会被忽略 / Combined HPM extended transfer flags. The READ bit is ignored when provided.
op	LibXR 写操作描述符 / LibXR write operation descriptor.
in_isr	仅用于状态分发的中断上下文标志 / ISR-context flag for status dispatch.

Returns: 返回事务最终错误码 / Final transfer error code.

Definition at line 2383 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(data);
  UNUSED(flags);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ TransferWithFlags() [2/2]

ErrorCode HPMI2C::TransferWithFlags	(	uint16_t	slave_addr,
		RawData	data,
		uint16_t	flags,
		ReadOperation &	op,
		bool	in_isr = false )

执行一段 HPM 扩展标志主机事务 / Execute one HPM master transfer with extended SDK flags.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address in the current addressing mode, without the R/W bit.
data	数据缓冲区；按 flags 指示读或写 / Data buffer used for read or write according to flags.
flags	HPM 扩展事务标志组合 / Combined HPM extended transfer flags.
op	LibXR 读写操作描述符 / LibXR read/write operation descriptor.
in_isr	仅用于状态分发的中断上下文标志 / ISR-context flag for status dispatch.

Returns: 返回事务最终错误码 / Final transfer error code.

Definition at line 2374 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(data);
  UNUSED(flags);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

◆ Write()

ErrorCode HPMI2C::Write	(	uint16_t	slave_addr,
		ConstRawData	write_data,
		WriteOperation &	op,
		bool	in_isr = false )

overridevirtual

向 I2C 从设备写入字节 / Write bytes to an I2C slave.

Parameters

slave_addr	当前寻址模式下的从设备地址，不包含 R/W 位 / Slave address for the current addressing mode, without the R/W bit.
write_data	源缓冲区；size_ 为 0 时不访问总线并返回 OK。非零长度时 addr_ 必须非空，且 size_ 不超过 I2C_SOC_TRANSFER_COUNT_MAX / Source buffer. A zero-size buffer completes with OK without bus access. For non-zero size, addr_ must be non-null and size_ must not exceed I2C_SOC_TRANSFER_COUNT_MAX.
op	LibXR 写操作描述符，见类注释中的操作模式说明 / LibXR write operation descriptor. See class-level operation mode notes.
in_isr	仅用于 CALLBACK/POLLING 完成分发的中断上下文标志 / ISR-context flag forwarded only to CALLBACK/POLLING completion handling.

Returns: 成功返回 OK；空缓冲指针返回 PTR_NULL；从地址超出当前寻址模式范围返回 ARG_ERR；长度超限返回 SIZE_ERR；其余返回 HPM SDK 状态转换后的 TIMEOUT、BUSY、 NO_RESPONSE、CHECK_ERR 或 FAILED / Returns OK on success, PTR_NULL for null non-empty buffer, SIZE_ERR for oversized transfer, ARG_ERR for slave addresses beyond the active addressing range, or converted HPM SDK status such as TIMEOUT, BUSY, NO_RESPONSE, CHECK_ERR, or FAILED.

Implements LibXR::I2C.

Definition at line 2325 of file hpm_i2c.cpp.

{
  UNUSED(slave_addr);
  UNUSED(write_data);
  return FinishOperation(op, in_isr, ErrorCode::NOT_SUPPORT);
}

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

driver/hpm/hpm_i2c.hpp
driver/hpm/hpm_i2c.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ AddressMode

◆ AsyncTransferKind

◆ SequenceFrame

◆ TransferFlag

Constructor & Destructor Documentation

◆ HPMI2C()

Member Function Documentation

◆ CompleteAsyncTransfer()

◆ DefaultWaitPolicy()

◆ GetAddressMode()

◆ GetClockFreq()

◆ GetWaitPolicy()

◆ MemRead()

◆ MemWrite()

◆ Read()

◆ SequenceRead()

◆ SequenceWrite()

◆ SetAddressMode()

◆ SetConfig()

◆ SetWaitPolicy()

◆ TransferWithFlags() [1/2]

◆ TransferWithFlags() [2/2]

◆ Write()