IPC Trace

学习阁2026/7/18大约 7 分钟调试工具调试IPCHook

6.5 IPC Trace

📚 本节导读

学习时长: 约 30 分钟
难度级别: ⭐⭐⭐☆☆
前置知识: 任务同步与通信（第4.3节）、信号量（第4.3.1节）

🎯 学习目标

理解 IPC Trace 的设计目的和架构
掌握 IPC Hook 机制的使用方法
掌握信号量追踪 Hook 点的注册和回调
理解环形缓冲区在追踪记录中的应用
能够分析 IPC Trace 追踪数据

一、概述

IPC Trace 是 OneOS 提供的 IPC 通信追踪工具，用于记录和分析任务间通信（Inter-Process Communication）的时序和状态。当系统出现死锁、优先级反转、资源竞争等疑难问题时，IPC Trace 可以帮助开发者快速定位问题根源。

IPC Trace 的核心设计思想是非侵入式 Hook 注入：

┌─────────────────────────────────────────────────┐
│                  IPC Trace 架构                    │
├─────────────────────────────────────────────────┤
│  ┌─────────┐   Hook Call   ┌──────────────────┐ │
│  │ IPC 对象 │ ────────────→ │  IPC Trace Hook  │ │
│  │ (Sem)   │               │  (os_ipc_trace)  │ │
│  └─────────┘               └────────┬─────────┘ │
│                                     │            │
│                                     ▼            │
│  ┌──────────────────────────────────────────────┐│
│  │          环形缓冲区 (Ring Buffer)              ││
│  │  ┌─────┬─────┬─────┬─────┬─────┬─────┐       ││
│  │  │Item0│Item1│Item2│ ... │ItemN│ ... │       ││
│  │  └─────┴─────┴─────┴─────┴─────┴─────┘       ││
│  └──────────────────────────────────────────────┘│
│                                     │            │
│                                     ▼            │
│  ┌──────────────────────────────────────────────┐│
│  │              追踪数据分析 (Shell)              ││
│  └──────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘

二、核心数据结构

2.1 IPC Trace 记录项 (`os_ipc_trace_item_t`)

来自 os_ipc_trace.h：

struct os_ipc_trace_item
{
    os_ubase_t desc;   /* 描述：操作类型或状态 */
    os_task_id task;   /* 触发操作的任务 */
    os_ubase_t irq;    /* 是否在中断上下文 */
};

成员	类型	说明
`desc`	`os_ubase_t`	描述字段，通常编码操作类型（如 wait/post）和状态（如 success/block）
`task`	`os_task_id`	触发该 IPC 操作的任务 ID，中断上下文则为 NULL
`irq`	`os_ubase_t`	标记是否在 ISR 中触发，0 表示任务上下文，非 0 表示中断上下文

2.2 IPC Trace 记录缓冲区 (`os_ipc_trace_rec_t`)

来自 os_ipc_trace.h：

struct os_ipc_trace_rec
{
    os_ipc_trace_item_t record[OS_IPC_TRACE_ITEM_NUM]; /* 追踪记录数组 */
    os_ubase_t          total_cnt;                     /* 总记录计数 */
    os_ubase_t          valid_cnt;                     /* 有效记录数 */
    rb_ring_buff_t      rb;                            /* 环形缓冲区 */
};

成员	说明
`record[]`	固定大小的追踪记录数组，大小由 `OS_IPC_TRACE_ITEM_NUM`（默认 10）决定
`total_cnt`	累计入队的总次数（用于统计）
`valid_cnt`	当前缓冲区中有效的记录数（≤ `OS_IPC_TRACE_ITEM_NUM`）
`rb`	环形缓冲区实例，基于 `record[]` 数组分配

2.3 IPC Trace 对象 (`os_ipc_trace_t`)

来自 os_ipc_trace.h：

struct os_ipc_trace
{
    os_ubase_t         ipc_obj;  /* 关联的 IPC 对象地址 */
    os_ipc_trace_rec_t trace;    /* 追踪记录 */
};

每个 IPC 对象（如信号量）可以关联一个独立的 os_ipc_trace_t，记录该对象的所有操作历史。

三、IPC Hook 机制

IPC Hook 是 OneOS 内核提供的一套通用的 Hook 注入框架，通过宏定义实现编译时 Hook 点的注册和调用。定义在 os_ipc_hook.h 中。

3.1 Hook 宏体系

