libqcperf - Qualcomm Dragonwing Documentation

libqcperf 是一个开源 C 库，用于在 Qualcomm 平台上进行实时硬件性能监控。它提供统一的 API，将调用分发到可插拔的后端，每个后端针对特定的硬件子系统。数据在后台线程上异步采集，并以可配置的流式速率通过注册的回调传递给您的应用程序。源代码和问题跟踪器：github.com/qualcomm/libqcperf

后端

每个后端针对特定的子系统和平台。您可以在构建时选择要编译进来的后端。

后端	平台	关键指标
`DUMMY`	全部	跨两种能力的合成指标——适合在没有硬件的情况下进行集成测试
`CPU`	Linux ARM64	每核及总体 CPU 负载（%）、频率（MHz）、有效利用率（%）、DCVS 频率限制
`NPU`	Linux ARM64	DSP/NPU Q6 利用率（%）、Q6 时钟（KHz）、HVX 利用率（%）、HMX 利用率（%）
`POWER`	Windows ARM64	CPU、GPU 和系统组件的功耗（mW）
`THERMAL`	Windows ARM64	22 个热区（包括 CPU 集群和 GPU）的温度（°C）

构建

Linux ARM64（交叉编译）

安装前提条件

为您的主机下载 ARM GNU Toolchain 并设置路径：

export AARCH64_TOOLCHAIN_PATH=/path/to/arm-gnu-toolchain

使用 CMake 配置

cmake -S qcperf -B build \
    -DTARGET_ARCH=linux-aarch64 \
    -DCMAKE_BUILD_TYPE=Release \
    -DProjectVersion="0.1.0.0" \
    -DBACKENDS="CPU;NPU;DUMMY" \
    -DBUILD_SHARED=OFF

关键标志：

标志	取值	描述
`-DTARGET_ARCH`	`linux-aarch64`	选择交叉编译工具链
`-DCMAKE_BUILD_TYPE`	`Release` / `Debug`	优化构建或带调试符号
`-DProjectVersion`	`"0.1.0.0"`	嵌入库中的版本字符串
`-DBACKENDS`	`"CPU;NPU;DUMMY"`	以分号分隔的要编译的后端列表；省略则启用平台支持的所有后端
`-DBUILD_SHARED`	`OFF` / `ON`	静态 `.a` 或共享 `.so`

构建

cmake --build build

输出位于构建目录根部：libQcPerfCore.a（静态）或 libQcPerfCore.so（共享），以及 QcPerfCoreTest 可执行文件。

CMake 预设

编辑 qcperf/CMakeUserPresets.json，一次性设置 AARCH64_TOOLCHAIN_PATH 和 ProjectVersion，然后使用命名预设：

cd qcperf
cmake --preset linux-aarch64-release
cmake --build --preset linux-aarch64-release

可用预设：linux-aarch64-debug、linux-aarch64-release、linux-aarch64-debug-shared、linux-aarch64-release-shared。

Windows ARM64

git submodule update --init --recursive
cmake -B build -G "Visual Studio 17 2022" -A ARM64 -DProjectVersion="0.1.0.0"
cmake --build build --config Release

API 概览

所有函数都返回 QcPerfReturnCode。请包含 qcperf.h 和 qcperf_common.h。

函数	描述
`qcperf_init()`	初始化库。必须首先调用。
`qcperf_version(info)`	获取库版本（build.major.minor.patch）。
`qcperf_connect_backend(id, msg_cb)`	连接到后端，并可选地注册消息回调。
`qcperf_get_capabilities_info(id, info)`	查询已连接后端的能力、指标和支持的速率。
`qcperf_set_data_callback(id, data_cb)`	注册在每个流式传输间隔被调用的数据回调。
`qcperf_start(id, request)`	以给定的采样和流式传输速率开始监控某项能力。
`qcperf_stop(id, request)`	停止活动的监控会话。
`qcperf_disconnect_backend(id)`	断开与后端的连接并释放其资源。
`qcperf_deinit()`	反初始化库并释放所有资源。
`qcperf_get_error_info(code, info)`	将返回码转换为人类可读的字符串。

