QuRT：你手机处理器中运行的实时操作系统——[完整使用手册]

内存管理

DSP上的内存资源是有限的。典型的Hexagon DSP拥有256 KB到2 MB的紧密耦合内存，同时还可以访问DDR内存。QuRT提供了相应的工具，可以帮助用户有效地管理这些内存资源。

内存映射结构

┌───────────────────────────────────┐  高地址段
│         DDR内存（与ARM CPU共享）     │
│   - 大型数据缓冲区                 │
│   - 神经网络权重值              │
│   - 音频/视频帧数据            │
├───────────────────────────────────┤
│         QuRT虚拟内存               │
│   - 用户堆                    │
│   - 线程栈                    │
├───────────────────────────────────┤
│         L2缓存（紧密耦合内存模式）       │
│   - 频繁访问的数据缓冲区           │
│   - 查找表                   │
├───────────────────────────────────┤
│         QuRT内核                  │
│   - 调度器、中断处理程序        │
│   - 系统数据结构              │
└───────────────────────────────────┘  低地址段

该图展示了Hexagon DSP从低地址到高地址的内存布局。QuRT内核占据最低的地址范围，用户代码无法访问这些内存。在其上方，以紧密耦合内存模式配置的L2缓存为频繁访问的数据提供了快速的存储空间。虚拟内存区域则用于存放用户堆和线程栈。最上层的是DDR内存，它与ARM CPU共享，被用来存储大型数据缓冲区、机器学习模型的权重值以及媒体帧数据。虽然DDR的内存延迟略高，但其容量要大得多。

动态内存分配

#include 
#include 

void memory_examples(void)
{
    /* 标准的malloc/free函数可以正常使用（QuRT提供了堆内存管理功能） */
    int *data = (int *)malloc(1024 * sizeof(int));
    if (!data) {
        printf("malloc失败！堆内存不足。\n");
        return;
    }

    for (int i = 0; i < 1024; i++) {
        data[i] = i * 2;
    }

    free(data);
}

QuRT提供了标准的C语言堆内存管理机制，因此malloc和free函数可以正常使用。不过，malloc的执行时间具有不确定性，因为它可能需要搜索空闲内存列表、合并相邻的空闲内存区域等。因此，这种函数并不适合用于实时系统中那些对执行时间有严格要求的场景。建议将malloc用于初始化和释放资源操作，而不要用于每帧或每个样本的数据分配。

缓存管理

在Hexagon DSP上，当与ARM CPU共享内存时，进行显式的缓存管理是非常必要的。

#include 

void cache_management_example(void)
{
    void *buffer;
    size_t buffer_size = 4096;

    /* 分配连续的、符合缓存对齐要求的内存空间 */
    int result = qurt_mem_region_create(
        &buffer,
        buffer_size,
        qurt_mem_default_pool,
        QURT_MEM_REGION_SHARED
    );

    if (result != QURT_EOK) {
        printf("内存区域分配失败\n");
        return;
    }

    /* 在读取其他处理器（例如ARM CPU）写入的数据之前： */
    qurt_mem_cache_clean(buffer, buffer_size,
                          QURT_MEM_CACHE_INVALIDATE);

    /* 从缓冲区中读取数据... */

    /* 在向其他处理器写入数据之后： */
    fill_buffer_with_results(buffer, buffer_size);
    qurt_mem_cache_clean(buffer, buffer_size,
                          QURT_MEM_CACHE_FLUSH);
}

qurt_mem_region_create()这个函数会分配一块物理上连续的内存区域，这样的内存区域适合与其他处理器共享。标志QURT_MEM_REGION_SHARED用于标记该内存区域可供跨处理器使用。

对于共享内存来说，相关的缓存规则虽然简单，但却至关重要：

1. 在读取数据之前，必须先使缓存失效，这样才能获取ARM CPU最新写入的数据，而不会看到过时的缓存内容。

2. 在写入数据之后，必须立即刷新缓存，这样ARM CPU才能看到你所做的修改，而不会使用主内存中原有的数据。

如果忽略了这些操作，虽然你的代码在逻辑上是正确的，但最终可能会因为使用过时的数据而导致错误。

