QuRT：你手机处理器内的实时操作系统 [完整手册]

# 从高通开发者门户下载 Hexagon SDK
# https://developer.qualcomm.com/software/hexagon-dsp-sdk

# 解压并运行安装程序
chmod +x qualcomm_hexagon_sdk_4_x_x_x.bin
./qualcomm_hexagon_sdk_4_x_x_x.bin

# 设置环境变量
export HEXAGON_SDK_ROOT=~/Qualcomm/Hexagon_SDK/4.x.x.x
export HEXAGON_TOOLS_ROOT=~/Qualcomm/Hexagon_SDK/4.x.x.x/tools
source $HEXAGON_SDK_ROOT/setup_sdk_env.source

# 检查 Hexagon 编译器
hexagon-clang --version

# 你应该看到类似如下输出：
# Qualcomm Hexagon Clang version 8.x.xx

# 运行 QuRT 模拟器以确认其正常工作
$HEXAGON_SDK_ROOT/tools/HEXAGON_Tools/8.x.xx/Tools/bin/hexagon-sim \
    --simulated_returnval --cosim_file \
    $HEXAGON_SDK_ROOT/libs/common/qurt/computev66/sdksim_bin/osam.cfg \
    -- $HEXAGON_SDK_ROOT/libs/common/qurt/computev66/sdksim_bin/bootimg.pbn

$HEXAGON_SDK_ROOT/examples/my_qurt_project/
├── src/
│   └── main.c              # 你的 QuRT 应用代码
├── inc/
│   └── my_module.h         # 头文件
├── hexagon.min              # 针对 Hexagon DSP 端的 SCons 构建配置
└── android.min              # 针对 ARM 端的 SCons 构建配置（若使用 FastRPC）

# hexagon.min - DSP 端的 SCons 构建描述符

BUILD_LIBS = libmy_qurt_app

# 源文件
libmy_qurt_app_C_SRCS = src/main.c

# QuRT 操作系统库
libmy_qurt_app_LIBS = atomic rpcmem

`.min` 文件格式是 Hexagon SDK 的 SCons 构建系统专用的。`BUILD_LIBS` 指定库的目标名称，`C_SRCS` 列出源文件，`LIBS` 指定要链接的库，`HEXAGON_CFLAGS` 设置编译器标志，而 `DLLS` 定义共享库的输出名称，其中 `_skel` 后缀是 FastRPC 为 DSP 端实现定义的约定。

在底层，SDK 的 `SConstruct` 会遍历项目树，读取每个 `.min` 文件，并将其声明转换为 SCons 构建目标。你在构建时传入的 `V`（变体）参数用于选择目标架构、构建类型和工具链版本。例如，`V=hexagon_Release_dynamic_toolv84_v66` 表示：针对 Hexagon 架构、发布模式、动态链接，使用 v84 工具链并面向 v66 DSP 架构进行构建。

对于需要比 `.min` 格式更精细控制的项目，你可以编写一个独立的 `SConscript` 文件：

使用 `SConscript` 方法可以完全访问 SCons 的功能：条件编译、自定义构建步骤、依赖扫描以及多变体构建。`Import('env')` 调用导入由 SDK 顶层 `SConstruct` 配置的构建环境，该环境已经包含了 Hexagon 编译器路径、QuRT 头文件和系统库的信息。`env.Clone()` 创建一个副本，确保你的修改不会影响项目树中的其他项目。

## QuRT 编程模型

QuRT 编程的核心思想非常简单明了：

**QuRT 是一个基于优先级的抢占式实时操作系统（RTOS）。** 这意味着所有代码都在线程中运行（不存在裸机主循环）。高优先级线程总是会立即抢占低优先级线程，无需协商。相同优先级的线程则采用时间片轮转调度。

调度器是无滴答（tick-less）的，意味着它不会周期性唤醒，仅在发生状态变化时运行，例如线程阻塞、信号被设置或更高优先级线程变为就绪状态。

此优先级图展示了 QuRT 的 256 个优先级级别的典型分配方式。优先级 0 是**最高**优先级，255 是**最低**优先级。这与 FreeRTOS 相反，在 FreeRTOS 中数值越大表示优先级越高。

中断处理程序占据最高优先级范围，系统任务紧随其后，用户线程通常位于中间范围。优先级为 255 的空闲线程仅在没有其他任务就绪时运行。

## 创建你的第一个 QuRT 线程

最简单的 QuRT 程序是创建一个线程，打印消息后退出。

该程序演示了 QuRT 中线程创建的四个步骤。第一步，调用 `qurt_thread_attr_init()` 初始化线程属性结构体；第二步，程序通过设置调试名称（出现在崩溃转储中）、栈地址、栈大小和优先级来配置线程；第三步，调用 `qurt_thread_create()` 创建并立即启动线程，传入函数指针和参数；第四步，调用 `qurt_thread_join()` 阻塞当前线程，直到新线程调用 `qurt_thread_exit()` 结束。

有两个细节至关重要：QuRT 不会自动为你分配栈内存，你必须提供一个静态分配且 8 字节对齐的缓冲区；此外，每个线程在返回前都必须调用 `qurt_thread_exit()`。如果线程函数直接返回而不调用 exit，其行为是未定义的。

### 线程创建流程

此流程展示了单个线程的生命周期。属性结构体充当配置对象：你先设置所有线程参数，然后将其传递给 `qurt_thread_create()`。一旦创建完成，线程便开始执行其入口函数。当入口函数调用 `qurt_thread_exit()` 时，线程终止，任何在 `qurt_thread_join()` 中阻塞的线程将被唤醒，并接收到退出状态码。

## 线程创建的内部工作原理

大多数教程都会跳过 `qurt_thread_create()` 内部发生的事情。理解其内部机制有助于更清晰地进行调试和优先级设计决策。

### 内核在线程创建期间的操作

当你调用 `qurt_thread_create()` 时，实际上是在向 QuRT 内核发起一个**系统调用**。内核会按顺序执行五个步骤：

这一流程中最令人意外的是第 5 步。如果新线程的优先级高于创建它的线程，那么**新线程会在**`qurt_thread_create()`**返回之前就开始运行**。创建线程在调用中途即被抢占。这正是“抢占式”调度的实际含义：调度器不会等待合适时机，而是立即强制执行优先级排序。

### 栈帧如何启动你的函数