测试应用程序

构建会生成 QcPerfCoreTest，这是一个演练完整库生命周期的单文件 C 程序。它是标准的用法示例。

运行测试应用程序

./QcPerfCoreTest <backend_id> <sampling_rate_ms> <streaming_rate_ms> <verbose_mode>

参数	描述
`backend_id`	整数后端标识符（0 = DUMMY，1 = CPU，2 = NPU，3 = POWER，4 = THERMAL）
`sampling_rate_ms`	硬件采样间隔（毫秒）；传入 `0` 使用后端支持的第一个速率
`streaming_rate_ms`	回调传递间隔（毫秒）；传入 `0` 使用后端支持的第一个速率
`verbose_mode`	`0` = 仅打印指标 ID 和值；任何其他值 = 同时打印指标名称、单位和描述

示例：

# Dummy backend, verbose output, 100 ms sampling, 500 ms streaming
./QcPerfCoreTest 0 100 500 1

# CPU backend, basic output, backend default rates
./QcPerfCoreTest 1 0 0 0

生命周期

测试应用程序演练完整的 API 调用序列：

初始化

qcperf_init();

连接到后端

qcperf_connect_backend(backend_id, &message_callback);

发现能力

qcperf_get_capabilities_info(backend_id, backend_info);

注册数据回调

qcperf_set_data_callback(backend_id, &result_callback);

启动、采集、停止——对每项能力执行

qcperf_start(backend_id, &request);
sleep(10);
qcperf_stop(backend_id, &request);

断开连接并反初始化

qcperf_disconnect_backend(backend_id);
qcperf_deinit();

回调实现

消息回调接收后端日志消息，并带上严重级别前缀打印，同时抑制调试级别的输出：

enum QcPerfReturnCode message_callback(struct QcPerfMessage *message) {
    if (message->message_level != QC_PERF_MESSAGE_LEVEL_DEBUG) {
        printf("[%s] Backend message: %s\n", level_str, message->message);
    }
    return QC_PERF_RETURN_CODE_SUCCESS;
}

数据回调在每个流式传输间隔被调用。在详细模式下，它从预先复制的 QcPerfBackendInfo 中查找指标名称、单位和描述；在基本模式下，它打印指标 ID 和原始值：

enum QcPerfReturnCode result_callback(struct QcPerfData *data) {
    printf("[DATA] Capability ID: %d, Metrics count: %d\n",
           data->capabilityId, data->metric_response_len);

    for (uint32_t i = 0; i < data->metric_response_len; i++) {
        if (g_is_verbose_print && metric_found) {
            // verbose: name, value, unit, description
            printf("  [%llu] %s: ", timestamp, metric_name);
            print_metric_value(&data->metric_response[i].metric_value);
            printf(" %s (%s)\n", metric_unit, metric_desc);
        } else {
            // basic: metric ID and value only
            printf("  [%llu] Metric ID %d: ", timestamp,
                   data->metric_response[i].metric_id);
            print_metric_value(&data->metric_response[i].metric_value);
            printf("\n");
        }
    }
    return QC_PERF_RETURN_CODE_SUCCESS;
}

数据回调运行在库的内部后台线程上。测试应用程序在启动任何监控会话之前会深拷贝 QcPerfBackendInfo，以便回调在无需持有锁的情况下安全读取指标元数据。

资源

GitHub 上的源代码

​后端

​构建

​Linux ARM64（交叉编译）

​CMake 预设

​Windows ARM64

​API 概览

​测试应用程序

​运行测试应用程序

​生命周期

​回调实现

​资源

后端

构建

Linux ARM64（交叉编译）

CMake 预设

Windows ARM64

API 概览

测试应用程序

运行测试应用程序

生命周期

回调实现

资源