/* 定义 Hook 函数指针（在源文件中） */
OS_IPC_HOOK_DEFINE(domain, hp, sta, ...)

/* 声明 Hook 函数指针（在头文件中） */
OS_IPC_HOOK_DECLARE(domain, hp, sta, ...)

/* 调用 Hook（在 IPC 操作代码中） */
OS_IPC_HOOK_CALL(domain, hp, sta, ...)

/* 注册 Hook 回调函数 */
OS_IPC_HOOK_ADD(domain, hp, sta, func)

/* 注销 Hook 回调函数 */
OS_IPC_HOOK_DEL(domain, hp, sta, func)

3.2 Hook 三层命名空间

层级	参数	含义	示例
域 (domain)	`domain`	IPC 对象类型	`sem`（信号量）、`mutex`（互斥锁）、`mq`（消息队列）
Hook 点 (hp)	`hp`	操作类型	`wait`（等待操作）、`post`（释放操作）
状态 (sta)	`sta`	操作结果	`success`（成功）、`block`（阻塞）、`timeout`（超时）

3.3 Hook 展开示例

以信号量 wait 操作的 success 状态为例：

// 声明 (os_sem_trace.h)
OS_IPC_HOOK_DECLARE(sem, wait, success, os_semaphore_id);
// 展开为: extern void (*gs_os_hook_sem_wait_success)(os_semaphore_id);

// 调用
OS_IPC_HOOK_CALL(sem, wait, success, sem);
// 展开为:
// do {
//     if (gs_os_hook_sem_wait_success) {
//         gs_os_hook_sem_wait_success(sem);
//     }
// } while (0);

四、信号量追踪

信号量是 IPC Trace 最典型的应用场景。OneOS 在信号量操作的关键路径上预设了多个 Hook 点。

4.1 信号量 Hook 点

定义在 os_sem_trace.h：

操作	Hook 点	状态	触发时机
`wait`	`sem_wait`	`success`	等待成功（获取到信号量）
`wait`	`sem_wait`	`fail`	等待失败
`wait`	`sem_wait`	`block`	等待阻塞（信号量不可用）
`wait`	`sem_wait`	`timeout`	等待超时
`post`	`sem_post`	`success`	释放成功
`post`	`sem_post`	`full`	信号量已满（达到最大值）
`post`	`sem_post`	`wake`	释放后唤醒等待任务

4.2 信号量 Hook 调用宏

#define OS_SEM_HOOK_CALL(sem, hp, sta, ...) OS_IPC_HOOK_CALL(sem, hp, sta, __VA_ARGS__)

使用示例：

// 在 os_semaphore_wait 成功时调用
OS_SEM_HOOK_CALL(sem, wait, success, sem);

// 在 os_semaphore_post 唤醒任务时调用
OS_SEM_HOOK_CALL(sem, post, wake, sem);

五、IPC Trace 核心 API 详解

5.1 ipc_trace_rec_init

os_err_t ipc_trace_rec_init(os_ipc_trace_t *ipct);

初始化追踪记录，清空所有数据和环形缓冲区。

5.2 ipc_trace_rec_enqueue

os_err_t ipc_trace_rec_enqueue(os_ipc_trace_t *ipct, os_ipc_trace_item_t *trace_data);

将追踪数据入队。使用 rb_ring_buff_put_force 强制写入（缓冲区满时覆盖最旧数据），同时更新 total_cnt 和 valid_cnt。

5.3 ipc_trace_rec_dequeue

os_err_t ipc_trace_rec_dequeue(os_ipc_trace_t *ipct, os_ipc_trace_item_t *trace_data);

从环形缓冲区中取出一条追踪数据。如果缓冲区为空则返回 OS_FAILURE。

5.4 ipc_trace_rec_add_kobj

os_err_t ipc_trace_rec_add_kobj(os_ipc_trace_t *ipct, os_ubase_t ipc_obj);

将追踪记录与 IPC 对象关联。ipc_obj 通常是 IPC 对象（如信号量）的地址。

5.5 ipc_trace_rec_del_kobj

os_err_t ipc_trace_rec_del_kobj(os_ipc_trace_t *ipct);

解除追踪记录与 IPC 对象的关联，并重置追踪记录。

5.6 ipc_trace_hook

os_err_t ipc_trace_hook(os_ipc_trace_t *ipct, os_ubase_t ipc_obj, os_ipc_trace_item_t *trace_data);

