cpu_trace

cpu_trace 提供CPU指令跟踪功能，支持锁存和读取CPU核心的PC、LR、SP寄存器值，以及低功耗模式下的挂起与恢复。

头文件清单

#include "include/driver/cpu_trace_unified.h"

接口清单

接口名称	功能简述
uapi_cpu_trace_enable	使能CPU Trace功能
uapi_cpu_trace_disable	关闭CPU Trace功能
uapi_cpu_trace_enable_repeat	重新使能CPU Trace功能
uapi_cpu_trace_lock_pclr	锁存当前PC和LR
uapi_cpu_trace_get_locked_pc	获取锁存的PC值
uapi_cpu_trace_get_locked_lr	获取锁存的LR值
uapi_cpu_trace_get_locked_sp	获取锁存的SP值
uapi_cpu_trace_get_locked_regs	获取锁存的PC、LR、SP值
uapi_cpu_trace_pclr_set_passthrough	设置pclr锁存的直通功能
uapi_cpu_trace_suspend	停止CPU Trace功能（低功耗模式）
uapi_cpu_trace_resume	恢复CPU Trace功能（低功耗模式）

Functions

uapi_cpu_trace_enable

cpu_trace_enable uapi cpu trace enable uapi_cpu_trace_enable

void uapi_cpu_trace_enable(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 使能指定CPU核心的Trace功能，开启指令跟踪采集
• 调用时清零Trace存储区域并设置采集地址范围
• 设置CPU核心编号以选择待跟踪的目标核心

前置条件

• 调用时序约束：CPU Trace硬件已正常供电，对应核心时钟已开启
• 依赖关系：CPU Trace驱动模块已通过构建系统启用（CONFIG_DRIVER_SUPPORT_CPUTRACEV2已开启）

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

uapi_cpu_trace_disable

cpu_trace_disable uapi cpu trace disable uapi_cpu_trace_disable

void uapi_cpu_trace_disable(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 关闭指定CPU核心的Trace功能，停止指令跟踪采集
• 调用时执行数据同步屏障（DSB），确保CPU流水线数据刷新后再关闭Trace
• 关闭后CPU Trace存储区域数据保持不变，可继续读取

前置条件

• 调用时序约束：CPU Trace功能已通过uapi_cpu_trace_enable使能
• 依赖关系：CPU Trace硬件已正常供电

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

uapi_cpu_trace_enable_repeat

cpu_trace_enable_repeat uapi cpu trace enable repeat uapi_cpu_trace_enable_repeat

void uapi_cpu_trace_enable_repeat(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 重新使能指定CPU核心的Trace功能
• 调用时清零Trace存储区域后重新开启跟踪采集
• 适用于Trace缓冲区写满后需要重新开始采集的场景

前置条件

• 调用时序约束：CPU Trace硬件已正常供电，对应核心时钟已开启
• 依赖关系：CPU Trace驱动模块已通过构建系统启用

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

uapi_cpu_trace_lock_pclr

cpu_trace_lock_pclr uapi cpu trace lock pclr uapi_cpu_trace_lock_pclr

void uapi_cpu_trace_lock_pclr(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 锁存指定CPU核心当前的PC和LR寄存器值
• 调用时依次开启pclr时钟、执行锁存、关闭pclr时钟
• 锁存后可通过get_locked系列接口读取锁存的寄存器值

前置条件

• 调用时序约束：CPU Trace功能已使能
• 依赖关系：pclr硬件模块时钟可正常开关

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

uapi_cpu_trace_get_locked_pc

cpu_trace_get_locked_pc uapi cpu trace get locked pc uapi_cpu_trace_get_locked_pc

uint32_t uapi_cpu_trace_get_locked_pc(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 获取指定CPU核心通过lock_pclr锁存的PC寄存器值
• 返回CPU当前执行指令寄存器PC的锁存值

前置条件

• 调用时序约束：已通过uapi_cpu_trace_lock_pclr完成PC和LR的锁存
• 依赖关系：pclr锁存数据已就绪

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

返回值

• 返回类型：uint32_t

返回值	文字含义	触发场景
PC寄存器值	锁存的PC寄存器值	已完成lock_pclr锁存

uapi_cpu_trace_get_locked_lr

cpu_trace_get_locked_lr uapi cpu trace get locked lr uapi_cpu_trace_get_locked_lr

uint32_t uapi_cpu_trace_get_locked_lr(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 获取指定CPU核心通过lock_pclr锁存的LR寄存器值
• 返回CPU下一条执行指令寄存器LR/RA的锁存值

前置条件

• 调用时序约束：已通过uapi_cpu_trace_lock_pclr完成PC和LR的锁存
• 依赖关系：pclr锁存数据已就绪

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

返回值

• 返回类型：uint32_t

返回值	文字含义	触发场景
LR寄存器值	锁存的LR/RA寄存器值	已完成lock_pclr锁存

uapi_cpu_trace_get_locked_sp

cpu_trace_get_locked_sp uapi cpu trace get locked sp uapi_cpu_trace_get_locked_sp

uint32_t uapi_cpu_trace_get_locked_sp(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 获取指定CPU核心锁存的SP（栈指针）寄存器值
• 返回CPU当前栈指针的锁存值

前置条件

• 调用时序约束：已通过uapi_cpu_trace_lock_pclr完成锁存
• 依赖关系：pclr锁存数据已就绪

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

返回值

• 返回类型：uint32_t

返回值	文字含义	触发场景
SP寄存器值	锁存的SP寄存器值	已完成lock_pclr锁存

uapi_cpu_trace_get_locked_regs

cpu_trace_get_locked_regs uapi cpu trace get locked regs uapi_cpu_trace_get_locked_regs

bool uapi_cpu_trace_get_locked_regs(uint32_t cpu, uint32_t *pc, uint32_t *lr, uint32_t *sp)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 一次性获取指定CPU核心锁存的PC、LR、SP三个寄存器值
• 调用时通过关中断保护原子性，确保三个寄存器值的一致性

前置条件

• 调用时序约束：已通过uapi_cpu_trace_lock_pclr完成锁存
• 依赖关系：出参指针pc、lr、sp不为NULL，且指向有效内存空间

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

出参

名称	数据类型	输出说明
pc	uint32_t *	锁存的PC寄存器值，由调用方分配内存、函数填充
lr	uint32_t *	锁存的LR/RA寄存器值，由调用方分配内存、函数填充
sp	uint32_t *	锁存的SP寄存器值，由调用方分配内存、函数填充

返回值

• 返回类型：bool

返回值	文字含义	触发场景
true	成功	锁存寄存器值获取成功
false	失败	锁存寄存器值获取失败

参考案例

• src/middleware/utils/dfx/panic/private/panic.c

uapi_cpu_trace_pclr_set_passthrough

cpu_trace_pclr_set_passthrough uapi cpu trace pclr set passthrough uapi_cpu_trace_pclr_set_passthrough

void uapi_cpu_trace_pclr_set_passthrough(uint32_t cpu)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 设置pclr锁存的直通功能
• 使能后pclr模块以直通模式运行
• 设置指定CPU核心的pclr直通模式

前置条件

• 调用时序约束：CPU Trace功能已使能
• 依赖关系：pclr硬件模块可用

入参

名称	参数类型	详细说明	约束取值范围
cpu	uint32_t	设置的CPU核心编号	CPU_TRACE_TRACED_PORTING_BCPU(0) / CPU_TRACE_TRACED_PORTING_MCPU(1)

uapi_cpu_trace_suspend

cpu_trace_suspend uapi cpu trace suspend uapi_cpu_trace_suspend

errcode_t uapi_cpu_trace_suspend(uintptr_t arg)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 停止CPU Trace功能，用于低功耗模式进入休眠
• 当CPU Trace处于使能状态时，标记挂起标志；未使能时无操作
• 由低功耗管理框架在系统休眠时调用

前置条件

• 调用时序约束：CPU Trace模块已初始化
• 依赖关系：CONFIG_CPU_TRACE_SUPPORT_LPM已开启

入参

名称	参数类型	详细说明	约束取值范围
arg	uintptr_t	停止的参数	-

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	挂起操作完成
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_CPU_TRACE_SUPPORT_LPM	功能宏	支持CPU Trace低功耗模式功能	n
CONFIG_DRIVER_SUPPORT_CPUTRACEV2	编译参与宏	控制cpu_trace_v2模块参与编译	n

uapi_cpu_trace_resume

cpu_trace_resume uapi cpu trace resume uapi_cpu_trace_resume

errcode_t uapi_cpu_trace_resume(uintptr_t arg)

头文件清单

#include "include/driver/cpu_trace_unified.h"

功能说明

• 恢复CPU Trace功能，用于低功耗模式退出休眠
• 当CPU Trace处于挂起状态时，重新使能Trace并清除挂起标志
• 由低功耗管理框架在系统唤醒时调用

前置条件

• 调用时序约束：CPU Trace模块已初始化
• 依赖关系：CONFIG_CPU_TRACE_SUPPORT_LPM已开启

入参

名称	参数类型	详细说明	约束取值范围
arg	uintptr_t	恢复的参数，指定需要恢复的核心	-

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	恢复操作完成
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_CPU_TRACE_SUPPORT_LPM	功能宏	支持CPU Trace低功耗模式功能	n
CONFIG_DRIVER_SUPPORT_CPUTRACEV2	编译参与宏	控制cpu_trace_v2模块参与编译	n

Type definitions

errcode_t

errcode t errcode_t

typedef uint32_t errcode_t;

使用说明

uapi_cpu_trace_suspend和uapi_cpu_trace_resume的返回值类型 [SDK公共基础类型]

Enumerations

cpu_trace_cpu_num_t

typedef enum {
    CPU_TRACE_TRACED_PORTING_BCPU = 0,  // trace BCPU
    CPU_TRACE_TRACED_PORTING_MCPU = 1,  // trace MCPU
    CPU_TRACE_CPU_CORE_NUMS,
} cpu_trace_cpu_num_t;

枚举成员	取值	描述
CPU_TRACE_TRACED_PORTING_BCPU	0	跟踪BCPU核心
CPU_TRACE_TRACED_PORTING_MCPU	1	跟踪MCPU核心
CPU_TRACE_CPU_CORE_NUMS	2	CPU核心数量

Macros

ERRCODE_SUCC [SDK公共共享宏]

errcode succ errcode_succ

#define ERRCODE_SUCC                                        0UL