SDK 文档 / 05 · 生命周期
05 · 生命周期
"点图标 → 应用全屏 → 点返回 → 回桌面"这条链上有 4 个进程、2 次 exec、1 次信号。这一章按时间顺序拆开,每步都给出实际命令和最大等待时间。出问题时对着这张表排查,比看代码快。
5.1 全景时序
时间 bbui(launcher) app-run.sh 你的应用 systemd
│
├─ 用户点卡片
├─ fork + setsid ────────────────────────────────► systemd-run --unit=bbui-app-<pid>
│ └─► 起 app-run.sh(独立 cgroup)
├─ usleep(120ms) │
├─ raise(SIGTERM) ├─ 轮询 pgrep blackbox-ui
└─ on_signal: release_grab + _exit(0) │ (每 100ms,最多 50 次)
│
┌─────────────────────────────────┘
├─ export BBAPP_DATA/ASSETS/LOG
├─ chmod 755 入口(保险)
├─ 后台启动应用 ──────────────► main()
│ ├─ bbapp_main()
│ │ ├─ 连 wayland
│ │ ├─ 探测触摸 + 挑主屏
│ │ ├─ 建 shm buffer
│ │ ├─ wl_shell 全屏
│ │ ├─ EVIOCGRAB 独占
│ │ └─ init()
├─ while kill -0 PID: └─ 帧循环 tick/draw/poll
│ 每 2s 停 gui/sub_gui/dji_camera3
│ (DJI 会自动把它们拉回来,所以要一直压)
│
应用退出(4 种方式之一)
├─ wait → rc
├─ 写日志 "应用退出 rc=N -> 回 bbui"
└─ exec /blackbox/opt/bin/bbui
└─► ui-start.sh: 停 DJI 界面 → 起 blackbox-ui
5.2 各阶段耗时与上限
| 阶段 | 典型 | 上限 | 超时会怎样 |
|---|---|---|---|
| fork → systemd-run 生效 | < 50 ms | —— | fork 失败时 bbui toast "启动失败(fork)" |
| bbui 从收到 SIGTERM 到退出 | < 100 ms | —— | 卡在释放相机时可能到几百 ms |
app-run.sh 等 bbui 消失 |
0.2~0.6 s | 5 s(50 × 100 ms) | 第 5 秒后 pkill -x blackbox-ui 强杀 |
| 应用连 wayland + 建 buffer | 0.1~0.3 s | —— | 连不上则日志报错、退出、回桌面 |
| 首帧可见 | 约 0.5~1.5 s(从点击算) | —— | 一直黑屏 = 应用卡在 init(),见 10 |
| 回桌面(返回键) | < 0.3 s | —— | exec bbui 失败则退回 ui-start.sh;再失败 _exit(127)(屏幕会黑) |
5.3 你的应用被调用的顺序
main() ← 你写的 BBAPP_MAIN 宏
└─ bbapp_main(&g_app) ← SDK 接管
├─ 参数检查:g_app 为 NULL 或没有 draw → 返回 2
├─ 读 BBAPP_DATA / BBAPP_ASSETS / BBAPP_LOG,mkdir(data)
├─ 装信号处理器(TERM/INT/HUP)、忽略 SIGCHLD/SIGPIPE
├─ wl_display_connect() 连接失败 → 返回 1
├─ 枚举全局对象(4 次 roundtrip)
├─ pick_target() 选主屏 + 触摸设备
├─ create_buffer() shm 1.14 MB(712×400×4)
├─ 建 surface / shell_surface / 全屏
├─ EVIOCGRAB 失败只记日志,不退出
├─ init() 你的第一个回调;返回非 0 → 记日志 → 回 bbui
└─ for (;;):
tick(now) ← 每轮都调(约每 16 ms 一次)
if (need_draw || tick) draw(cr, w, h) /* 内部挑一块空闲 buffer */
poll(wayland fd, evdev fd, 16ms)
├─ wayland 事件 → wl_display_dispatch(断开则跳出循环)
└─ 触摸事件 → 内部状态机 → tap(x,y) 或 返回键
几个容易误解的点
tick一存在就会持续重画。 条件是need_draw || app->tick,所以注册了tick的应用即使在tick里什么都不做,也会按合成器的节奏不停出帧。想省电就别注册tick,只用bbapp_redraw()。draw里不要做慢操作。 它在主线程里,阻塞就会掉帧、也会延迟触摸处理。tap在poll的同一轮里被调用,所以tap里改的状态,下一帧就能看到。init里拿到的bbapp_width()/height()已经是最终值,可以放心算布局。
5.4 四种退出方式
| 方式 | 触发 | SDK 行为 | 结果 |
|---|---|---|---|
| 返回键 | 点左上角「< 返回」 | bbapp_quit():释放独占 → 销毁 shell_surface/surface → flush → exec bbui |
回桌面,rc 由 exec 后的 bbui 决定 |
应用调 bbapp_quit() |
你自己的"完成/退出"按钮 | 同上 | 回桌面 |
正常 return / exit(0) |
main 返回 |
不会回 bbui(surface 就留在屏幕上) | 由 app-run.sh 兜底回桌面 |
| 崩溃 / 被 kill | 段错误、kill、OOM |
信号处理器只释放独占,_exit(0) |
由 app-run.sh 兜底回桌面 |
四个 rc 值写在日志里:
[20:15:22] 应用退出 rc=0 -> 回 bbui 正常
[20:15:22] 应用退出 rc=139 -> 回 bbui 段错误(128+11)
[20:15:22] 应用退出 rc=137 -> 回 bbui SIGKILL(128+9,多半是 OOM 或被手动杀)
[20:15:22] 应用退出 rc=1 -> 回 bbui wayland 连不上
注意:
main里直接return 0是合法但不推荐的收尾方式——SDL 式的"应用自己退出"在别的平台很自然,在这里会留下一块没人销毁的 surface,屏幕上会出现一层黑底直到脚本把 bbui 拉起来。统一用bbapp_quit()。
5.5 信号语义
| 信号 | SDK 收到后 | 说明 |
|---|---|---|
SIGTERM / SIGINT / SIGHUP |
释放 EVIOCGRAB → 关闭触摸 fd → _exit(0) |
不销毁 surface、不 exec bbui;回到桌面的责任在 app-run.sh |
SIGCHLD |
忽略 | 配合 bbapp_shell(),不留僵尸进程 |
SIGPIPE |
忽略 | wayland 断开时写 socket 不会打死进程 |
SIGTERM 这条路径故意不 exec bbui:如果你是被人 kill 的,说明外部(脚本/用户/部署器)正在收尾,再由应用去拉启动器会打架。
5.6 卡死会怎样(重要)
SDK 没有看门狗。 如果 draw 死循环、或 init 里 sleep(3600):
- 屏幕停在最后一帧,触摸不再响应(主线程被占);
app-run.sh的守候循环还在,但它只会在进程退出后才动作;- 没有物理返回键 → 用户只能长按电源,或从 adb
kill掉进程:
adb shell "pkill -f /blackbox/apps/com.example.hello"
# 脚本随即 exec bbui,桌面回来
写应用时请自己保证:draw/tap/tick 里不做阻塞 IO、不做 system()、不无限循环。需要跑长任务就用 bbapp_shell() 丢到后台。
5.7 和 DJI 服务的拉扯
app-run.sh 在应用存活期间每 2 秒执行一次:
for u in gui sub_gui dji_camera3; do
[ "$(systemctl is-active $u)" = "active" ] && systemctl stop "$u"
done
原因:bbui 一退出,dji_camera3 会被 systemd 的 Restart= 拉回来,相机界面立刻盖住应用并抢走触摸(实测应用 1 秒后 EVIOCGRAB 失败)。
代价是:应用运行期间 DJI 的相机/设置界面处于停止状态,回桌面后由 ui-start.sh负责恢复。所以不要在应用里假设"另一个 DJI 界面在后台活着"。
5.9 后台常驻(background,2026-11-03)
清单写 "background": true 的应用,「返回」不等于退出。
点「返回」
├─ 释放 EVIOCGRAB(让 bbui 能抢)
├─ 销毁 wl_shell_surface / wl_surface(屏幕让出来)
├─ 写 <app>/run.pid(内容是 pid)
├─ bbapp_shell("/blackbox/opt/bin/bbui") → bbui 起来,桌面出现
└─ 主循环继续跑:tick() 照常,draw() 不再调用
再点同一个图标
宿主 apps.c 读 run.pid → kill(pid,0) 活着 → SIGUSR1
→ 应用:重建 surface + 全屏 + EVIOCGRAB → 删 run.pid → 继续画
→ 宿主 120ms 后让 bbui 退出(和普通启动同一条路径)
三条兜底
| 情况 | 行为 |
|---|---|
后台进程已经死了(崩溃/被 kill -9) |
宿主发现 pid 是僵尸或不存在 → 删 run.pid → 走正常启动 |
应用正在后台时被 SIGTERM |
SDK 走普通清理(释放触摸、_exit(0)),run.pid 由宿主下次点击时清 |
| 重建 surface 失败 | SDK 直接 exec bbui 回桌面,不留在半死状态 |
| 唤醒后抢不回触摸 | bbui 是收到 SIGTERM 才释放 EVIOCGRAB,SDK 是收到 SIGUSR1 就恢复,两者赛跑;所以 SDK 会重试最多 2 秒(50 ms × 40),成功才记「恢复后重新独占触摸 OK」 |
约束
- 后台期间
draw不会被调用——没有 surface,画了也没地方显示; tick继续跑,所以音乐播放、下载、计时这类"不需要屏"的业务才适合后台;- 后台实例仍然占着一个 bbui 之外的进程,桌面「应用 → 详情」能看到「后台中」并可停止;
app-run.sh在应用真正退出时如果发现 bbui 已经在跑,不会再拉一个(避免两个启动器)。
5.8 与应用相关的几个边界条件
| 场景 | 行为 |
|---|---|
| 同一个应用连点两次 | 第二次点击时 bbui 已经在退出路径上,不会再拉一个实例 |
| 应用启动瞬间用户又点别的图标 | 来不及——bbui 已经 _exit(0) 了 |
app-run.sh 不存在(部署不完整) |
systemd-run 起不来 → 回退 sh app-run.sh 也失败 → 退出 127 → 屏幕黑,只能 adb 救 |
bbui 短命令不存在 |
应用返回时 exec /blackbox/opt/bin/bbui 失败 → 回退 sh ui-start.sh → 再失败 _exit(127) |
下一步 → 06 绘制:画布、像素格式、帧循环与性能预算。