交付 Native Hook 符号化与 Hypium 采集

[qiqingzhixin]

变更

• 增加 get_symbols 批量符号化接口，支持源码位置、内联链、demangle、缺失 SO 汇总和显式 SO 名称映射。
• 增加调用方持有的进程内 SymbolResolver，延迟建立并复用 SO 路径索引、模块命中/缺失缓存和 Symbolizer；保留原 get_symbols 兼容函数。
• 增加 kat-native-hook-symbolize CLI，从 trace_streamer SQLite 导出 Excel，并输出 missing_modules 工作表。
• 增加 Hypium ohosTest 计算器穿刺及 Python Native Hook 采集编排，不依赖 hmdriver2。
• 支持普通文件 symlink 作为 ELF 候选，目录 symlink/junction 仍不跟随。

如何采集 Native Hook trace

前置条件：

• hdc 和 trace_streamer_windows.exe 可执行，或通过参数显式指定路径。
• 设备上已存在 ohos.samples.distributedcalc。
• 当前 Hypium 方案需预先安装签名后的测试宿主 HAP 和 ohosTest HAP；脚本不会自动构建、签名或安装 HAP。
• 未指定 --target 时必须恰好有一台 Connected 设备。

执行 30 秒采集：

py tools/native_hook_capture.py --duration 30

多设备或工具不在 PATH 时：

py tools/native_hook_capture.py `
  --duration 30 `
  --target <device-serial> `
  --hdc D:/sdk/toolchains/hdc.exe `
  --trace-streamer D:/tools/trace_streamer_windows.exe

脚本在 profiler 就绪后执行 Hypium 用例，启动 ohos.samples.distributedcalc，完成 100 * 100 = 10000，随后拉取 trace 并调用 trace_streamer。成功产物位于：

target/trace/YYYYMMDD-HHMMSS/
├── native_heap.htrace
├── trace.db
├── hiprofiler.log
├── hypium.log
└── trace-streamer.log

只有 Hypium/UI 异常时才尽力增加 failure.png。

如何把符号转换到 Excel

准备 trace_streamer 生成的 trace.db，以及包含未裁剪 ELF/DWARF 文件的符号根目录：

cargo run -p kat-rs-native-hook-symbolize-poc `
  --release `
  --bin kat-native-hook-symbolize -- `
  target/trace/YYYYMMDD-HHMMSS/trace.db `
  --symbol-dir D:/zxlDown/images/laster `
  --output target/trace/YYYYMMDD-HHMMSS/symbols.xlsx

需要完整源码路径、行号和内联函数链时增加：

--include-source-location

trace 中的 SO 名称与符号目录中的文件名不一致时，可以重复配置映射。方向固定为“trace 名称或路径 → 符号目录名称或路径”：

--module-map /system/lib/ld-musl-arm.so.1=libc.so `
--module-map libtrace.so=libsymbols.so

完整示例：

