SDK 文档 / 10 · 调试与排错
10 · 调试与排错
设备上没有 IDE、没有 gdb 图形界面,能用的就是日志和几条命令。这一章先给"症状 → 原因"的速查表,再讲怎么手跑应用、怎么确认触摸/服务状态。
10.1 症状速查
| 症状 | 最可能的原因 | 怎么确认 | 处理 | |
|---|---|---|---|---|
| 桌面没有图标 | 目录不在 /blackbox/apps/ 下;或 bbui 没重扫 |
ls /blackbox/apps |
装完等 0.25 s;不行就重启 bbui | |
| 图标是灰的(点了提示装坏了) | app.json 读不到 / entry 文件不在 |
cat /blackbox/apps/<id>/app.json;ls -l 看入口 |
修文件名;unzip -o 重装 |
|
| 点图标黑一下又回桌面 | 应用启动即退出(连不上 wayland、init 非 0、崩溃) |
tail -30 app.log,看最后一行 [bbapp] |
见 10.3 | |
| 应用起来了但点不到 | 选中了副屏触摸;或没抢到独占 | 日志找 触摸独占成功 / touch ... MT 400x712 |
用 BBAPP_TOUCH 指定设备 |
|
| 点 A 处却响应 B 处坐标 | 同上(坐标整体偏) | 看日志 tap x,y 是否落在预期区 |
同上 | |
| 画面转 90° / 竖着 | 自己开了窗口或设了 BBAPP_ROT=90 |
echo $BBAPP_ROT |
去掉;别自己开 wayland 窗口 | |
| 画面正常但动不了 | draw 阻塞(死循环/大 IO),主线程卡住 |
top 看 CPU 是否 100% |
别在 draw 里做重活 |
|
| 文字是方块 | 设备缺字体 | `fc-list \ | grep -i quan` | 重跑部署器(10.1 字体注册) |
| 画面全黑但进程活着 | 首帧没提交(卡在 init) |
日志停在 启动 ... 之后、没有 tap 记录 |
检查 init 是否阻塞 |
|
| 应用 1 秒后消失 | 没跑在独立 cgroup 里(旧版启动方式) | systemctl status bbui-app-* |
用当前 apps.c 的 systemd-run 路径 |
|
| 相机界面盖住应用 | DJI 服务被拉回来了 | systemctl is-active dji_camera3 |
确认 app-run.sh 在跑(每 2 s 压一次) |
|
| 回桌面后触摸失灵 | 独占没释放(应用被 SIGKILL 硬杀) |
重启 bbui:bbui-stop; bbui |
EVIOCGRAB 随 fd 关闭自动释放,通常立刻恢复 |
|
| 中文路径打不开 | snprintf 缓冲太小被截断 |
日志里的路径 | 缓冲给 600 字节 |
10.2 日志怎么读
adb shell tail -f /blackbox/apps/com.example.hello/app.log
一次成功的启动,日志里这几行一定都在(顺序固定):
[20:11:03] === app-run 开始: /blackbox/apps/com.example.hello/hello ===
[20:11:03] exec /blackbox/apps/com.example.hello/hello
[1762...] [bbapp] touch /dev/input/event2 'fts_ts_3269' MT 400x712 -> 有匹配屏 score=1000
[1762...] [bbapp] 主屏 712x400(面板 400x712, 输出 'DSI-1' mode 400x712, rot=0)
[1762...] [bbapp] 触摸独占成功 (0..399, 0..711)
[1762...] [bbapp] 启动 com.example.hello (示例) 画布 712x400
对着缺哪行判断:
| 缺的行 | 说明 |
|---|---|
=== app-run 开始 === |
脚本没被执行(/blackbox/svc/app-run.sh 不存在或不可执行) |
exec ... |
脚本卡在"等 bbui 退出"那 5 秒里,或者脚本本身被杀了(systemctl status 看单元状态) |
触摸独占成功 |
EVIOCGRAB 失败——常见于 bbui 还没真正退出 |
一行 [bbapp] 都没有 |
应用在连 wayland 之前就崩了(动态库缺失最常见) |
有 启动 ... 但没有首帧 |
卡在 init() |
10.3 手跑(不经 bbui,直接看输出)
排查"到底是我崩了还是启动链路坏了"的最快办法:bbui 不在的时候手动跑。
adb shell
# 1) 停掉 bbui,把屏幕让出来
bbui-stop
# 2) 直接跑应用,环境变量自己给
cd /blackbox/apps/com.example.hello
XDG_RUNTIME_DIR=/run/user/root WAYLAND_DISPLAY=wayland-1 \
BBAPP_DATA=$PWD/data BBAPP_ASSETS=$PWD/assets BBAPP_LOG=$PWD/app.log \
./hello
- 崩了会直接在终端看到段错误/缺库;
- 想同时看系统日志:另开一个 adb shell
logcat | grep -i bbapp; - 想验证触摸但不独占:加
BBAPP_NOGRAB=1; - 跑完
bbui回来。
常见输出与含义
| 输出 | 原因 |
|---|---|
[bbapp] 连不上 wayland(WAYLAND_DISPLAY=...) |
环境变量没给,或 bbui-stop 把 weston 也带下去了 |
error while loading shared libraries: libcairo.so.2 |
设备缺 cairo(部署不完整) |
[bbapp] 触摸独占失败: Device or resource busy |
还有别的进程(bbui?)抓着 |
[bbapp] 没有 MT 触摸设备 -> 用默认 712x400(只能看,点不了) |
设备节点不存在(root 权限或 device 不匹配) |
10.4 确认触摸状态
# 谁在用这个设备(有 grab 时看不到别的进程,但能看到自己的)
adb shell "cat /proc/bus/input/devices | grep -A5 fts_ts"
# 直接看原始事件(会被 grab 挡掉,所以先 bbui-stop 再跑)
adb shell "cat /dev/input/event2 | od -An -tx1 -w16 | head"
如果 cat 没有输出、而应用里点击有日志,说明 grab 正常工作(事件只给了应用)。
10.5 注入点击做自动化
adb push tools/tapinj.aarch64 /blackbox/tmp/tapinj
adb shell "chmod 755 /blackbox/tmp/tapinj"
# 面板坐标:raw_x = 399 - y, raw_y = x
adb shell "/blackbox/tmp/tapinj /dev/input/event2 200 356 40"
适用场景:验证"应用能不能收到点击"、跑冒烟测试、触摸屏坏了临时操作。
注意参数是面板坐标不是画布坐标(07 有换算表)。
10.6 确认 DJI 服务被压住
adb shell "for u in gui sub_gui dji_camera3; do \
printf '%s=%s ' \$u \$(systemctl is-active \$u); done; echo"
应用运行期间三条都应该是 inactive/failed。如果 active,说明 app-run.sh 的守候循环没在跑(脚本被杀了、或者应用是用别的方式起的)。
10.7 检查应用单元
adb shell "systemctl list-units --all | grep bbui-app"
adb shell "systemctl status bbui-app-12345 --no-pager"
adb shell "journalctl -u bbui-app-12345 --no-pager | tail -30"
journalctl 能看到 systemd-run 启动失败的原因(比如单元名重复——我们的单元名带 pid,正常不会撞)。
10.8 拿崩溃信息
没有 gdb,但有三个手段:
# 1) 退出码(脚本会写进 app.log)
# rc=139 段错误, rc=134 abort, rc=137 SIGKILL
# 2) dmesg 里的段错误记录(含 pc 和库名)
adb shell "dmesg | grep -i -A3 'segfault\|hello'"
# 3) 自己装一个信号处理器,把 backtrace 打到日志
经验值:crash 90% 是空指针、缓冲区越界、或者 cairo_t 跨帧使用(保存了 cr 指针)。
10.9 性能怎么看
# 应用占多少 CPU
adb shell "top -b -n1 | grep hello"
# 帧率:连续取 10 次绘制日志的时间(如果自己加了日志)
判断标准很简单:没有 tick 的应用,静止时 CPU 应该接近 0。如果静止也占几成 CPU,说明你注册了 tick(注册即持续重绘)。
10.10 恢复到干净状态
# 停掉所有应用相关进程
adb shell "pkill -f '/blackbox/apps/'"
# 回桌面
adb shell "bbui"
# 清日志重来
adb shell "> /blackbox/apps/com.example.hello/app.log"
如果屏幕彻底黑了(bbui 和应用都没起来):
adb shell "bbui" # 短命令,等价于 ui-start.sh
adb shell "sh /blackbox/opt/bin/ui-start.sh" # 短命令不在时
下一步 → 11 版本与兼容。