diff --git a/docs/armv7-glibc-compat.md b/docs/armv7-glibc-compat.md new file mode 100644 index 0000000..0cf291a --- /dev/null +++ b/docs/armv7-glibc-compat.md @@ -0,0 +1,133 @@ +# armv7 平台包 glibc 兼容性整改规格(给 ssw-platform) + +> 提交方:ssw-tds-test(设备侧接入方) +> 日期:2026-11-12 +> 关联产物:`dist/sspf-v0.5.0-armv7-unknown-linux-gnueabihf.tar.gz`(150M) +> 关联引擎:`dist/pglite-armv7-unknown-linux-gnueabihf.tar.gz`(10M) + +## 1. 结论一句话 + +armv7 平台包**架构是对的**(rlib 全部 `armv7-unknown-linux-gnueabihf`,引擎二进制是 ARM EABI5 armhf), +但**链接用的 sysroot 是 Debian 12 的 GLIBC 2.36**,导致引擎被绑定到 `GLIBC_2.34` 版本节点, +**在 glibc ≤ 2.28 的设备上无法启动**(已实测复现)。 + +## 2. 实测证据 + +### 2.1 产物架构正确 + +``` +libpglite.a : ARM 静态库 +bin/initdb : ELF 32-bit LSB pie executable, ARM, EABI5, interpreter /lib/ld-linux-armhf.so.3 +bin/postgres : ELF 32-bit LSB pie executable, ARM, EABI5 +sspf 平台包 127 个 rlib : 目标三元组均为 armv7-unknown-linux-gnueabihf,无 x86_64 残留 +``` + +### 2.2 版本要求过高(根因) + +`objdump -T` 读出的版本需求: + +| 二进制 | 需要的 GLIBC 版本 | +|---|---| +| `bin/postgres` | 2.17, 2.25, **2.28, 2.29, 2.33, 2.34** | +| `bin/initdb` | 2.10, 2.14, **2.28, 2.29, 2.33, 2.34** | + +按版本号分组的符号: + +| 版本节点 | 符号 | +|---|---| +| GLIBC_2.34 | `__libc_start_main` `dlopen` `dlsym` `dlclose` `dlerror` `sem_init` `sem_destroy` `sem_post` `sem_wait` `sem_trywait` `shm_open` `shm_unlink` | +| GLIBC_2.33 | `stat64` `fstat64` `lstat64` | +| GLIBC_2.29 | `exp` `log` `pow` | +| GLIBC_2.28 | `fcntl` `fcntl64` | + +**这些符号本身在 glibc 2.26 就全部存在**(`sem_*`/`shm_open`/`dlopen` 都是老符号), +只是版本节点被绑高了 ⇒ **不是缺功能,是版本标签不匹配**。 + +### 2.3 复现(不需要设备) + +```bash +docker run --rm --platform linux/arm/v7 -v :/rt:ro arm32v7/debian:buster sh -c '/rt/bin/initdb --version' +``` + +输出(buster = glibc 2.28): + +``` +/rt/bin/initdb: /lib/arm-linux-gnueabihf/libm.so.6: version `GLIBC_2.29' not found (required by /rt/bin/initdb) +/rt/bin/initdb: /lib/arm-linux-gnueabihf/libc.so.6: version `GLIBC_2.33' not found (required by /rt/bin/initdb) +/rt/bin/initdb: /lib/arm-linux-gnueabihf/libc.so.6: version `GLIBC_2.34' not found (required by /rt/bin/initdb) +``` + +⇒ 在 **glibc 2.28 上已经起不来**。 + +### 2.4 根因定位 + +- `scripts/build-pglite-engine.sh` 用 `gcc-arm-linux-gnueabihf` + `libc6-dev-armhf-cross` 交叉编译引擎; +- `scripts/build-armv7.sh` 的 `ZIG_SYSROOT` 指向 `dist/pglite-engine-armv7/sysroot`; +- 该 sysroot 里的 libc 是 **`Debian GLIBC 2.36-9+deb12u14`**(实测 `strings` 确认)。 + +⇒ 链接时所有符号取 glibc 2.36 的版本节点 ⇒ 最高 `GLIBC_2.34`。 + +### 2.5 上游现有冒烟为什么没发现 + +`build-armv7.sh` 的冒烟用 `arm32v7/debian:bookworm-slim` = **glibc 2.36**, +与编译 sysroot 同版本 ⇒ 天然通过,掩盖了问题。 +**建议把冒烟镜像改成 `arm32v7/debian:buster`(2.28)或更老的 `stretch`(2.24)。** + +## 3. 目标设备基线 + +| 设备 | 架构 | glibc | 备注 | +|---|---|---|---| +| ZYNQ 192.168.1.233 | armv7l | **2.26** | 无 docker,BusyBox,静态二进制唯一可行 | +| 海光 192.168.1.102 | x86_64 | 2.28 | 有 docker,但 glibc 仍低于 2.34 | + +⇒ 引擎必须能在 **glibc 2.26** 上跑(ZYNQ 是硬约束)。 + +## 4. 两条可选修法 + +### 方案 A(推荐):改用 musl 静态,零设备 libc 依赖 + +- 目标三元组改为 `armv7-unknown-linux-musleabihf`; +- `zig cc -target arm-linux-musleabihf -static` 自带 musl libc(zig 0.14.1 已验证); +- 产物完全静态 ⇒ **设备 glibc 版本无关**,ZYNQ 的 2.26 无任何风险; +- 顺带解决「ZYNQ 无 glibc 头文件/运行时」的依赖问题。 + +已本地验证 musl 静态 armv7 二进制在 `arm32v7/debian:buster` 与 `alpine:3.20` 上均正常运行。 + +⚠️ 注意点: +- `relocate-runtime-cross.sh` 里的 `patchelf --set-rpath` 对静态产物无意义,可跳过; +- musl 下 `libpq.so.5` 仍需打进 runtime(`initdb` 依赖它); +- `pglite-rs-sys` 的 `build.rs` 无条件 `-lz`,musl 下 zlib 同样要静态链入。 + +### 方案 B:保留 gnueabihf,但用 ≤ 2.26 的 sysroot + +- 交叉工具链换成 **glibc ≤ 2.26** 的 sysroot(如 Debian 9 stretch armhf / Ubuntu 16.04 armhf); +- 引擎与 Rust 侧二进制都用它链接; +- 优点:与设备 glibc 语义一致,`patchelf`/RPATH 逻辑不变; +- 缺点:sysroot 需自备,且 stretch 的 glibc 无 `dlopen` 新符号问题要一并确认。 + +## 5. 验收标准(上游重编后请逐条自验) + +```bash +# ① 引擎二进制不得要求高于 2.26 的 GLIBC +objdump -T bin/postgres | grep -oE 'GLIBC_2\.[0-9]+' | sort -uV | tail -1 # 期望 ≤ GLIBC_2.26 +objdump -T bin/initdb | grep -oE 'GLIBC_2\.[0-9]+' | sort -uV | tail -1 # 期望 ≤ GLIBC_2.26 + +# ② 在老 glibc 的 armv7 容器里能起 +docker run --rm --platform linux/arm/v7 -v :/rt:ro arm32v7/debian:buster \ + sh -c '/rt/bin/initdb -D /tmp/pg -U check --no-sync -A trust -E UTF8' && echo INITDB_OK + +# ③ 若走方案 A(musl),产物必须是静态 +file bin/postgres | grep -q 'statically linked' && echo STATIC_OK + +# ④ sspf-admin 整体冒烟(老 glibc 容器里起服务 + 探活) +docker run --rm --platform linux/arm/v7 ... arm32v7/debian:buster sh -c '...' +``` + +设备侧我方会再用 `build/check-armv7-runtime.sh` 做最终裁决(读设备 glibc 版本 + 试跑 initdb)。 + +## 6. 不在本次整改范围(但请知悉) + +- `ssw-tds` 侧连接器(含 `tdc-rs`)在 ZYNQ 上是**独立静态二进制**(Go,musl), + 不依赖平台包的 glibc 符号版本 ⇒ 方案 B 落地后即使平台包仍有版本问题, + 连接器本身仍可单独部署; +- 但连接器启动后会拉起本地 PostgreSQL 引擎 ⇒ **引擎必须先修好**,否则连接器起不来。