当调度器首次进行上下文切换以运行一个全新线程时，它所做的操作与任何上下文切换完全相同：从 TCB 中恢复已保存的寄存器，并跳转到保存的程序计数器（PC）。

对于一个新线程，这些寄存器是在第 3 步中由内核人为构造出来的。**PC（程序计数器）**被设为 `my_thread_func`，因此处理器跳转到你的函数。**R0** 被设为你的 `arg` 参数，因此你的函数能将其作为第一个参数接收（遵循 Hexagon 调用约定）。**SP（栈指针）**被设为你的栈顶，因此你的函数拥有可用的栈空间。而**LR（链接寄存器）**被设为 `qurt_thread_exit`，因此如果你的函数正常返回（你不应依赖这一点），它将自动进入 `qurt_thread_exit`。

就像在一个你从未进入过的房间里醒来，  
但有人把一切都安排得如此完美，  
以至于你没有意识到自己并非从门口走进来的。  

时间 ──────────────────────────────────────────────►

线程 A (优先级 128)          内核/调度器               线程 B (优先级 64)
────────────────           ────────────────           ────────────────
调用                      
qurt_thread_create()       
   │                       
   ├─► 系统调用 ──────►     验证参数
                            分配 TCB
                            设置栈帧
                            将 B 插入就绪队列
                            
                            “B (64) > A (128)? 是。”
                            
                            保存 A 的寄存器   ──┐
                            到 A 的 TCB       │
                                               │
                            加载 B 的寄存器 ◄─┘
                            来自 B 的 TCB
                            （合成的寄存器值）
                            
                            跳转到 PC ────────► my_thread_func(arg)
                                               │
                                               │ 执行工作...
                                               │ 调用 qurt_thread_exit()
                                               │
                            B 从就绪队列移除 ◄─── 退出系统调用
                            
                            “下一个是谁？A。”
                            
                            加载 A 的寄存器
   │                        跳转到 A 的 PC
   │◄──────────────────────
   │
   ├─► qurt_thread_create()
   │   返回 QURT_EOK
   │
   ▼ 继续执行...

/* 概念上的 TCB 布局（简化版，非实际 QuRT 源码） */
struct qurt_tcb {
    /* 身份信息 */
    qurt_thread_t   thread_id;
    char            name[16];
    
    /* 调度相关 */
    uint8_t         base_priority;
    uint8_t         effective_priority; /* 可能因优先级继承而不同 */
    uint8_t         state;             /* READY, RUNNING, BLOCKED, SUSPENDED */
    
    /* 保存的 CPU 上下文（在上下文切换时填充） */
    uint32_t        saved_regs[32];
    uint32_t        saved_pc;
    uint32_t        saved_sp;
    uint32_t        saved_sr;
    
    /* 栈信息（用于调试和溢出检测） */
    void           *stack_base;
    size_t          stack_size;
    
    /* 阻塞信息 */
    void           *wait_object;  /* 正在等待的互斥锁/信号/管道 */
    uint32_t        wait_mask;    /* 正在等待的信号位 */
    
    /* 链表指针 */
    struct qurt_tcb *next_ready;
    struct qurt_tcb *next_waiting;
    
    /* Join 支持 */
    int             exit_status;  /* 传递给 qurt_thread_exit() 的值 */
    qurt_thread_t   joiner;      /* 在 qurt_thread_join() 中等待的线程 */
};

qurt_thread_create()
                           │
                           ▼
                    ┌──────────┐
          ┌─────────│  READY   │◄──────────────────────────┐
          │         └──────────┘                           │
          │              │ ▲                               │
          │  调度器选择   │ │ 被更高优先级                  │
          │  该线程      │ │ 线程抢占                       │
          │              │ │                              │
          │              ▼ │                               │
          │         ┌──────────┐     信号/互斥锁/          │
          │         │ RUNNING  │     定时器事件            │
          │         └──────────┘     唤醒线程               │
          │              │                                 │
          │  线程调用    │                                 │
          │  阻塞式 API： │                                 │
          │  - mutex_lock│                                 │
          │  - signal_   │                                 │
          │    wait      │                                 │
          │  - pipe_     │                                 │
          │    receive   ▼                                 │
          │         ┌──────────┐                           │
          │         │ BLOCKED  │───────────────────────────┘
          │         └──────────┘
          │
          │  qurt_thread_exit()
          │         │
          │         ▼
          │    ┌──────────┐
          └───►│  DEAD    │
               └──────────┘

┌─────────────────────────────────────────┐
│          Hexagon DSP 核心               │
│                                         │
│  ┌───────────┐  ┌───────────┐           │
│  │ 硬件线程  │  │ 硬件线程  │           │
│  │ 槽位 0    │  │ 槽位 1    │  ...      │
│  │           │  │           │           │
│  │ 线程 A    │  │ 线程 B    │           │
│  │ (运行中)  │  │ (运行中)  │           │
│  └───────────┘  └───────────┘           │
│                                         │
│  就绪队列: [C, D, E, F, ...]            │
│  调度器使用最高优先级的就绪线程         │
│  填充硬件槽位                           │
└─────────────────────────────────────────┘

static char stack[8192] __attribute__((aligned(8)));

void my_func(void *arg)
{
    /* 状态：RUNNING。栈已初始化，R0 寄存器包含 arg 参数 */
    int val = *(int *)arg;

    qurt_mutex_lock(&some_mutex);
    /* 如果互斥锁已被占用：状态变为 BLOCKED，直到持有者解锁 */

    shared_data = val;
    qurt_mutex_unlock(&some_mutex);

    qurt_thread_exit(QURT_EOK);
    /* 状态变为 DEAD。等待 join 的线程（若有）将被唤醒 */
}

int main(void)
{
    qurt_thread_t tid;
    qurt_thread_attr_t attr;
    int my_arg = 42;

    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_attr_set_stack_size(&attr, sizeof(stack));
    qurt_thread_attr_set_priority(&attr, 100);

    qurt_thread_create(&tid, &attr, my_func, &my_arg);
    /* 若 my_func 的优先级（100）高于 main：main 在此处被抢占 */

    int status;
    qurt_thread_join(tid, &status);
    /* 阻塞直到 my_func 退出；若已退出则立即返回 */
    
    return 0;
}

# 选项 1：使用 make 包装脚本（内部调用 SCons）
cd $HEXAGON_SDK_ROOT
make V=hexagon_Release_dynamic_toolv84_v66 \
     tree=my_qurt_project