用于实现可预测内存分配的内存池

内存池能够以O(1)的时间复杂度完成内存分配操作，因此它们非常适合用于实时系统中那些需要快速获取内存资源的场景。

#include 

#define BLOCK_SIZE 256
#define NUMBlocks 32

/* 内存池中的内存是静态分配的，这样可以确保分配过程的确定性 */
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 * NUMBlocks,
                          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);
}

这段代码创建了一个由32个块组成的内存池，每个块的大小为256字节。由于内存池中的内存是静态分配的，因此运行时完全不需要依赖malloc函数。

qurt_mem_pool_alloc()和qurt_mem_pool_free()这两个函数都能在常数时间内完成内存的分配与释放操作。如果内存池已经用尽，这两个函数会返回NULL，而不会导致程序阻塞或去其他地方查找内存。

这种确定的性能使得内存池成为处理音频数据、处理传感器传来的数据，以及任何需要在严格时间限制内完成的任务的理想选择。

定时器与计时功能

QuRT提供了基于硬件的定时器，能够实现精确的计时。这对于数字信号处理任务来说至关重要：例如，如果你正在以48 kHz的频率处理音频数据，那么你就需要每10.67毫秒就更新一次缓冲区，这一点绝对不能出错。

一次性定时器

#include 
#include 

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, &timerSignal);
    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(&timerSignal,
                      TIMER_EXPIRED SIGNAL,
                      QURT_SIGNAL_ATTR_WAIT_ANY);

    printf("定时器到期了！10毫秒已经过去。\n");
    qurt_signal_clear(&timerSignal, TIMER_EXPIRED.Signal);

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

这会创建一个一次性定时器，该定时器会在10毫秒后触发。这个定时器的配置是通过一个属性结构来完成的，该结构指定了定时器的持续时间、需要通知的信号对象、要设置的信号位掩码以及定时器的类型（QURT_TIMER_ONESHOT）。当定时器到期时，它会设置指定的信号位，从而唤醒那些在qurt_signal_wait()中处于等待状态的线程。在处理完相关事件后，该线程会清除这个信号位，并释放定时器资源。

周期性定时器

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);

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

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

周期性定时器使用的是QURT_TIMER_periodIC类型，而不是QURT.Timer_ONESHOT。它会按照指定的间隔反复触发。在这个示例中，程序会执行1000次循环，每次循环的间隔为1毫秒，每次循环都会处理一个音频帧。在每次循环结束后，都必须清除相应的信号位，否则下一次调用qurt_signal_wait()时会立即返回结果。

读取当前时间

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

    heavy_computation();

    unsigned long long endticks = qurt_sysclock_get_hwTicks();
    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);
}

qurt_sysclock_get_hwTicks()用于读取硬件周期计数器的值，这个计数器能够提供DSP上最高精度的计时信息。qurt_timer_convert_ticks_to_time()则可以将原始的计时数值转换为人类可读的形式（在这个例子中是微秒）。利用这种方法可以分析各个函数的执行时间，从而找出性能瓶颈所在。

中断处理

在DSP上，中断就是用来表示硬件需要立即处理的信号。QuRT提供了一种基于线程的中断处理模型，这种模型比纯硬件的中断服务程序更加结构化、更易于使用。


#include
#include

/* 重新启用中断 */
qurtInterrupt_acknowledge(irq);
}
}
}


QuRT中的中断处理程序与纯硬件层面的中断处理程序有所不同。它们是在专用的线程环境中运行的，因此可以在其中使用互斥锁和信号机制。不过，这些中断处理线程应该只执行最基本的任务：读取硬件寄存器的值、将数据放入队列中、向处理线程发送信号以及确认中断已经处理完毕。所有计算量较大的操作都应该在另一个优先级较低的线程中完成。


硬件中断 │
↓ │
中断处理线程（高优先级） 处理线程（中等优先级）
┌──────────────────┐ ┌──────────────────────────┐
│ 读取硬件寄存器值 │ │ 等待“数据已准备好”信号 │
│ 将数据放入队列 │ ──────► │ 从队列中取出数据 │
│ 向处理线程发送信号 │ │ 执行FFT运算/过滤等操作 │
│ 确认中断已处理 │ │ 将处理结果写入存储设备 │
└──────────────────┘ └──────────────────────────┘


