feat(m53): 自写 timeout(1) 并接入 devkit 本地源码构建路径

设备没有 timeout，busybox 1.31 也无该 applet；2026-11-11 18:44 一条挂在硬件上的 bluetoothctl 累积 55 个残留进程耗尽进程表，dropbear 无法 fork，整机在线却不可登录。本单给设备一个可用的 timeout。 - scripts/build/devkit-src/timeout.c（新，Apache-2.0，489 行）独立实现，未拷贝 busybox/GPL 代码；fork+setpgid(0,0) 后 kill(-pgid)，孙进程一并终止；waitpid 回收直接子进程不留僵尸；-s/-k 两阶段终止；退出码 124/137/128+N/125/126/127 对齐 coreutils 语义。计时不用 timerfd（musl 的 timerfd_settime 在 4.4 上静默失效，实测 timeout 2 sleep 30 等满 30s 才返回），改用 setitimer(ITIMER_REAL)+SIGALRM，与 SIGCHLD 一起进 signalfd，由一次 ppoll 等待，零轮询、不读时钟。 - build_devkit.sh：新增 build_local（B 路径，不碰上游 procps/lsof/ncurses 流程）；TOOLS/TOOL_NAMES/MANIFEST/licenses/stamp/--with-sources 接入；产物同时标注 Apache-2.0 并随附许可证原文。 - test_build_devkit.sh：T9（产物静态/架构/零 NEEDED/MANIFEST/license）、 T10（源码纪律：独立实现、不调 clock_gettime、不用 timerfd、进程组模型）。 - DEVKIT.md/README.md：产物表、PATH 实测（ssh 非登录 shell 无 opt/bin，且设备无 bash → 用 sh -lc 或绝对路径）、禁裸跑纪律与 18:44 事故时间线、 timerfd 静默失效的第二类 time64 坑、2026-11-11 真机验收原始输出。
2026-11-11 21:23:52 +08:00
1 parent a41b61198e
commit 80c0bd4eb4
@@ -8,12 +8,19 @@
 # musl 交叉编出完全静态的二进制，放进 TF 卡供开发调试。
 #
 # 产物（全部静态链接、strip 过、无 NEEDED）：
-#   fw_apps/devkit/bin/{vmstat,slabtop,free,ps,pmap,sysctl,lsof}
+#   fw_apps/devkit/bin/{vmstat,slabtop,free,ps,pmap,sysctl,lsof,timeout}
 #   fw_apps/devkit/MANIFEST.txt      版本/许可证/体积/校验摘要
 #   fw_apps/devkit/licenses/         各上游 COPYING（分发留痕）
 #   fw_apps/devkit/README.txt        上卡后怎么加 PATH、和 busybox 的同名关系
-#   （--with-sources 时另有 fw_apps/devkit/src/：三份源码包 + build_devkit.sh +
-#    DEVKIT.md，GPLv2 §3 的“对应源码”含构建控制脚本）
+#   （--with-sources 时另有 fw_apps/devkit/src/：三份源码包 + 本脚本 +
+#    DEVKIT.md + timeout.c，GPLv2 §3 的“对应源码”含构建控制脚本）
+#
+# 两条编译路径（互不干扰）：
+#   A. 上游包（procps-ng / lsof / ncurses）—— 固定版本 + sha256 + 缓存
+#   B. 本地源码（scripts/build/devkit-src/*.c）—— 本仓 Apache-2.0 独立实现
+#      timeout.c 就是 B 路径：设备没有 timeout(1)，busybox 1.31 也无该 applet，
+#      而设备曾因一条挂死的外部命令（bluetoothctl）耗尽进程表、fork 失效、
+#      SSH 完全不可达（2026-11-11 18:44）。B 路径不联网、不打补丁、不改上游流程。
 #
 # 源码固定为「版本 + sha256 + 固定 URL」，全部校验后才编译；缓存命中则零联网。
 #