# 选项 2：直接调用 SCons
cd $HEXAGON_SDK_ROOT
python tools/build/scons/scons.py \
    V=hexagon_Release_dynamic_toolv84_v66 \
    my_qurt_project

# 在模拟器上运行
hexagon-sim --simulated_returnval \
    --cosim_file osam.cfg \
    -- bootimg.pbn \
    -- my_qurt_app.so

#include <stdio.h>
#include <qurt.h>

#define STACK_SIZE    8192
#define BUFFER_SIZE   16
#define NUM_ITEMS     100

/* 线程栈 */
static char producer_stack[STACK_SIZE] __attribute__((aligned(8)));
static char consumer_stack[STACK_SIZE] __attribute__((aligned(8)));

/* 共享缓冲区 */
static int buffer[BUFFER_SIZE];
static int head = 0;
static int tail = 0;
static int count = 0;

/* 同步原语 */
qurt_mutex_t buffer_mutex;
qurt_cond_t  not_full;
qurt_cond_t  not_empty;

void producer_thread(void *arg)
{
    for (int i = 0; i < NUM_ITEMS; i++) {
        qurt_mutex_lock(&buffer_mutex);

        /* 等待缓冲区有空位 */
        while (count == BUFFER_SIZE) {
            qurt_cond_wait(&not_full, &buffer_mutex);
        }

        /* 生产一个项目 */
        buffer[head] = i;
        head = (head + 1) % BUFFER_SIZE;
        count++;

        printf("[Producer] Put item %d (buffer count: %d)\n", i, count);

        /* 通知消费者已有数据可用 */
        qurt_cond_signal(&not_empty);
        qurt_mutex_unlock(&buffer_mutex);
    }

    qurt_thread_exit(QURT_EOK);
}

void consumer_thread(void *arg)
{
    for (int i = 0; i < NUM_ITEMS; i++) {
        qurt_mutex_lock(&buffer_mutex);

        /* 等待缓冲区中有数据 */
        while (count == 0) {
            qurt_cond_wait(&not_empty, &buffer_mutex);
        }

        /* 消费一个项目 */
        int item = buffer[tail];
        tail = (tail + 1) % BUFFER_SIZE;
        count--;

        printf("[Consumer] Got item %d (buffer count: %d)\n", item, count);

        /* 通知生产者已有空间可用 */
        qurt_cond_signal(&not_full);
        qurt_mutex_unlock(&buffer_mutex);
    }

    qurt_thread_exit(QURT_EOK);
}

int main(void)
{
    qurt_thread_t producer, consumer;
    qurt_thread_attr_t attr;

    /* 在创建线程前初始化同步原语 */
    qurt_mutex_init(&buffer_mutex);
    qurt_cond_init(&not_full);
    qurt_cond_init(&not_empty);

    /* 创建生产者（更高优先级） */
    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_name(&attr, "producer");
    qurt_thread_attr_set_stack_addr(&attr, producer_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 100);
    qurt_thread_create(&producer, &attr, producer_thread, NULL);

    /* 创建消费者（较低优先级） */
    qurt_thread_attr_init(&attr);
    qurt_thread_attr_set_name(&attr, "consumer");
    qurt_thread_attr_set_stack_addr(&attr, consumer_stack);
    qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
    qurt_thread_attr_set_priority(&attr, 110);
    qurt_thread_create(&consumer, &attr, consumer_thread, NULL);

    /* 等待两个线程完成 */
    int status;
    qurt_thread_join(producer, &status);
    qurt_thread_join(consumer, &status);

    /* 清理资源 */
    qurt_mutex_destroy(&buffer_mutex);
    qurt_cond_destroy(&not_full);
    qurt_cond_destroy(&not_empty);

    printf("All done! Produced and consumed %d items.\n", NUM_ITEMS);
    return 0;
}

┌──────────────┬────────────────────────────────────────────────────┐
│ 原语         │ 使用场景                                           │
├──────────────┼────────────────────────────────────────────────────┤
│ 互斥锁       │ 保护共享数据免受并发访问                           │
│ 条件变量     │ “等待直到 X 为真”（始终与互斥锁配合使用）          │
│ 信号         │ 一个线程通知另一个线程（类似于轻拍某人提醒）       │
│ 屏障         │ “所有线程在此等待，直到全部到达”                   │
├──────────────┼────────────────────────────────────────────────────┤
│ 信号量       │ 控制对有限资源池的访问                             │
│              │ （例如，10 个线程共享 4 个 DMA 通道）              │
└──────────────┴────────────────────────────────────────────────────┘

qurt_mutex_t my_mutex;

void init_example(void)
{
    /* 使用前必须先初始化 */
    qurt_mutex_init(&my_mutex);
}

void critical_section_example(void)
{
    qurt_mutex_lock(&my_mutex);

    /* 同一时间仅有一个线程能执行此处代码 */
    shared_counter++;
    shared_buffer[index] = new_value;

    qurt_mutex_unlock(&my_mutex);
}

/* 非阻塞版本 */
void try_lock_example(void)
{
    int result = qurt_mutex_try_lock(&my_mutex);

    if (result == QURT_EOK) {
        shared_counter++;
        qurt_mutex_unlock(&my_mutex);
    } else {
        printf("忙，稍后重试\n");
    }
}

void cleanup_example(void)
{
    qurt_mutex_destroy(&my_mutex);
}

#include <qurt.h>

#define SIGNAL_DATA_READY   0x01
#define SIGNAL_STOP         0x02
#define SIGNAL_ERROR        0x04

qurt_signal_t my_signal;

void signal_init(void)
{
    qurt_signal_init(&my_signal);
}

/* 等待线程 */
void waiter_thread(void *arg)
{
    unsigned int received_signals;

    while (1) {
        /* 等待以下任意一个信号 */
        received_signals = qurt_signal_wait(
            &my_signal,
            SIGNAL_DATA_READY | SIGNAL_STOP | SIGNAL_ERROR,
            QURT_SIGNAL_ATTR_WAIT_ANY
        );

        if (received_signals & SIGNAL_STOP) {
            printf("收到停止信号，退出。\n");
            break;
        }

        if (received_signals & SIGNAL_DATA_READY) {
            printf("数据已就绪！开始处理...\n");
            process_data();
            /* 处理完成后清除信号位 */
            qurt_signal_clear(&my_signal, SIGNAL_DATA_READY);
        }

        if (received_signals & SIGNAL_ERROR) {
            printf("发生错误！正在处理...\n");
            handle_error();
            qurt_signal_clear(&my_signal, SIGNAL_ERROR);
        }
    }

    qurt_signal_destroy(&my_signal);
    qurt_thread_exit(QURT_EOK);
}

