在 鸿蒙NEXT 零售机上,App 沙箱内 一切 execve 都被 SELinux 禁止(libs 目录、files 目录、
memfd + /proc/self/fd 全部实测 EACCES)。本工程采用与 Termony 同源的内存 ELF loader
方案:fork 子进程后在进程内把目标 ELF 读入匿名内存、用 HarmonyOS 特有的 jit prctl
放开匿名页可执行权限(debug 签名应用可用)、直接跳转入口 —— 完全不经过 execve。
已在零售版真机(非 root)验证:参数传递、stdout/stderr 捕获、退出码透传全部正常。
PC: hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "hello foo bar"
│
▼
EntryAbility (onCreate/onNewWant 解析 want.parameters.cmd)
│
▼
napi_init.cpp: runBin → fork 子进程
│ execv(libhello.so) ← 零售机必然 EACCES
│ ↓ 失败回退
│ memfd_create + 顺序复制 ELF ← 关键:bundle libs 目录的文件
│ │ 随机读(lseek+read)会拿到坏数据,
│ │ 必须先顺序读进 memfd(实测坑)
│ ↓
│ z_entry(伪造初始栈) ← app/third_party/elf(MikhailProg/elf,
│ │ mmap 匿名页 ← 读 ELF 段 已打 jit prctl 补丁 + "@fd" 直传补丁)
│ │ prctl(0x6a6974) + mprotect PROT_EXEC ← debug 应用专属 jit 开关
│ │ 修正 auxv (AT_PHDR/AT_ENTRY/...)
│ ↓
│ z_trampo 跳转到目标入口 ← 目标二进制开始运行
▼
父进程 poll 捕获 stdout/stderr,超时 SIGKILL
│
▼
hilog (tag=BinRunner, 900 字符分段防截断) → PC: hdc shell hilog | grep BinRunner
方案 A — DevEco Studio(推荐,含签名 + 全套工具链):
从 HarmonyOS 开发者官网 下载安装。
默认路径 /Applications/DevEco-Studio.app,自带 hdc / hvigor / ohpm / OHOS NDK。
方案 B — 仅 Command Line Tools(不需要 IDE,仅 CLI 操作):
从 HarmonyOS SDK 下载页 获取 Command Line Tools 压缩包,解压后配置环境变量:
# 以 macOS 为例,Linux/Windows 路径略有不同
export DEVECO_SDK_HOME="$HOME/harmonyos/sdk"
export PATH="$DEVECO_SDK_HOME/default/openharmony/toolchains:$DEVECO_SDK_HOME/default/openharmony/toolchains/hdc:$PATH"验证:
hdc version # 设备连接工具
which ohpm # 包管理器
which hvigorw # 构建工具注意:仅 CLI 使用时只需要 hdc(
br push/run/ls/logs均通过 hdc 通信)。 如需构建安装 HAP,还需要 ohpm + hvigorw + OHOS NDK(或直接用 DevEco Studio)。
DevEco Studio 打开工程,File → Project Structure → Signing Configs → 自动签名。 必须是 debug 签名(jit prctl 只对 debug 应用开放)。
debug 签名 profile(.p7b)里内嵌了允许安装的设备 UDID 白名单:只有登记过的
手机才能安装本 HAP。DevEco 自动签名会把当前连接的设备 UDID 自动登记进 profile,
所以换新手机后必须重新自动签名 + 重新构建,详见
docs/device-onboarding.md。
仅 CLI 使用(不重新构建 App)时无需自己签名 —— 直接安装预编译的
binrunner/data/binrunner.hap即可;但它同样受 profile 白名单限制, 只能装在与构建时同一批 UDID 已登记的设备上。
签名配置不入库:
app/build-profile.json5的signingConfigs含本机材料路径与 账号相关口令,仓库里只保留空数组,构建时注入:
- DevEco Studio 自动签名会就地改写该文件 —— 那是你本机的配置,别提交;
- 命令行用
./build.sh:优先采用.build/build-profile.local.json5(已 gitignore, 首次可从 DevEco 改写后的app/build-profile.json5复制一份存档),没有该文件时用.build/keystore的自签材料(p7b 为空,HAP 不可安装),构建结束自动还原受控文件;- CI/发布用 GitHub Secrets + hap-sign-tool 签名,不读本机配置。
# DevEco Studio 用户
export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains:$PATH"
export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
# Command Line Tools 用户(路径按实际安装位置调整)
# export DEVECO_SDK_HOME="$HOME/harmonyos/sdk"
# export PATH="$DEVECO_SDK_HOME/default/openharmony/toolchains:$DEVECO_SDK_HOME/default/openharmony/toolchains/hdc:$PATH"
ohpm install --all
hvigorw assembleApp --mode project -p product=default -p buildMode=debug --no-daemon
hdc install app/entry/build/default/outputs/default/entry-default-signed.hapApp 版本与 Python 包版本联动:HAP 的
versionName/versionCode取自binrunner/__init__.py的__version__(同一处也是 wheel 版本号唯一来源)。build.sh构建 HAP 前自动同步;手动构建时执行python3 scripts/sync_app_version.py。versionCode按major*1_000_000 + minor*1_000 + patch映射(1.0.0 → 1000000), 单调递增保证已安装设备可覆盖升级。
hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "hello foo bar"
hdc shell hilog | grep BinRunner注意:本机 aa 用 --ps 传字符串参数(不是 --es,不同系统版本参数名不同,报错时看 aa start -h)。
规则:cmd 第一个词是二进制名或绝对路径,其余为参数。
路径约定:@ 展开为 App 沙箱 files 根目录(/data/storage/el2/base/haps/entry/files,
仿 shell tilde 语义但用 @,避免 host shell 抢先展开:词首或 --opt=@/x 等号后生效,
@foo 和参数中间的 @ 不展开);run/ls 等所有命令统一生效。
二进制名解析顺序:绝对路径直通 → 推送目录 @/bin/<名> → libs 目录 lib<名>.so。
/data/local/tmp 对 App 不可见(SELinux 隐藏为 ENOENT)、hdc file send 进不了
App 沙箱(shell uid 无权限)——两条直推路径在零售机上均实测不可行。可用通道是
App 内置的 TCP 推送 server(PushServer.ets,
App 启动即监听 :8888),配合 hdc fport 把文件写入 filesDir/bin/。
binrunner 把转发管理、推送、触发执行、日志收集封装成 一条命令(零依赖,hdc 不在 PATH 时自动找 DevEco 默认路径):
alias br="python3 binrunner" # 简短别名,推荐
br devices # 列出设备(多台时 -t UDID 指定)
br push ./benchmark # 推送二进制(自动建立 fport,幂等)
br push ./libmindspore-lite.so # 动态依赖库推进同一目录
br push ./mylibs/ # 递归推送目录(保持子目录结构)
br run "benchmark --modelFile=@/mobilenetv2.ms --loopCount=5"
br run --timeout 1800 "benchmark --modelFile=@/mobilenetv2.ms --loopCount=1000"
# → stdout/stderr 直接打印到本地终端,二进制退出码透传为 CLI 退出码
br ls # 列出 files 根目录(bin/ 子目录是推送区;加路径可列任意目录)
br rm "old-binary" # 删除已推送的文件或目录(递归)
br pull "hello" # 从设备拉取文件到本地
br logs # 持续跟踪设备日志br run --timeout 设置设备端执行期限(默认 60 秒,范围 1–2147483647 整数秒);
主机从启动请求返回后最多等待该期限加 30 秒,用于启动、调度和报告回传。
例如 --timeout 1800 允许设备执行 1800 秒,主机等待上限为 1830 秒。
报告包含实际执行期限,如 exit=-1 timedOut=true timeoutSec=1800。
主机等待报告超时只表示未收到完整报告。v1.4.1 起 CLI 会先探测设备是否已结束:能确定时直接报
「输出数据不完整(收到连续 X/Y 块):设备已结束,缺失部分无法通过 hilog 补齐」,
不确定时才提示设备状态未知。
此修复需要同时更新 CLI 和设备 HAP;仅更新 CLI 时,旧 v1.2.0 HAP 仍会在 30 秒终止任务。
从源码构建后请安装新 HAP(使用打包的 CLI 时执行 br setup --reinstall)。
直接使用 aa start 时可加 --ps timeout_sec 1800;未传入时(包括页面执行)保留 30 秒默认值。
持久化(追加到 ~/.zshrc 或 ~/.bashrc):
echo 'alias br="python3 '"$(pwd)"'/binrunner"' >> ~/.zshrc@统一展开为沙箱 files 根目录(run/ls均生效);命令名给绝对路径也可直接执行, 如br run "@/bin/hello a b"- 名字解析顺序:绝对路径直通 →
@/bin/<name>(推送目录优先) → libs 目录lib<name>.so - 推送支持子目录(PushServer 自动创建父目录),目录推送示例:
用
br push ./mylibs/ # 保持子目录结构,如 mylibs/sub/dep.so → bin/sub/dep.sobr ls "@/bin"查看已推送的文件树。 - 注意:
LD_LIBRARY_PATH仅含filesDir/bin/根目录(不递归搜索子目录),.so 依赖 请直接放在根层级;子目录适合放数据文件(模型、配置等) - 推送目录的文件是普通文件,没有 bundle libs 目录的随机读坏数据问题;loader 同样先过 memfd
- 数据文件也可通过子目录组织:
@/bin/models/xxx.ms、@/bin/configs/yy.json - 断点续传:≥4MiB 的文件中断后重跑同一条
br push会自动续传,只发剩余部分 (靠头部 4KiB 探针确认同一文件;传输期间用.part临时名,收满才改成正式名, 所以正式文件名不会指向半成品)。已实测 32MiB 传到 69% 强杀后续传,哈希与源文件一致。 - 长传保活:
br push期间自动点亮屏幕 + 巡检 fport 隧道,熄屏挂起 / 隧道被回收 导致的中断会自动自愈续传(详见 §7.2 与 docs/transfer-spec.md §传输可靠性) - 不想用 CLI 时等价的手工步骤:
hdc fport tcp:8888 tcp:8888+python3 binrunner push <file或目录>+aa start --ps cmd ...+hilog | grep BinRunner
已实测:推送静态 hello 执行 exit=42 正常;推送 benchmark + libmindspore-lite.so 免打包 完成 MobileNetV2 推理(AvgRunTime ≈35ms,与打包版一致);CLI 推送/执行/日志重组/退出码 透传全部验证通过。
BinRunner 支持多个终端同时 br run,各次执行互不干扰:
终端1: br run "hello" ──→ 子进程 456
终端2: br run "benchmark ..." ──→ 子进程 789
终端3: br push ./data/ ──→ PushServer TCP 连接
每个 br run 生成唯一 8 位 run_id(如 a1b2c3d4),所有 hilog 输出
带 [a1b2c3d4] 前缀,CLI 只认自己的 ID,输出互不混杂。
PushServer(TCP :8888)天然支持多连接并发。
- 进程隔离:每条
br run独立 fork 子进程,各自运行目标二进制,互不影响 - 流式输出:新版 CLI 与 App 配合使用时,
br run在任务执行期间持续显示 stdout/stderr, 分别写入 Host 的标准输出/标准错误并立即刷新;启动后按 0.5 秒间隔轮询(另加 hdc 耗时), 轮询只读本 App tag 下本次执行的行(hilog -x -T BinRunner -e '\[run_id\]'), 设备整体日志量和历史执行都不会拖慢本轮。 结束时仅在 stderr 打印退出状态,不重复打印日志。目标程序需主动刷新自身缓冲区 (例如 C 的fflush(stdout)或 Python 的-u);BinRunner 无法读取尚未写入管道的数据。 旧版 App 仍使用执行结束后的完整报告。协议与限制见 CLI 文档。 - 输出隔离:自动生成的 run_id 标记所有日志行,CLI 自动过滤
- Push 并发:多个
br push可同时进行,同名文件后写覆盖 - 详见 docs/concurrency-spec.md
# 静态(最简单):OHOS NDK 交叉编译时加 -static,参考 examples/hello/build.sh
# 动态(已实测 mindspore benchmark):二进制和它的 .so 依赖一起放进 libs 目录- 目标二进制重命名为
lib<名字>.so放入app/entry/libs/arm64-v8a/ - 动态二进制的依赖库(如
libmindspore-lite.so)放入同一目录;子进程已自动设置LD_LIBRARY_PATH指向该目录,musl ld.so 会沿它解析 NEEDED 依赖 - 动态链接器
/lib/ld-musl-aarch64.so.1由 loader 自动加载(App 可读系统 ld-musl,已实测) - 重新打包安装即可
/data/local/tmp App 读不到(SELinux),数据文件三条路。
放 app/entry/src/main/resources/rawfile/,App 启动时自动释放到 filesDir,
cmd 里用 @/xxx 引用。
br push model.ms,用 @/bin/model.ms 引用。
单文件上限 4GiB(策略护栏,双端常量一致;决策见 ADR-0001),
设备剩余空间不足会在写盘中报错并清理 .part。
⚠️ 已知坑:屏幕熄灭后 App 进后台,PushServer 的 8888 监听会被系统挂起,br push表现为「连接建立但无响应 / 中途 Connection refused」;hdc fport 隧道 也可能被系统回收但本地端口仍被残留进程占用。已由 CLI 保活线程 + App 前台常亮 双保险缓解,详见 docs/transfer-spec.md §传输可靠性。
App 起 server,hdc fport 后 PC 直连(见扩展方向)。
br run "benchmark --modelFile=@/mobilenetv2.ms --loopCount=5 --warmUpLoopCount=1"真机输出(零售版非 root 手机,CPU 2 线程):
Model = mobilenetv2.ms, NumThreads = 2, MinRunTime = 24.259 ms,
MaxRuntime = 40.460 ms, AvgRunTime = 29.849 ms
Run Benchmark mobilenetv2.ms Success.
集成方式:benchmark 重命名为 libbenchmark.so + libmindspore-lite.so 直接放入
app/entry/libs/arm64-v8a/,模型 mobilenetv2.ms 放 rawfile(本仓库均已内置)。
| 路径 | 结果 |
|---|---|
hdc shell 执行 /data/local/tmp 二进制 |
❌ SELinux 拒绝(shell 域) |
| App execv libs 目录的 .so | ❌ EACCES(noexec) |
| App execv files 沙箱目录 | ❌ EACCES(noexec) |
| App execv memfd + /proc/self/fd | ❌ EACCES(SELinux 拒匿名 inode exec) |
| App 读 /data/local/tmp | ❌ SELinux(对 App 隐藏,opendir 报 ENOENT) |
hdc file send 到 App 沙箱 files 目录 |
❌ permission denied(shell uid 无权限,dir 0700 属 App uid) |
| hdc fport + PushServer 推送二进制到 filesDir/bin 执行 | ✅ 已实测(静态 hello、动态 benchmark + libmindspore-lite.so 免打包跑通) |
| App 读 /lib/ld-musl-aarch64.so.1 | ✅ 可读(动态链接前提) |
| App 对任意文件 mmap PROT_EXEC | ❌ EACCES(dlopen 能工作是系统加载器的特权通道) |
| hnp 包安装(module.json5 hnpPackages) | ❌ 手机零售版无效:App 命名空间里根本没有 /data/app、/data/service/hnp(该机制只在鸿蒙 PC 有效) |
| 内存 ELF loader + jit prctl(debug 签名) | ✅ 唯一可行 |
| 静态链接二进制(musl -static) | ✅ 稳定 |
| 动态链接二进制 + ld.so 加载 .so 依赖 | ✅ 已实测(mindspore benchmark + libmindspore-lite.so) |
| 模型推理(MobileNetV2) | ✅ 已实测(AvgRunTime 29.8ms) |
| bundle libs 目录文件随机读(lseek+read) | |
| App 内访问 /proc/self/fd/N | ❌ 不可访问 → loader 打补丁支持 "@fd" 直传已打开 fd |
| 伪造栈贴近映射段底部 | |
| auxv 缺 AT_BASE / AT_EXECFN |
# probe:枚举关键目录到 hilog,排查路径问题
hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "probe"
# probe2:动态链接可行性检测(/data/local/tmp 可读性、ld-musl 可读性、各目录 exec-mmap)
hdc shell aa start -b com.example.binrunner -a EntryAbility --ps cmd "probe2"- hilog 通道带宽:stdout/stderr 通过 hilog 回传,单条日志约 1000 字符上限。流式数据每块最多 400 字节,
十六进制编码后发送(2.2 倍膨胀),块间加微延迟降低 socket 溢出风险。真机实测 USB 链路约 325KB/s,
持续高速输出(单次 ≥ 约 1MB)会超过该上限;CLI 检查序号与总块数,确认设备已结束且缺块不可补齐后
立即报错并给出收到/应有块数(不再空等到
--timeout),已经显示的输出保留。 大输出场景建议拆小单次输出量,或等后续版本扩展 TCP/文件回传 - CPU 推理正常;GPU/NPU 推理未实测——限制在 MindSpore Lite 尚未适配鸿蒙 OS 的 GPU/NPU 驱动(benchmark 只能走 CPU),而非 BinRunner:沙箱内二进制可 dlopen 系统 GPU/NPU 驱动库,BinRunner 不限制驱动访问
- 熄屏挂起 PushServer:屏幕熄灭后 App 进后台,8888 监听被系统挂起,长传会中断。
br push已内置保活 + 自愈(见 §7.2),App 前台也保持常亮,双保险 - 二进制以 App uid 运行,受 App 沙箱约束(访问不了其他应用数据等)
- seccomp 存在(Termony 实测 setuid/setgid 会被杀),避免在用例里调用特权 syscall
- TCP 回传:App 起 socket server,
hdc fport tcp:8889 tcp:8889(8888 已被 PushServer 占用),适合大输出/交互式用例 - 批量用例:cmd 传用例名,App 内查表执行并汇总 exit code;PC 脚本批量驱动
- busybox 整套工具:静态编译 busybox 为 libbusybox.so,cmd 形式
busybox ls -l(libbusybox.so 内部按 argv[0]/argv[1] 分发 applet) br shell:交互式 shell,持续输入命令到同一 App 实例LD_LIBRARY_PATH递归子目录:动态链接器自动搜索filesDir/bin/的子目录LD_LIBRARY_PATH递归子目录:动态链接器自动搜索filesDir/bin/的子目录