追踪 Hook 入口函数。首先检查 ipc_obj 是否匹配，匹配则调用 ipc_trace_rec_enqueue 入队。

六、配置参数

配置项	位置	默认值	说明
`OS_USING_IPC_TRACE`	Kconfig	n	启用 IPC Trace 功能
`OS_IPC_TRACE_ITEM_NUM`	os_ipc_trace.h	10	每个 IPC 对象的追踪记录数
`OS_USING_SEM_TRACE`	条件编译	n	启用信号量追踪
`OS_SEM_WAIT_HOOK`	条件编译	n	启用信号量 wait 操作的 Hook
`OS_SEM_POST_HOOK`	条件编译	n	启用信号量 post 操作的 Hook
`OS_USING_IPC_HOOK`	Kconfig	n	全局 IPC Hook 开关

七、使用示例

7.1 信号量追踪示例

#include <oneos_config.h>
#include <os_ipc_trace.h>
#include <os_ipc_hook.h>
#include <os_sem_trace.h>

/* 定义追踪对象 */
static os_ipc_trace_t g_sem_trace;

/* 信号量 wait 成功时的回调 */
static void sem_wait_success_hook(os_semaphore_id sem)
{
    os_ipc_trace_item_t trace_item = {
        .desc = 0x01,     /* 编码: wait_success */
        .task = os_task_self(),
        .irq  = 0,
    };
    ipc_trace_hook(&g_sem_trace, (os_ubase_t)sem, &trace_item);
}

/* 信号量 post 唤醒时的回调 */
static void sem_post_wake_hook(os_semaphore_id sem)
{
    os_ipc_trace_item_t trace_item = {
        .desc = 0x10,     /* 编码: post_wake */
        .task = os_task_self(),
        .irq  = 0,
    };
    ipc_trace_hook(&g_sem_trace, (os_ubase_t)sem, &trace_item);
}

/* 初始化追踪 */
void my_trace_init(void)
{
    /* 初始化追踪记录 */
    ipc_trace_rec_init(&g_sem_trace);

    /* 注册 Hook 回调 */
    OS_IPC_HOOK_ADD(sem, wait, success, sem_wait_success_hook);
    OS_IPC_HOOK_ADD(sem, post, wake, sem_post_wake_hook);
}

7.2 追踪数据分析

/* 读取并分析追踪数据 */
void my_trace_analyze(void)
{
    os_ipc_trace_item_t item;

    os_kprintf("=== IPC Trace Analysis ===\r\n");
    os_kprintf("Total operations: %d\r\n", g_sem_trace.trace.total_cnt);
    os_kprintf("Valid records: %d\r\n", g_sem_trace.trace.valid_cnt);

    /* 出队所有记录 */
    while (ipc_trace_rec_dequeue(&g_sem_trace, &item) == OS_SUCCESS)
    {
        os_kprintf("  desc:0x%lx task:%p irq:%lu\r\n",
                   item.desc, (void *)item.task, item.irq);
    }
}

7.3 关联 IPC 对象

os_semaphore_id my_sem;

void my_sem_trace_init(void)
{
    /* 创建信号量 */
    my_sem = os_semaphore_create(OS_NULL, "trace_sem", 1, 1);

    /* 关联追踪对象 */
    ipc_trace_rec_add_kobj(&g_sem_trace, (os_ubase_t)my_sem);
}

7.4 完整追踪流程

void task_producer(void *arg)
{
    while (1)
    {
        os_semaphore_wait(my_sem, OS_WAIT_FOREVER);
        /* 临界区操作 */
        os_semaphore_post(my_sem);
        os_task_tsleep(100);
    }
}

void task_consumer(void *arg)
{
    while (1)
    {
        os_semaphore_wait(my_sem, OS_WAIT_FOREVER);
        /* 临界区操作 */
        os_semaphore_post(my_sem);
        os_task_tsleep(200);
    }
}

/* 运行一段时间后，通过 Shell 命令查看追踪数据 */
/* 可以分析出信号量的竞争情况和等待时间 */

📝 本节小结

IPC Trace 通过 Hook 机制实现非侵入式 IPC 操作追踪
Hook 三层命名空间（域/操作/状态）提供了灵活的 Hook 点管理
环形缓冲区 保证追踪数据的内存安全，满时自动覆盖旧数据
信号量追踪 是 IPC Trace 的典型应用，预设了 7 个 Hook 点
追踪数据可用于分析死锁、优先级反转、资源竞争等疑难问题