上图展示了这种中断处理任务的分配方式。左边的中断处理线程会以最低的延迟时间来处理硬件中断：它读取传感器寄存器的值，将原始数据放入队列中，向处理线程发送信号，然后确认中断已经处理完毕，以便下次能够再次接收新的中断信号。右边的处理线程则会以较低的优先级来执行计算量较大的任务，比如FFT运算、数据过滤或机器学习模型的推理。

这种设计可以确保：即使处理线程还在处理之前的数据，中断处理线程也能够随时准备接受新的硬件中断请求。

管道与消息队列

QuRT提供了内置的管道机制，用于实现安全、结构化的数据在线程之间的传递。这些管道实际上是固定大小的消息队列，支持阻塞式的发送和接收操作。


#include
#include

process_sensor_reading(&msg);
}
}


QuRT管道配置了静态分配的缓冲区、一定数量的元素以及每个元素的长度。与栈类似，这些缓冲区的管理责任在于使用者自身。qurt_pipe_send()方法会将消息复制到管道中，如果管道已满，则会阻塞；qurt_pipe.receive()方法则会从管道中读取消息，如果管道为空，也会导致阻塞。该管道会自动处理所有的内部同步机制，因此无需额外使用互斥锁。

对于这里展示的传感器数据处理场景来说，管道是一种非常合适的解决方案：读取线程会以固定的频率采集硬件数据，并将这些数据放入管道中；而处理线程则会从管道中取出这些数据并进行后续处理。管道能够自动提供缓冲功能，并在必要时抑制数据的传输速度。

QuRT与FastRPC

在实际的高通设备中，人们很少单独使用QuRT。运行在ARM CPU上的Android或Linux应用程序会通过FastRPC（快速远程过程调用）将计算量较大的任务卸载到DSP上进行处理。下图展示了整个处理流程：

┌───────────────────────────────────────────────────────────────┐
│                         ARM CPU端                          │
│                                                               │
│   your_app.c                                                  │
│   ┌───────────────────────────────────────────────────┐       │
│   │  #include "my_dsp_module.h"  // 由工具自动生成的头文件    │       │
│   │                                                   │       │
│   │  // 这看起来像是一个普通的函数调用，       │       │
│   │ 但实际上它是在DSP上执行的！          │       │
│   │  result = my_dsp_module_process_audio(            │       │
│   │      input_buffer, output_buffer, num_samples);   │       │
│   └───────────────────┬───────────────────────────────┘       │
│                       │ FastRPC                               │
└───────────────────────┼───────────────────────────────────────┘
            （跨越处理器边界进行通信）          
┌───────────────────────┼───────────────────────────────────────┐
│                       ▼                                       │
│                  DSP端（使用QuRT）                              │
│   my_dsp_module_skel.c  // 由工具自动生成的框架代码            │
│   ┌───────────────────────────────────────────────────┐       │
│   │  int my_dsp_module_process_audio(                 │       │
│   │      const int16_t *input,                        │       │
│   │      int16_t *output,                             │       │
│   │      int num_samples)                             │       │
│   │  {                                                │       │
│   │      // 这段代码是在QuRT环境下、在Hexagon DSP上运行的   │       │
│   │      apply_noise_reduction(input, output,         │       │
│   │                             num_samples);         │       │
│   │      return 0;                                    │       │
│   │  }                                                │       │
│   └───────────────────────────────────────────────────┘       │
└───────────────────────────────────────────────────────────────┘

该图展示了FastRPC的架构。在ARM CPU端，应用程序会调用一个看起来像普通的C函数。实际上，FastRPC会先将参数序列化，然后将其传输到Hexagon DSP上，在QuRT环境下执行该函数，并最终返回结果。对于程序员来说，这种远程过程调用的体验是完全透明的。

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

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

/* my_dsp_module.idl */
#include "remote.idl"
#include "AEEStdDef.idl"

interface my_dsp_module {

    /* 简单计算操作 */
    long process_audio(
        in sequence input,
        out sequence output,
        in long num_samples
    );

