Files
ssw-platform/docs/armv7-glibc-compat.md
T
ssw-tds-test 5420c0f4de docs(armv7): 记录 glibc 版本不匹配问题与整改规格
armv7 平台包的引擎用 Debian 12 的 GLIBC 2.36 当 sysroot,符号被绑到
GLIBC_2.34 版本节点,在 glibc 2.28(海光)实测已起不来:
  initdb: libc.so.6: version 'GLIBC_2.34' not found

被抬高版本号的符号本身在 2.26 即存在,故非缺功能而是版本标签问题。
给出两条修法(musl 静态 / 降级 sysroot)与可复现的验收命令。
2026-11-12 20:40:12 +08:00

5.8 KiB
Raw Blame History

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 复现(不需要设备)

docker run --rm --platform linux/arm/v7 -v <rt>:/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. 验收标准(上游重编后请逐条自验)

# ① 引擎二进制不得要求高于 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>:/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 引擎 ⇒ 引擎必须先修好,否则连接器起不来。