@@ -22,6 +29,9 @@
 #   不需要内核头（musl 头足够；只有 lsof 缺 11 个 TCP 状态宏，本脚本 -D 补上）。
 #   ⚠ 该工具链在 4.4 内核上是 time64 ABI 错配：`vmstat -t` 时间戳列会是空，
 #     原因/证据/后续修法见 DEVKIT.md「已知限制：工具链 time64」。不是 -D 能修的。
+#     同一坑的第二个表现：musl 的 timerfd_settime() 静默失效（返回 0 但不计时）。
+#     timeout 因此既不读时钟也不用 timerfd：超时用 setitimer(ITIMER_REAL)+SIGALRM，
+#     子进程退出用 SIGCHLD，两者进同一个 signalfd，由一次 ppoll 等（零轮询）。
 #
 # 许可证（二进制将来随卡分发时请保留此节）：
 #   procps-ng 4.0.4  GPL-2.0-or-later（COPYING=GPLv2）
@@ -31,6 +41,8 @@
 #   ncurses 6.5      MIT 风格（X11 许可），保留版权声明即可
 #   lsof 4.99.4      Purdue Research Foundation 许可（BSD 风格 4 条），
 #                    要求文档与源码中保留作者与 Purdue 的署名（COPYING 第 2 条）
+#   timeout          Apache-2.0（本仓自有，scripts/build/devkit-src/timeout.c）
+#                    独立实现，未拷贝 busybox/GPL 代码；许可证原文随产物分发
 #   本脚本链接的 ncurses 只作为 slabtop 的静态依赖进入产物，不单独分发。
 #
 # 用法：
@@ -69,6 +81,11 @@ NCURSES_VER="6.5"
 PROCPS_VER="4.0.4"
 LSOF_VER="4.99.4"

+# 本地源码（B 路径）：本仓 Apache-2.0 独立实现，不下载、不 patch、不进上游流程。
+# 每个 *.c 编一个同名可执行文件；新增工具只需丢一个 .c 进这个目录。
+LOCAL_SRC_DIR="$ROOT/scripts/build/devkit-src"
+LOCAL_TOOLS="timeout"
+
 # 设备内核版本：写进 lsof 的 LINUXV，让它按目标内核（4.4）选代码路径
 TARGET_KERNEL_VSTR="4.4.94"

@@ -77,18 +94,20 @@ SRC_NCURSES="ncurses-${NCURSES_VER}.tar.gz|https://mirrors.tuna.tsinghua.edu.cn/
 SRC_PROCPS="procps-ng-${PROCPS_VER}.tar.xz|https://downloads.sourceforge.net/project/procps-ng/Production/procps-ng-${PROCPS_VER}.tar.xz|22870d6feb2478adb617ce4f09a787addaf2d260c5a8aa7b17d889a962c5e42e"
 SRC_LSOF="lsof-${LSOF_VER}.tar.xz|https://deb.debian.org/debian/pool/main/l/lsof/lsof_${LSOF_VER}+dfsg.orig.tar.xz|dc3e7f51cf03bc7fbcdd9e62d4a52825682092031bd1ae08b15fe7f4f582aebf"

-# 卡上 src/ 必须包含的文件：三份源码包 + 构建脚本 + 本文档。
+# 卡上 src/ 必须包含的文件：三份源码包 + 构建脚本 + 本文档 + 本地源码。
 # GPLv2 §3 的“对应源码”明确包含 "scripts used to control compilation and
 # installation"，缺了脚本，收卡人拿不到本轮用的 -D/configure 参数。
-SRC_STAGE_LIST="ncurses-${NCURSES_VER}.tar.gz procps-ng-${PROCPS_VER}.tar.xz lsof-${LSOF_VER}.tar.xz build_devkit.sh DEVKIT.md"
+# timeout.c 不在 GPL 义务范围内（Apache-2.0 自有），但带上才能复现整包。
+SRC_STAGE_LIST="ncurses-${NCURSES_VER}.tar.gz procps-ng-${PROCPS_VER}.tar.xz lsof-${LSOF_VER}.tar.xz build_devkit.sh DEVKIT.md timeout.c"

 # 交付的工具——验证、MANIFEST 比对、stamp 自检都从这里取，避免多处手写漂移