    /* 矩阵乘法运算 */
    long matrix_multiply(
        in sequence mat_a,
        in sequence mat_b,
        out sequence result,
        in long rows_a,
        in long cols_a,
        in long cols_b
    );
};

IDL（接口定义语言）文件用于定义跨处理器的API。每个函数都会通过方向限定符来指定其参数类型：`in`表示数据从ARM流向DSP，`out`表示数据从DSP回流到ARM；`sequence`语法则用于表示可变长度数组。Hexagon SDK的IDL编译器会根据这些定义为ARM端生成存根代码，为DSP端生成骨架代码。

步骤2：实现DSP端代码

/* my_dsp_module_imp.c - DSP实现部分 */

#include "my_dsp_module.h"
#include 
#include 

int my_dsp_module_process_audio(
    const int16_t *input, int input_len,
    int16_t *output, int output_len,
    int num_samples
)
{
    if (!input || !output || num_samples <= 0) {
        return -1;
    }

    /* 清除缓存：ARM已经将数据写入缓存 */
    qurt_mem_cache_clean((void *)input,
                          num_samples * sizeof(int16_t),
                          QURT_MEM_CACHE_INVALIDATE);

    /* 在DSP上进行处理 */
    for (int i = 0; i < num_samples; i++) {
        /* 简单的噪声门处理 */
        if (abs(input[i]) < 100) {
            output[i] = 0;
        } else {
            output[i] = input[i];
        }
    }

    /* 刷新缓存：ARM会读取DSP处理后的结果 */
    qurt_mem_cache_clean(output,
                          num_samples * sizeof(int16_t),
                          QURT_MEM_CACHE.Flush);

    return 0;
}

DSP实现部分接收由ARM CPU写入的输入数据。在读取数据之前，代码会清除缓存，以确保DSP获取的是主内存中的最新数据而非过时的缓存内容；在输出数据后，代码会刷新缓存，以便ARM CPU能够看到DSP处理后的结果。实际的计算操作（在这个例子中是简单的噪声门处理）发生在这些缓存操作之间。

步骤3：实现ARM端代码

/* main_arm.c - ARM/Android应用程序 */

#include 
#include 
#include 
#include "my_dsp_module.h"

int main(void)
{
    int num_samples = 1024;

    /* 使用ION内存实现与DSP的无复制数据共享 */
    rpcmem_init();

    int16_t *input = (int16_t *)rpcmem_alloc(
        RPCMEM_heap_ID_SYSTEM,
        RPCMEM_DEFAULT_FLAGS,
        num_samples * sizeof(int16_t));

    int16_t *output = (int16_t *)rpcmem_alloc(
        RPCMEMHeap_ID SYSTEM,
        RPCMEM_DEFAULT_FLAGS,
        num_samples * sizeof(int16_t));

    if (!input || !output) {
        printf("rpcmem_alloc失败!\n");
        return -1;
    }

    /* 用音频数据填充输入缓冲区 */
    for (int i = 0; i < num_samples; i++) {
        input[i] = (int16_t)(i % 256);
    }

    /* 通过FastRPC将数据发送给DSP进行处理 */
    int result = my_dsp_module_process_audio(
        input, num_samples,
        output, num_samples,
        num_samples);

    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;
}

ARM端代码使用rpcmem_alloc()来分配ION内存，这种共享内存区域可以被ARM CPU和Hexagon DSP直接访问，无需进行任何数据复制。调用my_dsp_module_process_audio()时，该函数看起来像是一个普通的函数调用，但实际上FastRPC会将其透明地转发给DSP进行处理。当函数执行完成后，输出缓冲区中就会包含DSP处理后的结果。

构建完整项目

一个FastRPC项目需要进行两次SCons构建：一次针对ARM CPU端，另一次针对Hexagon DSP端。这两部分代码分别对应不同的.min文件（即android.min和hexagon.min），它们都会由SDK的SConstruct工具进行处理。

cd $HEXAGON_SDK_ROOT

# 为ARM目标平台（Android）构建代码
make V=android_Release tree=my_dsp_module

# 为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"

