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) 或 返回键

几个容易误解的点

  1. tick 一存在就会持续重画。 条件是 need_draw || app->tick,所以注册了 tick 的应用即使在 tick 里什么都不做,也会按合成器的节奏不停出帧。想省电就别注册 tick,只用 bbapp_redraw()。
  2. draw 里不要做慢操作。 它在主线程里,阻塞就会掉帧、也会延迟触摸处理。
  3. tap 在 poll 的同一轮里被调用,所以 tap 里改的状态,下一帧就能看到。
  4. 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):

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」

约束

  1. 后台期间 draw 不会被调用——没有 surface,画了也没地方显示;
  2. tick 继续跑,所以音乐播放、下载、计时这类"不需要屏"的业务才适合后台;
  3. 后台实例仍然占着一个 bbui 之外的进程,桌面「应用 → 详情」能看到「后台中」并可停止;
  4. 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 绘制:画布、像素格式、帧循环与性能预算。

bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成