-TOOL_NAMES="vmstat slabtop free ps pmap sysctl lsof"
+TOOL_NAMES="vmstat slabtop free ps pmap sysctl lsof $LOCAL_TOOLS"

 # licenses/ 下必须存在的许可证副本（缺一个都算交付不完整）：
 #   procps 是 GPL-2.0+（COPYING）且 library/ 是 LGPL-2.1+（COPYING.LIB），
 #   ncurses/lsof 是 MIT 风格 / Purdue，musl 是 MIT 且七个产物都静态链入了它。
-LICENSE_FILES="procps-ng-${PROCPS_VER}-COPYING procps-ng-${PROCPS_VER}-COPYING.LIB ncurses-${NCURSES_VER}-COPYING lsof-${LSOF_VER}-COPYING musl-COPYRIGHT"
+#   timeout 是本仓 Apache-2.0 自有实现，分发二进制时按 Apache-2.0 §4 附许可证原文。
+LICENSE_FILES="procps-ng-${PROCPS_VER}-COPYING procps-ng-${PROCPS_VER}-COPYING.LIB ncurses-${NCURSES_VER}-COPYING lsof-${LSOF_VER}-COPYING musl-COPYRIGHT meowos-timeout-LICENSE"

 FORCE=0
 CLEAN=0
@@ -221,12 +240,14 @@ sources_complete() {
    done
    cmp -s "$SCRIPT_PATH" "$OUT_DIR/src/build_devkit.sh" || return 1
    cmp -s "$ROOT/scripts/build/DEVKIT.md" "$OUT_DIR/src/DEVKIT.md" || return 1
+    # 本地源码也要与仓库逐字节一致：src/ 里的 timeout.c 必须能编出同一个二进制
+    cmp -s "$LOCAL_SRC_DIR/timeout.c" "$OUT_DIR/src/timeout.c" || return 1
    return 0
 }

 stage_sources() {
    local f
-    log "整理 $OUT_DIR/src（三份源码包 + 构建脚本 + 文档）"
+    log "整理 $OUT_DIR/src（三份源码包 + 本地源码 + 构建脚本 + 文档）"
    fetch_src "$SRC_NCURSES"
    fetch_src "$SRC_PROCPS"
    fetch_src "$SRC_LSOF"
@@ -239,6 +260,8 @@ stage_sources() {
        || die "复制构建脚本失败: $SCRIPT_PATH（GPLv2 §3 要求带构建脚本）"
    cp "$ROOT/scripts/build/DEVKIT.md" "$OUT_DIR/src/DEVKIT.md" \
        || die "复制 DEVKIT.md 失败: $ROOT/scripts/build/DEVKIT.md"
+    cp "$LOCAL_SRC_DIR/timeout.c" "$OUT_DIR/src/timeout.c" \
+        || die "复制本地源码失败: $LOCAL_SRC_DIR/timeout.c（Apache-2.0，复现 timeout 需要）"
    sources_complete || die "src/ 整理后仍不完整（sha256 或文件缺失）"
    info "共 $(du -sh "$OUT_DIR/src" | cut -f1)：$(ls "$OUT_DIR/src" | tr '\n' ' ')"
 }
@@ -341,13 +364,41 @@ build_lsof() {
    )
 }