构建过程会生成两个结果：一个是ARM可执行文件（由你的main_arm.c代码以及相关 Stub文件编译而成），另一个是Hexagon共享库文件（即_skel.so，它是由你的DSP实现代码编译生成的）。SCons会自动处理IDL文件的编译工作：它会检测到.idl文件，自动生成相应的Stub和骨架C源代码文件，并将它们纳入对应的构建过程中。最终，这两个结果都会被推送到设备上。

当ARM可执行文件运行并调用FastRPC函数时，系统会将相应的骨架库加载到DSP上，并通过该库来路由此次调用。

构建传感器融合管道

本节将线程、同步机制、定时器以及信号整合到一个完整的、功能真实的QuRT应用程序中。该管道会从三个模拟传感器（加速度计、陀螺仪、磁力计）读取数据，利用互补滤波算法对这些数据进行融合处理，然后以100赫兹的频率输出方向信息。

/*
 * sensor_fusion.c - 在QuRT平台上实现的多传感器融合管道
 *
 * 架构如下：
 *   [加速度计中断服务程序] ──► [融合线程] ──► [报告线程]
 *   [陀螺仪中断服务程序]  ──►       ▲
 *   [磁力计中断服务程序]   ──►       │
 *                    [定时器线程]
 *                    （每10毫秒触发一次融合计算）
 */

#include 
#include 
#include 
#include 
#include 

/* 配置参数 */
#define STACK_SIZE          8192
#define FUSION_PERIOD_US    10000   /* 10毫秒相当于100赫兹的融合频率 */
#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_hwticks();
}

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

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

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

        /* 数据采样频率约为400赫兹 */
        qurt_timer_sleep(2500);
    }

    printf("[加速度计] 线程结束\n");
    qurt_thread_exit(QURT_EOK);
}

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

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

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

        /* 数据采样频率为1000赫兹 */
        qurt_timer_sleep(1000);
    }

    printf("[陀螺仪] 线程结束\n");
    qurt_thread_exit(QURT_EOK);
}

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

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

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

        /* 数据采样频率为100赫兹 */
        qurt_timer_sleep(10000);
    }

    printf("[磁力计] 线程结束\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;
}

/* 融合线程函数（每10毫秒执行一次） */
void fusion_thread(void *arg)
{
    qurt_timer_t fusion_timer;
    qurt_timer_attr_t timer_attr;

    printf("[融合线程] 线程启动\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;
        qurtmutex_lock(&fused_mutex);
        state = latest_fused;
        qurt_mutexunlock(&fused_mutex);

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

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

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

    qurt_timer_delete(fusion_timer);
    printf("[融合线程] 线程结束\n");
    qurt_thread_exit(QURT_EOK);
}

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

    printf("[报告线程] 线程启动\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;
        qurtmutex_unlock(&fused_mutex);

        /* 每100次更新时报告一次结果（即每秒报告一次） */
        if (++report_count % 100 == 0) {
            printf("[报告] 方向信息 - 旋转角度：%.2f 俯仰角：%.2f  "
                   "偏航角：%.2f  （更新次数：%d）\n",
                   state.roll, state.pitch, state.yaw, report_count);
        }
    }

    printf("[报告线程] 线程结束\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);
    qurtmutex_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},
        {"magreader",   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, threadConfigs[i].stack);
        qurt_thread_attr_set_stack_size(&attr, STACK_SIZE);
        qurt_thread_attr_set_priority(&attr, threadconfigs[i].priority);

        int result = qurt_thread_create(&threads[i], &attr,
                                         thread_configs[i].func, NULL);
        if (result != QURT_EOK) {
            printf("创建线程 '%s' 失败：%d\n",
                   threadConfigs[i].name, result);
            return -1;
        }
        printf("成功创建了线程 '%s'，优先级为 %d\n",
               thread_configs[i].name, threadconfigs[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);
    qurtmutexdestroy(&fused_mutex);
    qurt_signal_destroy(&fusion_signal);
    qurt_signal_destroy(&report_signal);

    printf("=== 传感器融合管道运行完成 ===\n");
    return 0;
}

这个示例展示了多个QuRT组件如何协同工作。

三个传感器读取线程以最高优先级运行（加速度计和陀螺仪的优先级为60，磁力计的优先级为70），它们会不断将最新的测量数据写入受互斥锁保护的共享内存中。

一个融合处理线程每隔10毫秒被触发一次，它会同时读取这三个传感器的数据，然后通过相应的算法计算出飞行器的滚转角、俯仰角和偏航角，并将最终的结果输出出来。

另一个优先级最低的线程（优先级为120）会在新的融合数据可用时接收信号，并每秒记录一次飞行器的当前方向信息。

优先级分配

优先级60：传感器读取线程（最高优先级，必须确保及时获取硬件数据）
优先级80：融合处理线程（每10毫秒运行一次，需要快速完成计算）
优先级120：日志记录线程（最低优先级，仅负责数据记录）

优先级的分配遵循一个明确的规则：与硬件交互越频繁的线程，其优先级就越高。如果融合处理线程花费的时间过长，日志记录线程会等待；这种情况是可以接受的，因为延迟记录日志并不会对系统造成实时影响。但如果传感器的数据读取出现延迟，融合算法就会使用过时的数据来进行计算。

在控制无人机或机器人的实际应用中，如果惯性测量单元提供的数据是过时的，那么计算出的方向信息就会不准确，这可能会导致设备出现故障。

调试QuRT应用程序

与Linux环境相比，QuRT的调试功能较为有限。它没有带图形用户界面的gdb工具，而且程序崩溃时产生的错误信息往往难以提供有用的线索。以下这些技巧可以组成一套实用的调试工具包。

#include 

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);
}