/* 发送信号的线程（或 ISR） */
void sender_thread(void *arg)
{
    prepare_data();
    qurt_signal_set(&my_signal, SIGNAL_DATA_READY);

    /* 稍后发送停止信号 */
    qurt_signal_set(&my_signal, SIGNAL_STOP);

    qurt_thread_exit(QURT_EOK);
}

#define NUM_WORKER_THREADS  4

qurt_barrier_t sync_barrier;

void worker_thread(void *arg)
{
    int thread_num = (int)(uintptr_t)arg;

    /* 第一阶段：每个线程独立计算部分结果 */
    printf("线程 %d：正在计算第一阶段...\n", thread_num);
    compute_partial_result(thread_num);

屏障使用参与的线程数量进行初始化。每个线程在到达同步点时调用 `qurt_barrier_wait()`。该调用会阻塞，直到所有线程都到达。当最后一个线程调用 `qurt_barrier_wait()` 后，所有线程将同时被释放，并继续进入第二阶段。

### 信号量

信号量用于控制对 N 个相同资源池的访问。与互斥锁（即 N=1 的信号量）不同，信号量允许多达 N 个线程同时持有它。

信号量初始计数值为 4，对应于 DMA 通道的数量。每次调用 `qurt_sem_down()` 都会使计数减一，若计数变为零则阻塞。每次调用 `qurt_sem_up()` 都会使计数加一，并唤醒一个等待中的线程（如果有）。这确保了同时使用 DMA 通道的线程不会超过 4 个。

## 内存管理

DSP 上的内存是有限的。典型的 Hexagon DSP 拥有 256 KB 到 2 MB 的紧耦合内存（TCM），并可访问 DDR。QuRT 提供了有效管理这两种内存的工具。

### 内存布局

此图展示了从低地址到高地址的 Hexagon DSP 内存布局。QuRT 内核位于最低地址区域，用户代码无法访问。其上方是配置为 TCM 模式的 L2 缓存，用于存放热点数据。虚拟内存区域用于存放用户堆和线程栈。最上方的 DDR 与 ARM CPU 共享，用于存储大型数据缓冲区、机器学习模型权重和媒体帧。DDR 的容量远大于 TCM，但延迟更高。

### 动态内存分配

QuRT 提供了标准 C 堆，因此 `malloc` 和 `free` 可按预期工作。但 `malloc` 的执行时间不可预测，因为它可能需要搜索空闲链表、分割块或合并相邻的空闲区域。这使得它不适合实时关键路径，因为这些路径要求执行时间必须是确定性的。应仅在初始化和销毁阶段使用 `malloc`，避免在每帧或每个采样点进行分配。

### 缓存管理

在 Hexagon DSP 上，当与 ARM CPU 共享内存时，显式的缓存管理至关重要。

`qurt_mem_region_create()` 调用分配了一个物理连续的内存区域，适合与其他处理器共享。`QURT_MEM_REGION_SHARED` 标志将其标记为可用于跨处理器通信。

共享内存的缓存规则简单却至关重要：

1.  **读取前失效（Invalidate）**：确保你看到的是 ARM CPU 最新写入的数据，而不是陈旧的缓存项。

2.  **写入后刷新（Flush）**：确保你的更改能被 ARM CPU 看到，而不是主存中的旧内容。

忽略这些操作会导致逻辑正确但运行异常的 bug，因为代码操作的是过时的数据。

### 用于可预测分配的内存池

内存池提供 O(1) 时间复杂度的分配，适用于实时关键路径。

/* 内存池的内存是静态分配的，以保证确定性 */
static char pool_memory[BLOCK_SIZE * NUM_BLOCKS] __attribute__((aligned(8)));
static qurt_mem_pool_t my_pool;

void pool_init(void)
{
    qurt_mem_pool_create(&my_pool, pool_memory,
                          BLOCK_SIZE * NUM_BLOCKS,
                          BLOCK_SIZE);
}

void *pool_alloc(void)
{
    void *block = qurt_mem_pool_alloc(&my_pool);
    if (!block) {
        printf("内存池已耗尽！\n");
    }
    return block;
}

void pool_free(void *block)
{
    qurt_mem_pool_free(&my_pool, block);
}

#include <qurt.h>
#include <qurt_timer.h>

qurt_timer_t my_timer;
qurt_signal_t timer_signal;

#define TIMER_EXPIRED_SIGNAL  0x01

void timer_example(void)
{
    qurt_signal_init(&timer_signal);

    qurt_timer_attr_t attr;
    qurt_timer_attr_init(&attr);

    /* 设置定时器持续时间：10 毫秒 */
    qurt_timer_attr_set_duration(&attr,
        qurt_timer_convert_time_to_ticks(10000,  /* 微秒 */
                                          QURT_TIME_USEC));

    /* 设置定时器到期时触发的信号 */
    qurt_timer_attr_set_signal(&attr, &timer_signal);
    qurt_timer_attr_set_signal_mask(&attr, TIMER_EXPIRED_SIGNAL);

    /* 单次触发：仅触发一次 */
    qurt_timer_attr_set_type(&attr, QURT_TIMER_ONESHOT);

    /* 创建并启动定时器 */
    qurt_timer_create(&my_timer, &attr);

    /* 等待定时器到期 */
    qurt_signal_wait(&timer_signal,
                      TIMER_EXPIRED_SIGNAL,
                      QURT_SIGNAL_ATTR_WAIT_ANY);

    printf("定时器已到期！10ms 已过去。\n");
    qurt_signal_clear(&timer_signal, TIMER_EXPIRED_SIGNAL);

    /* 清理资源 */
    qurt_timer_delete(my_timer);
    qurt_signal_destroy(&timer_signal);
}

void periodic_timer_thread(void *arg)
{
    qurt_timer_t periodic_timer;
    qurt_signal_t periodic_signal;
    qurt_timer_attr_t attr;

    qurt_signal_init(&periodic_signal);
    qurt_timer_attr_init(&attr);

    /* 每 1 毫秒触发一次 */
    qurt_timer_attr_set_duration(&attr,
        qurt_timer_convert_time_to_ticks(1000, QURT_TIME_USEC));
    qurt_timer_attr_set_signal(&attr, &periodic_signal);
    qurt_timer_attr_set_signal_mask(&attr, 0x01);
    qurt_timer_attr_set_type(&attr, QURT_TIMER_PERIODIC);

    qurt_timer_create(&periodic_timer, &attr);

    int iteration = 0;
    while (iteration < 1000) {
        qurt_signal_wait(&periodic_signal, 0x01,
                          QURT_SIGNAL_ATTR_WAIT_ANY);
        qurt_signal_clear(&periodic_signal, 0x01);

        /* 每毫秒执行一次 */
        process_audio_frame(iteration);
        iteration++;
    }

    qurt_timer_delete(periodic_timer);
    qurt_signal_destroy(&periodic_signal);
    qurt_thread_exit(QURT_EOK);
}

void timing_example(void)
{
    unsigned long long start_ticks = qurt_sysclock_get_hw_ticks();

    heavy_computation();

    unsigned long long end_ticks = qurt_sysclock_get_hw_ticks();
    unsigned long long elapsed_ticks = end_ticks - start_ticks;

    unsigned long long elapsed_us =
        qurt_timer_convert_ticks_to_time(elapsed_ticks, QURT_TIME_USEC);

    printf("计算耗时 %llu 微秒\n", elapsed_us);
}

#include <qurt.h>
#include <qurt_interrupt.h>

#define MY_SENSOR_IRQ      42
#define IRQ_SIGNAL         0x01

static qurt_signal_t irq_signal;

void sensor_isr_thread(void *arg)
{
    int irq = MY_SENSOR_IRQ;

    /* 将此线程注册为 IRQ 42 的处理程序 */
    qurt_interrupt_register(irq, &irq_signal, IRQ_SIGNAL);

    printf("传感器 ISR 线程就绪，等待中断...\n");

    while (1) {
        /* 阻塞，直到硬件中断触发 */
        unsigned int sigs = qurt_signal_wait(
            &irq_signal, IRQ_SIGNAL, QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & IRQ_SIGNAL) {
            qurt_signal_clear(&irq_signal, IRQ_SIGNAL);

QuRT 的中断服务例程（ISR）与裸机环境下的 ISR 不同。它们运行在专用的线程上下文中，这意味着你可以在其中使用互斥锁和信号量。但 ISR 线程仍应尽可能少地工作：读取硬件寄存器、将数据入队、通知处理线程并确认中断。所有开销较大的计算都应在单独的、优先级较低的处理线程中进行。

该图展示了 ISR 卸载模式。左侧的 ISR 线程以最小延迟响应硬件中断：读取传感器寄存器、将原始数据入队、通知处理线程，并确认中断以便下次触发。右侧的处理线程则以较低优先级执行耗时操作（如 FFT、滤波、机器学习推理）。

这种设计确保了即使处理线程仍在处理前一个样本，ISR 线程也能随时响应下一个硬件中断。

## 管道与消息队列

QuRT 提供了内置的管道支持，用于安全、结构化的线程间通信。管道是固定大小的消息队列，支持阻塞式的发送和接收操作。

QuRT 管道通过静态分配的缓冲区、元素数量和元素大小进行配置。与栈类似，缓冲区内存由开发者负责管理。`qurt_pipe_send()` 将消息复制进管道，若管道已满则阻塞；`qurt_pipe_receive()` 从管道复制出消息，若管道为空则阻塞。管道内部自动处理所有同步逻辑，因此无需额外的互斥锁。

管道非常适用于此处所示的传感器数据模式：读取线程以固定频率采样硬件并将消息推入管道，而处理线程从中取出消息并进行处理。管道自动提供缓冲和背压机制。

## QuRT 与 FastRPC

在真实的高通设备中，你很少会单独使用 QuRT。通常情况下，运行在 ARM CPU 上的 Android 或 Linux 应用程序会通过 **FastRPC**（快速远程过程调用）将计算密集型任务卸载到 DSP 上执行。下图展示了完整的处理流水线：

此图展示了 FastRPC 架构。在 ARM CPU 一侧，你的应用程序调用一个看似普通 C 函数的接口。实际上，FastRPC 会将参数序列化，通过处理器边界发送到 Hexagon DSP，在 QuRT 环境下执行该函数，并将结果返回。对程序员而言，这就像一次透明的远程过程调用。

### 步骤 1：定义接口（IDL 文件）

创建一个 `.idl` 文件，描述 ARM 可以在 DSP 上调用的函数：

IDL（接口定义语言）文件定义了跨处理器的 API。每个函数通过方向修饰符指定参数流向：`in` 表示数据从 ARM 流向 DSP，`rout` 表示数据从 DSP 返回给 ARM。`sequence<type>` 语法表示可变长度数组。Hexagon SDK 的 IDL 编译器会根据此定义为 ARM 侧生成桩代码（stub），为 DSP 侧生成骨架代码（skeleton）。

### 步骤 2：实现 DSP 端

DSP 实现接收由 ARM CPU 写入的输入缓冲区。在读取之前，代码使缓存失效，以确保 DSP 能从主存中获取最新数据，而不是使用过时的缓存内容。写入输出后，代码刷新缓存，以确保 ARM CPU 能看到 DSP 的结果。实际处理逻辑（本例中是一个简单的噪声门）位于缓存操作之间执行。

### 步骤 3：实现 ARM 端

if (result != 0) {
        printf("DSP 处理失败: %d\n", result);
    } else {
        printf("DSP 处理成功！\n");
        printf("前 10 个输出样本: ");
        for (int i = 0; i < 10; i++) {
            printf("%d ", output[i]);
        }
        printf("\n");
    }

    rpcmem_free(input);
    rpcmem_free(output);
    rpcmem_deinit();

    return 0;
}

cd $HEXAGON_SDK_ROOT

# 通过 make 包装器构建 ARM 目标（Android）
make V=android_Release tree=my_dsp_module

# 通过 make 包装器构建 Hexagon DSP 目标
make V=hexagon_Release_dynamic_toolv84_v66 tree=my_dsp_module

# 或者直接调用 SCons 构建两个变体
python tools/build/scons/scons.py \
    V=android_Release \
    V=hexagon_Release_dynamic_toolv84_v66 \
    my_dsp_module

# 推送到设备
adb push android_Release/ship/my_dsp_module /data/local/tmp/
adb push hexagon_Release_dynamic_toolv84_v66/ship/libmy_dsp_module_skel.so \
    /data/local/tmp/

# 运行程序
adb shell "cd /data/local/tmp && ./my_dsp_module"

/*
 * sensor_fusion.c - 在 QuRT 上实现多传感器融合流水线
 *
 * 架构：
 *   [Accel ISR] ──► [Fusion Thread] ──► [Report Thread]
 *   [Gyro ISR]  ──►       ▲
 *   [Mag ISR]   ──►       │
 *                    [Timer Thread]
 *                    (每 10ms 触发一次融合)
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <qurt.h>
#include <qurt_timer.h>

/* 配置 */
#define STACK_SIZE          8192
#define FUSION_PERIOD_US    10000   /* 10ms = 100Hz 融合频率 */
#define QUEUE_DEPTH         32

/* 数据类型 */
typedef struct {
    float x, y, z;
    unsigned long long timestamp;
} vec3_sample_t;

typedef struct {
    vec3_sample_t accel;
    vec3_sample_t gyro;
    vec3_sample_t mag;
    float roll, pitch, yaw;
} fused_state_t;

/* 线程栈 */
static char accel_stack[STACK_SIZE]  __attribute__((aligned(8)));
static char gyro_stack[STACK_SIZE]   __attribute__((aligned(8)));
static char mag_stack[STACK_SIZE]    __attribute__((aligned(8)));
static char fusion_stack[STACK_SIZE] __attribute__((aligned(8)));
static char report_stack[STACK_SIZE] __attribute__((aligned(8)));

/* 共享状态 */
static vec3_sample_t latest_accel;
static vec3_sample_t latest_gyro;
static vec3_sample_t latest_mag;
static fused_state_t latest_fused;

static qurt_mutex_t sensor_mutex;
static qurt_mutex_t fused_mutex;
static qurt_signal_t fusion_signal;
static qurt_signal_t report_signal;

#define SIG_FUSION_TICK        0x01
#define SIG_NEW_FUSED_DATA     0x01
#define SIG_SHUTDOWN           0x80

static volatile int running = 1;

/* 模拟传感器读数 */
static void read_accelerometer(vec3_sample_t *sample)
{
    sample->x = 0.01f;
    sample->y = 0.02f;
    sample->z = 9.81f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

static void read_gyroscope(vec3_sample_t *sample)
{
    sample->x = 0.001f;
    sample->y = -0.002f;
    sample->z = 0.0005f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

static void read_magnetometer(vec3_sample_t *sample)
{
    sample->x = 25.0f;
    sample->y = -5.0f;
    sample->z = 40.0f;
    sample->timestamp = qurt_sysclock_get_hw_ticks();
}

/* 加速度计线程 */
void accel_thread(void *arg)
{
    printf("[Accel] 线程已启动\n");

    while (running) {
        vec3_sample_t sample;
        read_accelerometer(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_accel = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* ~400Hz 采样率 */
        qurt_timer_sleep(2500);
    }

    printf("[Accel] 线程退出\n");
    qurt_thread_exit(QURT_EOK);
}

/* 陀螺仪线程 */
void gyro_thread(void *arg)
{
    printf("[Gyro] 线程已启动\n");

    while (running) {
        vec3_sample_t sample;
        read_gyroscope(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_gyro = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* 1kHz 采样率 */
        qurt_timer_sleep(1000);
    }

    printf("[Gyro] 线程退出\n");
    qurt_thread_exit(QURT_EOK);
}

/* 磁力计线程 */
void mag_thread(void *arg)
{
    printf("[Mag] 线程已启动\n");

    while (running) {
        vec3_sample_t sample;
        read_magnetometer(&sample);

        qurt_mutex_lock(&sensor_mutex);
        latest_mag = sample;
        qurt_mutex_unlock(&sensor_mutex);

        /* 100Hz 采样率 */
        qurt_timer_sleep(10000);
    }

    printf("[Mag] 线程退出\n");
    qurt_thread_exit(QURT_EOK);
}

/* 简化的互补滤波器 */
static void compute_orientation(
    const vec3_sample_t *accel,
    const vec3_sample_t *gyro,
    const vec3_sample_t *mag,
    fused_state_t *state)
{
    float dt = 0.01f;

    float accel_roll = atan2f(accel->y, accel->z) * 57.2958f;
    float accel_pitch = atan2f(-accel->x,
        sqrtf(accel->y * accel->y + accel->z * accel->z)) * 57.2958f;

    /* 短期信任陀螺仪，长期信任加速度计 */
    state->roll = 0.98f * (state->roll + gyro->x * dt * 57.2958f)
                + 0.02f * accel_roll;
    state->pitch = 0.98f * (state->pitch + gyro->y * dt * 57.2958f)
                 + 0.02f * accel_pitch;

    state->yaw = atan2f(mag->y, mag->x) * 57.2958f;

    state->accel = *accel;
    state->gyro = *gyro;
    state->mag = *mag;
}

/* 融合线程（每10ms运行一次） */
void fusion_thread(void *arg)
{
    qurt_timer_t fusion_timer;
    qurt_timer_attr_t timer_attr;

    printf("[Fusion] 线程已启动\n");

    qurt_timer_attr_init(&timer_attr);
    qurt_timer_attr_set_duration(&timer_attr,
        qurt_timer_convert_time_to_ticks(FUSION_PERIOD_US,
                                          QURT_TIME_USEC));
    qurt_timer_attr_set_signal(&timer_attr, &fusion_signal);
    qurt_timer_attr_set_signal_mask(&timer_attr, SIG_FUSION_TICK);
    qurt_timer_attr_set_type(&timer_attr, QURT_TIMER_PERIODIC);

    qurt_timer_create(&fusion_timer, &timer_attr);

    while (running) {
        unsigned int sigs = qurt_signal_wait(
            &fusion_signal,
            SIG_FUSION_TICK | SIG_SHUTDOWN,
            QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & SIG_SHUTDOWN) break;

        qurt_signal_clear(&fusion_signal, SIG_FUSION_TICK);

        /* 在锁保护下获取传感器数据快照 */
        vec3_sample_t a, g, m;
        qurt_mutex_lock(&sensor_mutex);
        a = latest_accel;
        g = latest_gyro;
        m = latest_mag;
        qurt_mutex_unlock(&sensor_mutex);

        /* 运行融合算法（无需锁，使用本地数据） */
        fused_state_t state;
        qurt_mutex_lock(&fused_mutex);
        state = latest_fused;
        qurt_mutex_unlock(&fused_mutex);

        compute_orientation(&a, &g, &m, &state);

        /* 发布融合结果 */
        qurt_mutex_lock(&fused_mutex);
        latest_fused = state;
        qurt_mutex_unlock(&fused_mutex);

        /* 通知上报线程 */
        qurt_signal_set(&report_signal, SIG_NEW_FUSED_DATA);
    }

    qurt_timer_delete(fusion_timer);
    printf("[Fusion] 线程退出\n");
    qurt_thread_exit(QURT_EOK);
}

/* 上报线程 */
void report_thread(void *arg)
{
    int report_count = 0;

    printf("[Report] 线程已启动\n");

    while (running) {
        unsigned int sigs = qurt_signal_wait(
            &report_signal,
            SIG_NEW_FUSED_DATA | SIG_SHUTDOWN,
            QURT_SIGNAL_ATTR_WAIT_ANY);

        if (sigs & SIG_SHUTDOWN) break;

        qurt_signal_clear(&report_signal, SIG_NEW_FUSED_DATA);

        fused_state_t state;
        qurt_mutex_lock(&fused_mutex);
        state = latest_fused;
        qurt_mutex_unlock(&fused_mutex);

        /* 每100次更新上报一次（在100Hz下为每秒一次） */
        if (++report_count % 100 == 0) {
            printf("[Report] 姿态 - 横滚: %.2f  俯仰: %.2f  "
                   "偏航: %.2f  (更新 #%d)\n",
                   state.roll, state.pitch, state.yaw, report_count);
        }
    }

    printf("[Report] 线程退出\n");
    qurt_thread_exit(QURT_EOK);
}

/* 主函数 */
int main(void)
{
    qurt_thread_t threads[5];
    qurt_thread_attr_t attr;
    int status;

    printf("=== 传感器融合流水线启动 ===\n");

    /* 初始化同步原语 */
    qurt_mutex_init(&sensor_mutex);
    qurt_mutex_init(&fused_mutex);
    qurt_signal_init(&fusion_signal);
    qurt_signal_init(&report_signal);
    memset(&latest_fused, 0, sizeof(latest_fused));

    struct {
        const char *name;
        char *stack;
        int priority;
        void (*func)(void *);
    } thread_configs[] = {
        {"accel_reader", accel_stack,  60, accel_thread},
        {"gyro_reader",  gyro_stack,   60, gyro_thread},
        {"mag_reader",   mag_stack,    70, mag_thread},
        {"fusion",       fusion_stack, 80, fusion_thread},
        {"reporter",     report_stack, 120, report_thread},
    };

    /* 创建所有线程 */
    for (int i = 0; i < 5; i++) {
        qurt_thread_attr_init(&attr);
        qurt_thread_attr_set_name(&attr, thread_configs[i].name);
        qurt_thread_attr_set_stack_addr(&attr, thread_configs[i].stack);
        qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
        qurt_thread_attr_set_priority(&attr, thread_configs[i].priority);

        int result = qurt_thread_create(&threads[i], &attr,
                                         thread_configs[i].func, NULL);
        if (result != QURT_EOK) {
            printf("创建线程 '%s' 失败: %d\n",
                   thread_configs[i].name, result);
            return -1;
        }
        printf("创建线程 '%s' (优先级 %d)\n",
               thread_configs[i].name, thread_configs[i].priority);
    }

    /* 运行10秒钟 */
    printf("流水线运行10秒钟...\n");
    qurt_timer_sleep(10000000);

    /* 关闭系统 */
    printf("正在关闭...\n");
    running = 0;
    qurt_signal_set(&fusion_signal, SIG_SHUTDOWN);
    qurt_signal_set(&report_signal, SIG_SHUTDOWN);

    /* 等待所有线程结束 */
    for (int i = 0; i < 5; i++) {
        qurt_thread_join(threads[i], &status);
    }

    /* 清理资源 */
    qurt_mutex_destroy(&sensor_mutex);
    qurt_mutex_destroy(&fused_mutex);
    qurt_signal_destroy(&fusion_signal);
    qurt_signal_destroy(&report_signal);

    printf("=== 传感器融合流水线完成 ===\n");
    return 0;
}

优先级 60：传感器读取线程（最高优先级，绝不丢失硬件数据）
优先级 80：融合引擎（每 10ms 运行一次，必须快速完成）
优先级 120：报告线程（最低优先级，仅用于日志记录）

#include <stdio.h>

void debug_example(void)
{
    printf("[%s:%d] value = %d\n", __func__, __LINE__, some_var);
}

switch (result) {
    case QURT_EOK:
        break;
    case QURT_EINVALID:
        printf("无效参数\n");
        break;
    case QURT_EFAILED:
        printf("通用失败\n");
        break;
    case QURT_EMEM:
        printf("内存不足\n");
        break;
    case QURT_ENOTALLOWED:
        printf("操作不允许（检查权限）\n");
        break;
    case QURT_ETIMEOUT:
        printf("操作超时\n");
        break;
    default:
        printf("未知错误: %d\n", result);
}

void dump_thread_info(void)
{
    qurt_thread_t tid = qurt_thread_get_id();
    char name[QURT_THREAD_ATTR_NAME_MAXLEN];

    qurt_thread_get_name(name, sizeof(name));

    printf("线程: %s (ID: %lu)\n", name, tid);
}

#define STACK_CANARY 0xDEADBEEF

static char my_stack[STACK_SIZE] __attribute__((aligned(8)));

void init_stack_canary(void)
{
    /* 在栈底写入金丝雀值 */
    ((unsigned int *)my_stack)[0] = STACK_CANARY;
    ((unsigned int *)my_stack)[1] = STACK_CANARY;
}

void check_stack_canary(void)
{
    if (((unsigned int *)my_stack)[0] != STACK_CANARY ||
        ((unsigned int *)my_stack)[1] != STACK_CANARY) {
        printf("检测到栈溢出！\n");
    }
}

# 启用指令跟踪运行
hexagon-sim --timing --pmu_statsfile stats.txt \
    --cosim_file osam.cfg \
    -- bootimg.pbn -- my_app.so

# 统计文件提供以下信息：
# - 总周期数
# - 缓存命中/未命中率
# - 停顿周期数
# - 每周期指令数（IPC）

/* 错误：线程函数返回但未退出 */
void bad_thread(void *arg) {
    do_work();
    return;  /* 崩溃或未定义行为 */
}

/* 正确 */
void good_thread(void *arg) {
    do_work();
    qurt_thread_exit(QURT_EOK);
}

/* 错误：栈位于调用线程的栈上 */
void create_thread_bad(void) {
    char stack[4096];
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_create(&tid, &attr, func, NULL);
}   /* 此处 stack 被销毁，新线程崩溃 */

/* 正确：使用静态或堆分配 */
static char stack[4096] __attribute__((aligned(8)));
void create_thread_good(void) {
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_create(&tid, &attr, func, NULL);
}

/* BAD: 手动自旋锁，无优先级继承 */
volatile int lock = 0;
while (__sync_lock_test_and_set(&lock, 1)) { /* 自旋 */ }

/* GOOD: 支持优先级继承的 QuRT 互斥锁 */
qurt_mutex_lock(&my_mutex);

/* BAD */
char stack[4096];

/* GOOD */
char stack[4096] __attribute__((aligned(8)));

/* 对于 DMA 缓冲区，通常需要 256 字节对齐 */
char dma_buffer[1024] __attribute__((aligned(256)));

/* BAD: mutex_lock 可能无限期阻塞 */
void isr_handler(void *arg) {
    qurt_mutex_lock(&some_mutex);
    qurt_mutex_unlock(&some_mutex);
}

/* GOOD: 使用非阻塞 try_lock 并设置回退机制 */
void isr_handler(void *arg) {
    if (qurt_mutex_try_lock(&some_mutex) == QURT_EOK) {
        /* 快速更新 */
        qurt_mutex_unlock(&some_mutex);
    } else {
        /* 推迟任务给处理线程 */
        qurt_signal_set(&deferred_signal, DEFERRED_WORK);
    }
}

#include <hexagon_types.h>
#include <hvx_hexagon_protos.h>

/* 一次性处理 128 字节数据 */
void vectorized_gain(int16_t *audio, int num_samples, int16_t gain)
{
    HVX_Vector *vptr = (HVX_Vector *)audio;
    HVX_Vector vgain = Q6_Vh_vsplat_R(gain);
    int num_vectors = num_samples * sizeof(int16_t) / sizeof(HVX_Vector);

    for (int i = 0; i < num_vectors; i++) {
        vptr[i] = Q6_Vh_vmpy_VhVh_sat(vptr[i], vgain);
    }
}

void lock_cache_example(void)
{
    extern float fft_twiddle_factors[];
    size_t twiddle_size = 1024 * sizeof(float);

    /* 锁定数据在 L2 中，防止被逐出 */
    qurt_mem_l2cache_lock((unsigned int)fft_twiddle_factors,
                           twiddle_size);

    /* 使用完成后解锁： */
    qurt_mem_l2cache_unlock((unsigned int)fft_twiddle_factors,
                             twiddle_size);
}

/* BAD: 在音频处理循环中调用 malloc */
void process_audio_bad(void) {
    while (1) {
        float *temp = malloc(1024 * sizeof(float));
        process(temp);
        free(temp);
    }
}

/* GOOD: 预先分配所有资源 */
static float temp_buffer[1024];
void process_audio_good(void) {
    while (1) {
        process(temp_buffer);
    }
}

┌─────────────────────────────────────────────────────────────────┐
│                    QuRT API 快速参考                              │
├─────────────────┬───────────────────────────────────────────────┤
│ 线程            │                                               │
│  创建           │ qurt_thread_create(&id, &attr, func, arg)     │
│  退出           │ qurt_thread_exit(status)                      │
│  等待结束       │ qurt_thread_join(id, &status)                 │
│  获取 ID        │ qurt_thread_get_id()                          │
│  休眠           │ qurt_timer_sleep(usec)                        │
├─────────────────┼───────────────────────────────────────────────┤
│ 互斥锁          │                                               │
│  初始化         │ qurt_mutex_init(&mutex)                       │
│  加锁           │ qurt_mutex_lock(&mutex)                       │
│  尝试加锁       │ qurt_mutex_try_lock(&mutex)                   │
│  解锁           │ qurt_mutex_unlock(&mutex)                     │
│  销毁           │ qurt_mutex_destroy(&mutex)                    │
├─────────────────┼───────────────────────────────────────────────┤
│ 信号量          │                                               │
│  初始化         │ qurt_signal_init(&signal)                     │
│  等待           │ qurt_signal_wait(&sig, mask, attr)            │
│  设置           │ qurt_signal_set(&signal, mask)                │
│  清除           │ qurt_signal_clear(&signal, mask)              │
│  销毁           │ qurt_signal_destroy(&signal)                  │
├─────────────────┼───────────────────────────────────────────────┤
│ 定时器          │                                               │
│  创建           │ qurt_timer_create(&timer, &attr)              │
│  删除           │ qurt_timer_delete(timer)                      │
│  休眠           │ qurt_timer_sleep(usec)                        │
│  时钟周期       │ qurt_sysclock_get_hw_ticks()                  │
├─────────────────┼───────────────────────────────────────────────┤
│ 内存            │                                               │
│  缓存刷新       │ qurt_mem_cache_clean(addr, sz, FLUSH)         │
│  缓存失效       │ qurt_mem_cache_clean(addr, sz, INVALIDATE)    │
│  L2 锁定        │ qurt_mem_l2cache_lock(addr, size)             │
│  L2 解锁        │ qurt_mem_l2cache_unlock(addr, size)           │
├─────────────────┼───────────────────────────────────────────────┤
│ 信号量（Semaphore）│                                           │
│  初始化         │ qurt_sem_init_val(&sem, count)                │
│  down (等待)    │ qurt_sem_down(&sem)                           │
│  up (发布)      │ qurt_sem_up(&sem)                             │
│  销毁           │ qurt_sem_destroy(&sem)                        │
├─────────────────┼───────────────────────────────────────────────┤
│ 屏障（Barrier） │                                               │
│  初始化         │ qurt_barrier_init(&barrier, count)            │
│  等待           │ qurt_barrier_wait(&barrier)                   │
│  销毁           │ qurt_barrier_destroy(&barrier)                │
└─────────────────┴───────────────────────────────────────────────┘