+# ---------------------------------------------------------------------------
+# 4b) 本地源码（B 路径）：scripts/build/devkit-src/*.c
+#     与上游包完全隔离：不下载、不 configure、不 make、不改 TOOLS 里上游的
+#     源码/构建参数。只做一次 zig cc，产物落在 $BUILD_DIR/local/<name>，
+#     之后由 collect_and_verify 统一 strip + 静态/架构/NEEDED 自检。
+#     -ffile-prefix-map 抹掉宿主路径（与上游同样的可复现性要求，见 DEVKIT.md §10）；
+#     -static 显式给，不依赖工具链默认值。
+# ---------------------------------------------------------------------------
+build_local() {
+    local f name
+    log "编译本地源码（$LOCAL_SRC_DIR，Apache-2.0 自有实现）"
+    rm -rf "$BUILD_DIR/local"
+    mkdir -p "$BUILD_DIR/local"
+    for f in "$LOCAL_SRC_DIR"/*.c; do
+        [ -f "$f" ] || die "本地源码目录为空: $LOCAL_SRC_DIR"
+        name="$(basename "$f" .c)"
+        info "zigcc → $name"
+        "$ZIGCC" -O2 -Wall -Wextra -static \
+            -ffunction-sections -fdata-sections \
+            -ffile-prefix-map="$LOCAL_SRC_DIR"=/devkit-src \
+            -Wl,--gc-sections \
+            -o "$BUILD_DIR/local/$name" "$f" \
+            > "$BUILD_DIR/local-$name.log" 2>&1 \
+            || { tail -30 "$BUILD_DIR/local-$name.log"; die "$name 编译失败"; }
+    done
+}
+
 # ---------------------------------------------------------------------------
 # 5) 收集 + strip + 逐项验证
 # ---------------------------------------------------------------------------
 # 产出清单：<源路径>|<目标名>|<出处>|<许可证>
 # 只放「真机实测能跑且真有价值」的：vmstat/slabtop（busybox 没有）、
 # free/ps/pmap（busybox 版字段残缺）、sysctl（busybox 1.31 没有此 applet）、
-# lsof（busybox 版只有 pid/fd）。
+# lsof（busybox 版只有 pid/fd）、timeout（busybox 1.31 没有此 applet，2026-11-11
+# 整机进程耗尽事故后成为设备侧刚需）。
 # 不交付 top：表头时钟被工具链 time64 打坏（不是 procps 的 bug，见 DEVKIT.md §9），
 # 且卡上已有 htop 3.5.3（673KB）→ 属重复且不可信。
 TOOLS="
@@ -358,6 +409,7 @@ $BUILD_DIR/procps/src/ps/pscommand|ps|procps-ng $PROCPS_VER|GPL-2.0-or-later
 $BUILD_DIR/procps/src/pmap|pmap|procps-ng $PROCPS_VER|GPL-2.0-or-later
 $BUILD_DIR/procps/src/sysctl|sysctl|procps-ng $PROCPS_VER|GPL-2.0-or-later
 $BUILD_DIR/lsof/lsof|lsof|lsof $LSOF_VER|Purdue/BSD-style
+$BUILD_DIR/local/timeout|timeout|devkit-src (local)|Apache-2.0
 "

 FAIL=0
@@ -420,6 +472,9 @@ write_meta() {
    # musl：七个 procps/lsof 产物都静态链入了 zig 自带 musl（MIT），必须随副本留声明
    cp "$MUSL_COPYRIGHT"                   "$OUT_DIR/licenses/musl-COPYRIGHT" \
        || die "复制许可证失败: musl COPYRIGHT（$MUSL_COPYRIGHT）"
+    # timeout 是本仓自有 Apache-2.0 实现：Apache-2.0 §4 要求分发时附许可证原文
+    cp "$ROOT/LICENSE"                     "$OUT_DIR/licenses/meowos-timeout-LICENSE" \
+        || die "复制许可证失败: $ROOT/LICENSE（timeout 的 Apache-2.0 原文）"

    {
        echo "MeowOS devkit — 静态 MIPS32r2 调试工具集"
@@ -439,16 +494,20 @@ EOF
        echo "  ncurses  $NCURSES_VER  MIT-style   sha256 $(printf '%s' "$SRC_NCURSES" | awk -F'|' '{print $3}')"
        echo "  procps-ng $PROCPS_VER  GPL-2.0+ / library=LGPL-2.1+   sha256 $(printf '%s' "$SRC_PROCPS" | awk -F'|' '{print $3}')"
        echo "  lsof     $LSOF_VER  Purdue/BSD   sha256 $(printf '%s' "$SRC_LSOF" | awk -F'|' '{print $3}')"
+        echo "  timeout  Apache-2.0  本仓 scripts/build/devkit-src/timeout.c（独立实现，未拷贝 GPL 代码）"
+        echo "           sha256 $(sha256sum "$LOCAL_SRC_DIR/timeout.c" | cut -d' ' -f1)"
        echo "  musl     zig $ZIG_VERSION 自带（MIT）  许可证原文见 licenses/musl-COPYRIGHT"
-        echo "  （--with-sources 时）src/ 内还有 build_devkit.sh + DEVKIT.md（构建控制脚本，GPLv2 §3 要求）"
+        echo "  （--with-sources 时）src/ 内还有 build_devkit.sh + DEVKIT.md + timeout.c（构建控制脚本与本地源码）"
        echo "  重编方法: src/build_devkit.sh（卡上路径；仓库里是 scripts/build/build_devkit.sh）"
-        echo "  许可证原文: licenses/*-COPYING / licenses/*-COPYRIGHT；说明见 src/DEVKIT.md"
+        echo "  许可证原文: licenses/*-COPYING / licenses/*-COPYRIGHT / licenses/meowos-timeout-LICENSE"
+        echo "  说明见 src/DEVKIT.md"
        echo
        echo "注意: procps-ng 是 GPL-2.0-or-later。把本目录随卡交付给第三方时，"
        echo "      GPLv2 §3 要求提供对应源码（含构建脚本）—— 请用 --with-sources 带上 src/，"
        echo "      或随卡附书面要约（有效期 ≥3 年）。仅给出下载 URL 不构成合规。"
        echo "      另外 ps/vmstat/slabtop/free/pmap/sysctl 静态链接了 LGPL-2.1+ 的 libproc2："
        echo "      LGPL-2.1 §6 要求「源码(§6a) 或 共享库(§6b) 或 书面要约(§6c)」三选一，详见 DEVKIT.md §6。"
+        echo "      timeout 是 Apache-2.0（本仓自有），与上述 GPL 组件无源码混合。"
    } > "$OUT_DIR/MANIFEST.txt"

    cat > "$OUT_DIR/README.txt" <<'EOS'
@@ -464,12 +523,21 @@ MeowOS devkit — 设备端调试工具（静态 MIPS32r2）
        export PATH="/usr/data/mnt/sd_0/MeowOS/opt/devkit/bin:$PATH"
    fi

+⚠ SSH 默认是**非登录 shell**：`ssh root@设备 'cmd'` 的 PATH 只有
+  /usr/sbin:/usr/bin:/sbin:/bin，**不含 MeowOS/opt/bin，也不含本 devkit 目录**。
+  所以卡上直接 `timeout 1 sleep 5` 会报 not found。两种正确写法：
+      sh -lc 'timeout 1 sleep 5'                         # 走登录 shell → 带上 opt/bin
+      /usr/data/mnt/sd_0/MeowOS/opt/devkit/bin/timeout 1 sleep 5   # 绝对路径
+  （2026-11-11 实测：ssh 非登录 shell 下 `command -v timeout` 为空。）
+
 目录内容（本文件所在目录就是 devkit 根）：
    bin/            可执行文件（实体文件，非软链）
    MANIFEST.txt    版本 / 许可证 / 体积 / sha256
-    licenses/       上游许可证原文（procps GPLv2 + LGPL-2.1、ncurses、lsof、musl）
+    licenses/       许可证原文（procps GPLv2 + LGPL-2.1、ncurses、lsof、musl、
+                    meowos-timeout-LICENSE = Apache-2.0）
    src/            仅当随卡附带了源码（--with-sources）时存在：三份源码包 +
-                    build_devkit.sh + DEVKIT.md。**src/ 是生成目录，请勿手放文件。**
+                    build_devkit.sh + DEVKIT.md + timeout.c。
+                    **src/ 是生成目录，请勿手放文件。**
    说明文档：src/DEVKIT.md（若本源码未随附，见仓库 scripts/build/DEVKIT.md）

 exFAT 没有 Unix 权限位（挂载 fmask=0022 → 新文件一律 0755），也没有符号链接。
@@ -480,11 +548,27 @@ exFAT 没有 Unix 权限位（挂载 fmask=0022 → 新文件一律 0755），
 与 busybox 同名命令的关系（devkit/bin 前插 PATH 时生效）：
    free  ps  lsof              → 会被本目录版本覆盖（procps/lsof 字段更全）
    vmstat  slabtop  pmap  sysctl → busybox 1.31 没有这些 applet，直接新增
+    timeout                     → busybox 1.31 同样没有，直接新增
 要临时用回 busybox 版：busybox free / busybox ps / busybox lsof
 注意：/bin/ps -> busybox，/usr/bin/{free,lsof,top} -> ../../bin/busybox，
 所以“前插 devkit/bin”是唯一让新版本生效的方式（不要覆盖这些软链：
 rootfs 是 ubifs，随固件回刷会被还原，而且 busybox 软链是基线的一部分）。

+timeout 用法（本仓 Apache-2.0 独立实现，非 busybox 代码）：
+    timeout [-s SIGNAL] [-k DURATION] DURATION COMMAND [ARGS...]
+    timeout 2 sleep 30              # 2 秒后返回，退出码 124
+    timeout -s KILL 2 sleep 30      # 退出码 137
+    timeout -k 1 5 bluetoothctl connect XX:XX...   # TERM 后 1 秒仍在 → KILL
+    timeout 0.2 sleep 5             # 支持小数秒（约 200ms 返回）
+  超时信号发给 COMMAND 的**整个进程组**：命令自己 fork 的孙进程一起死
+  （`timeout 5 sh -c 'a & b & wait'` 不会留下 a/b）。退出码：
+    124=超时  137=超时且最终发了 KILL  128+N=命令死于信号 N
+    125=timeout 自身参数/系统调用错  126=命令无法执行  127=命令不存在
+  不支持 --preserve-status / -v / d（天）后缀，给了会明确报 125（不静默忽略）。
+  不跟踪 setsid() 逃出进程组的守护进程（coreutils 也不跟踪）。
+  精度是毫秒级够用：计时交给内核 setitimer(ITIMER_REAL)+SIGALRM，不读时钟，
+  误差主要来自调度延迟（单核负载高时数十毫秒）。
+
 已知限制：
  - pmap 只能读 /proc/<pid>/maps；本机 CONFIG_PROC_PAGE_MONITOR=n，
    /proc/<pid>/smaps 不存在，所以 pmap -x 拿不到 PSS/私有脏页。
@@ -496,6 +580,9 @@ rootfs 是 ubifs，随固件回刷会被还原，而且 busybox 软链是基线
        `free -s 1` 与 `vmstat 1 N` 的整秒间隔正常
      * ps 的 lstart、slabtop/pmap/sysctl 不受影响
    原因与后续修法见 src/DEVKIT.md「已知限制：工具链 time64」。
+    timeout 不受影响：它不调用 clock_gettime/time，也不用 timerfd
+    （musl 的 timerfd_settime 在这台机上是静默失效的），超时由内核
+    setitimer(ITIMER_REAL)+SIGALRM 计时。
  - lsof 不带 -n 时会尝试反向解析（编译进 musl 的 resolv.conf 路径是构建机的，
    设备上不存在）→ 实测 `lsof -i` 约 3s 超时；请用 `lsof -nP`。
  - 不提供 top：见 src/DEVKIT.md（同样是 time64 问题：表头时钟不可信）。
@@ -510,6 +597,8 @@ stamp_value() {
        # 带 zig 的完整版本（0.17.0 → 0.17.1 也要触发重建：工具链 patch 会改产物）
        echo "zig=$ZIG_VERSION target=$ZIG_TARGET kernel=$TARGET_KERNEL_VSTR"
        echo "ncurses=$NCURSES_VER procps=$PROCPS_VER lsof=$LSOF_VER"
+        # 本地源码（timeout 等）：内容变就必须重编，否则 stamp 命中会漏掉新代码
+        ( cd "$LOCAL_SRC_DIR" && sha256sum *.c ) 2>/dev/null || true
    } | sha256sum | cut -d' ' -f1
 }

@@ -590,6 +679,7 @@ main() {
    build_ncurses
    build_procps
    build_lsof
+    build_local

    collect_and_verify
    [ "$FAIL" = 0 ] || die "$FAIL 个产物未通过静态/架构自检（见上）"