QURT_EINVALID通常表示传入的参数有误（例如堆栈未对齐、指针为空或优先级超出范围）。QURT_EMEM意味着内核用于存储内部数据的内存已经用完。QURT_ENOTALLOWED则往往表明硬件设备的权限设置存在问题。

线程状态检测

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);
}

这个函数可以输出当前线程的名称和ID，当多个线程同时向同一个日志文件写入数据时，这个功能非常有用，因为它可以帮助你区分哪些消息是由哪个线程产生的。

栈溢出检测

#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");
    }
}

QuRT本身并不具备检测栈溢出的功能。因此，我们需要在线程开始执行之前，在栈的底部写入一个特定的值作为“哨兵”。如果栈的大小超过了其允许的范围，这个“哨兵”值就会被覆盖。通过定期检查这个“哨兵”值（或者在线程退出时进行检查），就可以及时发现栈溢出现象；否则，这些溢出问题可能会表现为一些莫名其妙、看似无关的程序崩溃。

使用Hexagon模拟器

# 以指令追踪模式运行模拟器
hexagon-sim --timing --pmu_statsfile stats.txt \
    --cosim_file osam.cfg \
    -- bootimg.pbn -- my_app.so

# 这个统计文件会提供以下信息：
# - 总执行周期数
# - 缓存命中率/未命中率
# - 由于等待资源而导致的停滞周期数
# - 每个周期执行的指令数量

使用--timing选项可以进行精确到每个周期的模拟；而选项则会将性能计数器的数据写入文件中。统计文件会报告总执行周期数、缓存命中率和未命中率、停滞周期数，以及每个周期执行的指令数量。这些数据对于判断程序的性能瓶颈是出在计算资源上、内存资源上，还是其他方面，具有非常重要的参考价值。

常见误区

误区1：忘记退出线程

/* 错误做法：线程函数执行完毕后不调用退出函数 */
void bad_thread(void *arg) {
    do_work();
    return;  /* 这会导致程序崩溃或出现未定义行为 */
}

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

如果QuRT线程在执行完毕之后不调用qurt_thread_exit()函数来退出，就会导致程序出现未定义行为。虽然操作系统在创建线程时会将链接寄存器的值设置为qurt_thread_exit函数的位置，作为一种安全机制，但你也绝对不能依赖这种机制——必须始终明确地调用qurt_thread_exit()函数来结束线程的执行。

误区2：在错误的作用域内分配栈内存

/* 错误做法：栈内存位于调用线程的栈空间中 */
void create_thread_bad(void) {
    char stack[4096];
    qurt_thread_attr_set_stack_addr(&attr, stack);
    qurt_thread_create(&tid, &attr, func, NULL);
}   /* 这里栈内存会被释放，新创建的线程会崩溃 */