cargo run -p kat-rs-native-hook-symbolize-poc `
  --release `
  --bin kat-native-hook-symbolize -- `
  target/trace/YYYYMMDD-HHMMSS/trace.db `
  --symbol-dir D:/zxlDown/images/laster `
  --output target/trace/YYYYMMDD-HHMMSS/symbols.xlsx `
  --module-map /system/lib/ld-musl-arm.so.1=libc.so `
  --include-source-location

工作簿包含：

• symbols：callchain_id、depth、original_symbol、resolved_symbol。
• missing_modules：本地没有匹配 ELF 的 module_path 和 occurrence_count。SO 已找到但单个地址没有符号时不进入该表。

如何调用核心代码 get_symbols

输入地址格式固定为 MODULE+0xHEX，地址按 ELF 模块相对虚拟地址解释：

use std::{collections::HashMap, path::Path};

use kat_rs_native_hook_symbolize_poc::get_symbols;

fn example() -> anyhow::Result<()> {
    let addresses = vec![
        "/system/lib/ndk/libffrt.so+0x74825".to_owned(),
        "/system/lib/ld-musl-arm.so.1+0x1234".to_owned(),
    ];
    let module_name_map = HashMap::from([(
        "/system/lib/ld-musl-arm.so.1".to_owned(),
        "libc.so".to_owned(),
    )]);

    let result = get_symbols(
        &addresses,
        Path::new("D:/zxlDown/images/laster"),
        &module_name_map,
        true,
    )?;

    for symbol in result.symbols {
        println!("{symbol}");
    }
    for missing in result.missing_modules {
        eprintln!("missing {} x{}", missing.module_path, missing.occurrence_count);
    }
    Ok(())
}

参数含义：

• addr_list：待解析地址列表；返回的 symbols 与其等长且顺序一致。
• symbol_dir：显式传入的本地符号根目录；存在合法输入时目录不存在会报错。
• module_name_map：可为空；完整路径键优先于 basename 键。
• include_source_location：true 时输出完整源码路径、行号和内联链；false 时仅输出基本函数符号。

无法解析的输入、找不到模块或地址没有符号时，symbols 对应位置保留原始字符串。找不到 ELF 的合法 SO 同时汇总到 missing_modules。

连续处理多批地址时应复用 SymbolResolver，否则兼容函数每次都会重新扫描符号目录：

use std::collections::HashMap;

use kat_rs_native_hook_symbolize_poc::SymbolResolver;

fn batches(first_batch: &[String], second_batch: &[String]) -> anyhow::Result<()> {
    let mut resolver = SymbolResolver::new("D:/zxlDown/images/laster");
    let module_name_map = HashMap::new();

    let first = resolver.get_symbols(first_batch, &module_name_map, false)?;
    let second = resolver.get_symbols(second_batch, &module_name_map, false)?;
    println!("{} {}", first.symbols.len(), second.symbols.len());
    Ok(())
}

索引在首次合法查询时建立一次。实例生命周期内符号目录视为稳定；目录内容变化后创建新实例。空输入或全部不合法的输入不会扫描目录。

get_symbols 性能

测试环境使用 D:/zxlDown/images/laster（23.37 GB、3171 个 SO）和约 29.9 秒的真实 target/trace/test.db。60 秒、120 秒没有独立真机 trace，分别按真实帧序列原顺序重复 2 倍、4 倍构造等效规模，因此只用于评估方法的扩展性能。

等效 trace	总输入	合法地址	每次新建实例中位耗时	复用实例中位耗时	提升	峰值工作集
30s（真实）	282982	158798	2593 ms	395 ms	6.6×	1137 MiB
60s（2×）	565964	317596	3887 ms	1065 ms	3.6×	1255 MiB
120s（4×）	1131928	635192	5981 ms	2509 ms	2.4×	1490 MiB

每档复用数据取 5 次调用的中位数；兼容函数取 3 次中位数，include_source_location=false。首次调用仍需建立目录索引并加载 ELF，三档分别约 2705 ms、2754 ms、4979 ms。工作集主要由大型未裁剪 ELF/DWARF 和百万级输入/输出字符串占用，SO 路径索引仅保存 3171 条路径。

验证

• cargo fmt --all -- --check
• cargo test -p kat-rs-native-hook-symbolize-poc：14 passed
• cargo clippy -p kat-rs-native-hook-symbolize-poc --all-targets -- -D warnings
• py -m py_compile tools/native_hook_capture.py tools/test_native_hook_capture.py
• py -m unittest tools/test_native_hook_capture.py：10 passed
• Hypium 主 HAP 与测试 HAP 使用 --no-daemon --no-parallel 构建成功。
• 真实 trace 共 2675 帧：1398 帧解析成功且包含源码位置，367 帧包含内联链；映射 /system/lib/ld-musl-arm.so.1=libc.so 后缺失 SO 为 0。
• 已有 API 26 真机 Hypium 结果：Tests run: 1, Failure: 0, Error: 0, Pass: 1。

待补证据

• 设计要求的 30 秒真机采集尚待补跑：原验证设备 7001005458323933328a521c3c503800 当前 Offline；当前在线设备未安装按其 UDID 签名的 Hypium 主/测试 HAP。因此先以 Draft 提交，补齐签名设备验证后转 Ready。

Closes #152

[qiqingzhixin]

该混合 PR 已按 review 边界拆分为两个独立 Draft PR：

• feat: 增加 Native Hook 应用 Trace 采集 #166：Hypium 计算器穿刺与 Native Hook Trace 采集。
• feat: 增加 Native Hook 符号化与 Excel 导出 #167：Rust 符号化、SymbolResolver 和 SQLite 到 Excel 导出。

两个新 PR 均基于最新 main，分别包含独立 SDD 和验证证据，test 与 pr-guard 已通过。后续 review 请在对应 PR 继续。