/* 正确做法：使用静态分配或堆分配 */
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);
}

栈内存的使用寿命必须长于使用它的线程的生命周期。如果将栈内存作为函数中的局部变量来分配，那么当该函数执行完毕时栈内存就会被释放，但此时线程可能仍在运行中。因此应使用静态分配（如示例所示），或者通过仔细管理内存生命周期来进行堆分配。

误区3：在不知情的情况下发生优先级反转

/* 错误做法：使用手动 spinlock，且不支持优先级继承 */
volatile int lock = 0;
while (__sync_lock_test_and_set(&lock, 1)) { /* 进行无限循环等待 */ }

/* 正确做法：使用支持优先级继承的 QuRT mutex */
qurt_mutex_lock(&mymutex);

如果一个高优先级的线程在等待一个由低优先级线程持有的手动 spinlock，而此时有一个中等优先级的线程抢先获取了该锁，那么高优先级的线程实际上就会被中等优先级的线程阻塞。

QuRT mutex 通过支持优先级继承来解决这个问题：当某个线程持有锁时，它的优先级会暂时提升为最高优先级的线程的优先级。而手动 spinlock 并不具备这种功能。

误区4：未对齐的内存

/* 错误做法 */
char stack[4096];

/* 正确做法 */
char stack[4096] __attribute__((aligned(8)));

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

线程栈内存必须满足 8 字节的对齐要求；而 DMA 缓冲区通常需要 256 字节的对齐。未对齐的内存会在 Hexagon 架构上导致硬件故障，而且这类故障产生的诊断信息非常少。

误区5：在中断服务程序中发生阻塞

/* 错误做法：使用 mutex_lock 可能会导致无限期的阻塞 */
void isr_handler(void *arg) {
    qurt_mutex_lock(&somemutex);
    qurt_mutex_unlock(&some_mutex);
}

/* 正确做法：使用非阻塞的 try_lock 方法，并在无法获取锁时将任务交给低优先级的线程处理 */
void isr_handler(void *arg) {
    if (qurt_mutex_try_lock(&some_mutex) == QURT_EOK) {
        /* 快速完成操作后释放锁 */
        qurtmutex_unlock(&some_mutex);
    } else {
        /* 将任务交给低优先级的线程处理 */
        qurt_signal_set(&deferred_signal, DEFERRED_WORK);
    }
}

虽然从技术上讲，QuRT 的中断服务程序线程可以调用阻塞型 API，但在高优先级的中断处理程序中使用这些 API会导致中断处理被无限期地阻塞，直到阻塞条件得到解决。因此应使用 qurt_mutex_try_lock() 来尝试获取锁，如果无法获取锁，则应通过信号将任务交给低优先级的线程来处理。

性能优化

使用HVX（Hexagon向量扩展技术）

#include 
#include 

/* 使用HVX一次处理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);
    }
}

HVX为Hexagon DSP提供了针对128字节数据的SIMD运算功能。Q6_Vh_vsplat_R这种内置函数可以将一个标量值广播到向量寄存器的所有通道中；Q6_Vh_vmpy_VhVh_sat则用于执行两个半字向量的饱和乘法运算。一条HVX指令可以处理64个16位样本，因此在音频和信号处理任务中，使用HVX相比使用标量代码能够显著提升运行速度。

为热门数据锁定L2缓存

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);
}

qurt_mem_l2cache_lock()这种函数可以将某个内存区域固定在L2缓存中，从而防止它被其他数据替换。这对于那些在循环中会被频繁访问的数据（比如FFT运算中使用的旋转因子数组）来说非常有用。

不过，如果将过多的数据锁定在L2缓存中，就会减少其他线程可用的缓存空间，因此请谨慎使用这种技术。

避免在热门处理路径中使用动态分配内存

/* 不好的做法：在音频处理循环中使用malloc */
void process_audio_bad(void) {
    while (1) {
        float *temp = malloc(1024 * sizeof(float));
        process(temp);
        free(temp);
    }
}

/* 好的做法：提前分配所有所需内存 */
static float temp_buffer[1024];
void process_audio_good(void) {
    while (1) {
        process(temp_buffer);
    }
}

malloc和free这些函数的执行时间具有不确定性，因为它们可能需要遍历空闲内存列表、合并或拆分内存块，而在最坏的情况下，甚至需要向操作系统申请更多内存。

在以48 kHz频率运行的实时音频处理循环中，一次缓慢的内存分配操作就可能导致音频出现异常。因此，建议在程序初始化时提前分配所有所需缓冲区，并重复使用这些缓冲区。

API快速参考

┌─────────────────────────────────────────────────────────────────┐
│                    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)           │
├─────────────────┼───────────────────────────────────────────────┤
│ 信号量           │                                               │
│  初始化          │ qurt_sem_init_val(&sem, count)                │
● 减少信号量值     │ qurt-sem_down(&sem)                           │
● 增加信号量值     │ qurt_sem_up(&sem)                             │
● 删除信号量        │ qurt_sem_destroy(&sem)                        │
├─────────────────┼───────────────────────────────────────────────┤
│ 障碍物           │                                               │
│  初始化          │ qurt_barrier_init(&barrier, count)            │
● 等待障碍物       │ qurtBarrier_wait(&barrier)                   │
● 删除障碍物        │ qurt_barrier_destroy(&barrier)                │
└─────────────────┴───────────────────────────────────────────────┘

此表格按类别列出了最常用的QuRT API函数。左列标明了相应的操作类型，右列则显示了这些函数的函数签名。

• 线程相关操作包括创建、终止、加入线程以及让线程进入睡眠状态。

• 互斥锁相关操作提供了锁定、尝试锁定以及解锁功能。

• 信号相关操作支持基于位掩码的通知机制，用于实现等待、设置和清除信号等功能。定时器相关操作则包括创建、删除定时器、让定时器进入睡眠状态，以及读取硬件计时器的数值。

• 内存相关操作涉及缓存清空与失效处理（这对于跨处理器之间的数据交换尤为重要），同时也包括对那些对性能要求极高的数据的L2缓存进行锁定操作。

• 信号量与屏障机制进一步完善了同步原语的功能。

后续步骤

本手册介绍了QuRT编程的基础知识，包括线程管理、同步机制、内存操作、定时器使用、中断处理、管道通信、FastRPC技术以及多传感器数据融合流程。接下来，您可以通过一系列循序渐进的学习步骤来深入掌握这些内容。

首先，请下载Hexagon SDK，并在模拟器上运行其中包含的示例项目。位于$HEXAGON_SDK_ROOT/examples/目录下的示例代码通过FastRPC展示了真实的ARM-DSP通信流程，这些示例是了解完整、可运行的项目功能的最佳途径。

请阅读位于$HEXAGON_SDK_ROOT/docs/目录中的QuRT用户指南。该指南详细介绍了本文中提到的所有API函数，同时还涵盖了许多其他未在文中提及的功能（例如QuRT的TLB管理机制和电源管理接口）。

尝试使用Hexagon提供的向量扩展技术HVX进行编程练习。HVX正是Hexagon DSP发挥其高性能的关键所在，学习如何编写向量化DSP代码将是提升系统性能的重要手段。

最后，请准备一块开发板（例如Qualcomm RB5），并在真实的硬件平台上运行您的代码。虽然模拟器可以验证代码的正确性，但只有在实际硬件环境下才能真正了解代码的执行时间、缓存效果，以及它与其他在DSP上运行的软件之间的交互情况。

推荐阅读资料

Hexagon SDK的相关文档位于\(HEXAGON_SDK_ROOT/docs/目录下。QuRT API的参考资料则位于\)HEXAGON_SDK_ROOT/docs/qurt/目录中。Qualcomm开发者网站developer.qualcomm.com提供了更多的资源、论坛和应用说明。而Hexagon DSP架构参考手册则是了解该硬件平台的权威指南。

QuRT是一套功能强大的工具。它不会手把手地指导您使用，但它能让您以微秒级精度控制世界上最先进的DSP架构之一的实时处理能力。虽然学习曲线较为陡峭，但一旦掌握了这些知识，你就会明白为什么会有数十亿设备愿意将它们最关键的任务交给这个小巧的操作系统来处理。