最近在追龙架构双周会的一手资料时发现大部分内容都分散在境外技术社区的原始发布和邮件列表里对于国内开发者来说既需要时间翻译又需要整理上下文。本文不打算逐字翻译第 7 期的会议内容而是把龙架构的学习路径整理成一份可落地的工程笔记从指令集背景讲到 QEMU 模拟运行、交叉编译、Docker 多架构构建再到常见坑点排查。无论你是系统软件开发者、嵌入式工程师还是准备把服务迁移到龙架构平台的运维同学都可以按这篇文章的思路动手跑一遍。我会尽量用“最小可运行”的方式来组织内容先讲清楚龙架构是什么再搭环境再写代码最后给出排错清单和工程建议。文章里涉及的代码和命令都给出完整示例但版本信息需要结合你实际使用的发行版和工具链做微调关键地方我会标注清楚。1. 背景与核心概念1.1 什么是龙架构龙架构是龙芯中科推出的自主指令系统架构英文名是 LoongArch。它和 x86、ARM 一样属于 CPU 的指令集架构层面决定了 CPU 能够识别和执行哪些机器指令。从技术定位来看LoongArch 是一套 RISC 风格的指令集包含基础指令集和扩展指令集两部分。基础指令集覆盖整数运算、访存、分支跳转、函数调用等核心能力扩展指令集包括向量计算、二进制翻译加速、虚拟化支持等内容。相比传统 CISC 风格指令集RISC 风格的指令编码更规整硬件实现和编译器后端开发相对直接。龙架构的特别之处在于指令系统自主设计而不是基于某个外部指令集改造而来。同时它提供了一定的指令兼容策略旧型号的龙芯处理器主要兼容 MIPS 指令而使用 LoongArch 的新一代处理器可以通过二进制翻译机制运行 x86、ARM 等架构的应用形成“自主指令集 翻译兼容”的软件生态路径。对于开发者来说龙架构真正需要关注的不只是 CPU 本身而是三层内容一是指令集手册二是工具链GCC、LLVM、binutils三是操作系统和基础软件适配。这三层缺一环业务软件就很难真正落地。1.2 龙架构与 x86/ARM 的关键差异很多读者会问龙架构和 x86、ARM 有什么本质区别我们从一个软件工程师的角度来对比。x86 是典型 CISC 指令集指令长短不一历史包袱重但生态成熟Windows、Linux 和大量商业软件都围绕它适配。ARM 是移动端和嵌入式领域的主导者功耗控制优秀指令集相对简洁但授权模式对芯片厂商有较高门槛。LoongArch 作为较新的指令集设计在编码上有后发优势。例如指令编码长度相对规整基础指令集的分组清晰编译器后端更容易做优化。它不像 x86 那样需要兼容几十年前的指令行为也没有 ARM 复杂的指令集切换状态。但“架构新”也意味着生态需要从零积累。一台龙架构服务器能不能跑起业务不仅取决于 CPU 快不快还取决于操作系统内核是否支持、GCC 是否能生成针对性的优化代码、OpenJDK 是否有对应构建、数据库和中间件是否有适配版本。所以在学习龙架构时我建议不要把注意力只放在“指令长什么样”上而是建立“指令集 ABI 操作系统 基础软件”的整体视角。这样在排查问题时才知道问题到底出在编译阶段、内核支持阶段还是运行库缺失阶段。1.3 双周会关注什么龙架构双周会通常围绕主线内核、GCC/LLVM 工具链、二进制翻译、基础软件适配、测试验证等话题展开。第 7 期的时间是 2026 年 8 月 6 日讨论内容一般会涉及上游补丁的合入情况、社区版本的状态、新的适配进展和后续计划。对普通开发者来说这类会议的价值在于了解龙架构生态的“当前水位”哪些组件已经稳定支持哪些还处于实验阶段哪些方向需要有人投入贡献。本文不会逐字复述会议议程而是从技术层面梳理一套你可以自己动手验证的路径这样去看下一期资料时理解成本会低很多。2. 环境准备与版本说明2.1 硬件与系统选择学习龙架构环境有三种常见方式成本从高到低排列方式优点缺点适用场景真实龙架构主机性能真实行为最准确成本高采购周期长生产环境验证、性能测试云主机/服务器弹性获取多人共享不是所有云平台都提供团队 CI、长期开发QEMU 模拟零硬件成本可快速体验性能偏弱启动较慢学习入门、交叉验证对于第一遍学习我建议优先使用 QEMU 模拟因为不需要额外购买设备而且可以随时重装系统不用担心把环境弄坏。如果你所在团队已经在龙架构服务器上跑业务那就直接在真实机器上操作效果更好。操作系统方面龙架构生态里有专门面向该平台的 Loongnix、Loongnix-Server也有统信 UOS、麒麟等桌面/服务器系统的龙架构版本。社区里还常见基于 Debian、openEuler 等发行版衍生的 LoongArch 移植版本。具体用哪一个取决于你后续要跑什么软件以及团队熟悉哪套管理体系。版本信息这里需要特别说明龙架构的软件生态变化较快不同发行版的内核、GCC、QEMU 版本差异较大。本文示例以较新的发行版环境为目标重点演示配置思路如果你的环境版本较老可能需要先升级工具链或内核。2.2 工具链与 QEMU 版本建议在写代码之前需要准备以下工具# 查看当前系统架构 uname -m # 查看 GCC 是否支持 loongarch 后端 gcc -v 21 | grep -i loongarch如果你在 x86 主机上做交叉编译需要安装龙架构交叉编译工具链。不同发行版包名不一样常见的有# Debian/Ubuntu 风格示例具体包名以发行版为准 sudo apt install gcc-loongarch64-linux-gnu binutils-loongarch64-linux-gnu # 或者使用 QEMU 用户态模拟器 sudo apt install qemu-user qemu-user-static binfmt-support如果是 RHEL/CentOS 风格的系统包名可能不同建议先搜索仓库yum search loongarchQEMU 的版本很关键。运行龙架构用户态程序建议使用 QEMU 8.0 及以上版本因为对 LoongArch 的支持是逐步完善的。太老的 QEMU 可能无法识别loongarch64目标或者运行时报指令不支持。如果发行版自带的 QEMU 太旧可以选择从源码编译但这不是本文的重点。2.3 示例项目结构说明为了后面实战部分不混乱建议先建立一个统一目录loongarch-lab/ ├── hello/ │ ├── hello.c │ └── Makefile ├── sysroot/ │ └── (交叉编译用的根文件系统) └── scripts/ └── build-hello.shhello目录放第一个最小程序sysroot目录用于存放目标系统的动态库和头文件scripts目录放构建脚本。目录结构不复杂但提前规划可以避免交叉编译时把目标系统的库和宿主系统的库混在一起。3. 核心原理拆解3.1 指令集的分层结构LoongArch 指令集不是单一的一张大表而是分层的结构。对于应用开发者我们大多数时候不直接写汇编但理解分层有助于阅读反汇编、排查崩溃问题。最底层是基础整数指令包括算术运算、逻辑运算、移位、比较、跳转、访存等。往上是扩展指令集包括扩展类别作用向量扩展提供 SIMD 能力适合多媒体和高性能计算二进制翻译扩展加速 x86/ARM 应用翻译虚拟化扩展支持虚拟化场景加密扩展提供常用密码学指令加速在编译普通 C/C 程序时GCC 会根据-march参数决定使用哪些扩展指令。例如gcc -marchloongarch64 -O2 -o hello hello.c如果不指定-march编译器会采用默认的基础配置。在性能敏感场景需要根据实际 CPU 型号传递合理参数这就需要查阅龙芯处理器对应的 CPU 配置编号。3.2 ABI 与寄存器约定ABI即应用二进制接口是“编译器生成的程序”和“操作系统”之间的契约。它规定了函数参数怎么传、返回值放哪里、栈怎么管理、寄存器怎么分配。LoongArch 64 位 ABI 使用 32 个通用寄存器每个寄存器 64 位。常见的寄存器约定如下寄存器别名作用$r0$zero恒为 0$r1$ra返回地址$r2$tp线程指针$r3$sp栈指针$r4-$r11$a0-$a7函数参数$r12-$r20$t0-$t8临时寄存器$r21-$r31$s0-$s8 等保存寄存器函数调用时前 8 个参数使用$a0到$a7传递超过 8 个参数的部分通过栈传递。返回值使用$a0。这些规则看起来枯燥但排查疑难 bug 时非常有用。例如当你看到一个崩溃日志显示pc指向某个奇怪地址而$ra是无效值时往往意味着函数返回地址被破坏这并不是 Java/Python 层面的问题而是底层运行库或者 JIT 代码的问题。3.3 二进制翻译与兼容运行龙架构生态里经常提到二进制翻译即让非 LoongArch 架构的程序也能在龙架构机器上运行。其核心思路是在用户态拦截程序的指令流把 x86、ARM 指令翻译成 LoongArch 指令同时维护模拟的寄存器状态和内存视图。二进制翻译有两类常见形态形态工作方式特点解释执行逐条翻译并执行简单但慢动态二进制翻译以基本块为单位翻译并缓存性能更高实现复杂在实际系统中二进制翻译通常作为一个用户态运行库提供应用启动时通过加载器或容器注入翻译层。这样做的优势是不需要修改原始应用缺点是性能有额外开销而且对指令集覆盖率要求高遇到新指令组合可能出现兼容问题。对开发者来说二进制翻译适合“过渡期”或“少量低频应用”的场景。在正式生产环境尤其是性能敏感的业务更推荐使用原生编译版本。3.4 软件适配全景图龙架构的软件适配可以从纵向层次来看应用层业务程序、中间件、数据库客户端 基础软件层OpenJDK、Python、GCC、glibc、systemd 操作系统层Linux 内核、发行版工具链、驱动 硬件层龙芯 CPU 平台每一层都有对应的工作。操作系统层解决内核启动、驱动、中断等基础问题基础软件层解决编译器和运行时库的适配应用层则是业务团队投入最多的地方。对普通业务开发者来说一个比较现实的建议是先确认你使用的编程语言运行时是否支持龙架构再确认中间件和数据库是否有对应构建最后才是业务代码的兼容性测试。比如 Java 应用需要先确认所用 OpenJDK 发行版是否提供 loongarch64 版本Python 应用需要确认解释器、C 扩展库是否都有对应的 wheel 包。如果基础层不满足业务代码写得再标准也无法运行。4. 完整实战从编译到运行4.1 用 QEMU 运行一个龙架构系统如果你手头没有龙架构硬件最简单的方式是用 QEMU 系统模拟启动一个龙架构 Linux。这里给出一个思路性流程具体命令取决于你使用的发行版镜像。首先需要准备 Linux 内核镜像和根文件系统镜像一般可以从发行版官网的 LoongArch 目录下载。然后使用 QEMU 启动qemu-system-loongarch64 \ -m 2G \ -smp 2 \ -kernel vmlinux \ -drive filerootfs.img,formatraw \ -append root/dev/sda rw consolettyS0 \ -nographic启动后你会进入系统 shell。这种方式适合跑一个完整的发行版验证内核、驱动、软件包管理是否正常。缺点是启动时间较长而且 QEMU 模拟性能远低于真实硬件不适合做性能测试。4.2 原生编译并运行 C 程序进入龙架构系统后先写一个最小的 C 程序。这里用getauxval读取内核传递给用户程序的平台信息可以直观看到当前架构标识。// 文件路径hello/hello.c #include stdio.h #include sys/auxv.h int main(void) { printf(Hello LoongArch\n); printf(execfn: %s\n, (char *)getauxval(AT_EXECFN)); printf(platform: %s\n, (char *)getauxval(AT_PLATFORM)); return 0; }在系统里编译运行gcc -O2 -o hello hello.c ./hello预期输出大致是Hello LoongArch execfn: ./hello platform: loongarch64如果你的系统缺失sys/auxv.h说明基础开发库没装完整需要先安装build-essential或对应开发包。这段代码虽然简单但验证了三件事编译器可正常工作、内核能加载动态链接器、基础 C 库能提供系统调用封装。4.3 交叉编译与用户态模拟很多读者手头只有 x86 机器这时候可以借助交叉编译工具链和 QEMU 用户态模拟器在 x86 上编译并运行龙架构程序。交叉编译的意思是在 x86 主机上运行编译器但生成的目标文件是 loongarch64 架构的。编译命令如下loongarch64-linux-gnu-gcc -O2 -static -o hello-loongarch hello.c注意这里用了-static把依赖库静态链接进可执行文件这样在 QEMU 用户态模拟运行时不需要指定目标系统的动态库路径。如果你不使用-static就需要用-L指定 sysroot或者通过qemu-loongarch64 -L /path/to/sysroot指定根文件系统。编译完成后用 QEMU 用户态运行qemu-loongarch64 ./hello-loongarch输出结果和在真实龙架构系统上运行基本一致。用户态模拟并不需要启动完整的内核它只模拟 CPU 指令和系统调用接口因此启动速度很快非常适合做编译结果的冒烟验证。4.4 查看运行结果与反汇编运行成功后可以用以下命令确认二进制架构和代码特征file hello-loongarch正常情况下你会看到类似ELF 64-bit LSB executable, LoongArch 64-bit, version 1...如果想更深入地理解编译器生成的指令可以用交叉 objdump 反汇编loongarch64-linux-gnu-objdump -d hello-loongarch | head -50在反汇编输出里你会看到addi.d、st.d、bl等典型 LoongArch 指令。这些指令对应 C 代码中的栈操作和函数调用阅读时结合 3.2 小节的寄存器约定可以快速理解调用过程。4.5 Docker 多架构构建示例在实际工程中我们常用 Docker 构建多架构镜像。要让 Docker 构建出龙架构镜像需要在构建机上注册 QEMU binfmt 处理器。# 注册 qemu-user-static 到 binfmt docker run --rm --privileged multiarch/qemu-user-static --reset -p yes # 创建 buildx 构建器 docker buildx create --name loongarch-builder --use # 构建并推送 loong64 架构镜像 docker buildx build --platform linux/loong64 -t your-registry/hello:loong64 --push .其中linux/loong64是龙架构在 Docker Platform 中的常见标识具体是否支持要看 Docker 版本和构建环境。构建时Docker 会先通过 QEMU 在 x86 机器上执行 loong64 二进制这个过程对上层是透明的体验和多架构构建基本一致。这里要提醒一下multiarch/qemu-user-static镜像需要从外部镜像仓库拉取如果网络环境受限可以考虑在内部镜像仓库预先同步该镜像。5. 常见问题与排查思路5.1 问题汇总表问题现象常见原因解决思路gcc: error: unrecognized command-line option编译器版本过旧不支持 LoongArch 后端升级 GCC或安装交叉编译工具链Exec format error当前系统无法识别 loong64 可执行文件格式安装 qemu-user、注册 binfmt或改用真实龙架构机器qemu-loongarch64: Could not open /lib/ld.so.1用户态模拟未指定目标系统的动态库路径编译时使用-static或用-L指定 sysroot内核启动卡住无输出内核参数或根文件系统路径错误检查-append参数确认 root 设备名Docker buildx 构建失败缺少 QEMU binfmt 注册或平台标识不支持重新注册 qemu-user-static确认--platform写法动态链接触发段错误sysroot 与目标系统库版本不一致使用发行版提供的统一 sysroot不要混用多个版本5.2 交叉编译找不到头文件这个问题很常见。交叉编译时stdio.h、stdlib.h这些头文件必须来自目标系统的 sysroot而不是 x86 主机本地的/usr/include。如果直接使用宿主 gcc 的 include 路径会出现两种结果要么报找不到头文件要么编译通过但运行崩溃。排查步骤如下# 查看交叉编译器默认的 sysroot loongarch64-linux-gnu-gcc -print-sysroot # 查看编译器搜索路径 loongarch64-linux-gnu-gcc -E -x c - -v /dev/null如果默认路径里没有目标头文件需要手动指定loongarch64-linux-gnu-gcc --sysroot/path/to/sysroot -I/path/to/sysroot/usr/include ...这里再次建议最小示例使用-static从源头规避动态库搜索路径问题。5.3 运行阶段提示找不到共享库如果你编译时没有加-static在qemu-loongarch64运行时会提示找不到.so文件。这不能简单靠把 x86 上的库复制过来解决因为架构不同。正确做法是准备一个目标系统的根文件系统目录里面包含lib、usr/lib下的动态库。然后用以下方式运行qemu-loongarch64 -L /path/to/loongarch-rootfs ./hello-dynamic使用-L参数表示将指定目录作为模拟的根目录动态链接器会从该目录下搜索共享库。对于复杂的项目我建议用发行版自带的 debootstrap 或容器导出方式生成完整 sysroot避免手工拷贝漏文件。5.4 二进制翻译后程序卡死或闪退如果你在龙架构系统上通过二进制翻译运行 x86 程序遇到卡死或闪退优先考虑三类原因原因类型典型表现建议翻译层版本过旧新指令集组合不识别升级二进制翻译运行时应用使用了不常见系统调用调用后无响应检查是否可以用原生版本替代CPU 特性检测异常程序误判指令集能力检查是否通过cpucfg暴露特性这类问题没有通用“银弹”需要结合日志和崩溃栈逐层分析。一个务实的建议是优先寻找原生版本而不是把所有希望寄托在翻译层。6. 最佳实践与工程建议6.1 优先原生构建二进制翻译兜底龙架构生态越来越成熟常见语言运行时和基础软件已经有不少原生支持。对生产项目优先使用原生构建版本原因有三性能更稳定、排错更简单、社区支持更完整。二进制翻译适合“临时应急”或“长尾工具”不建议作为核心业务的长期方案。在实际选型时可以按这个顺序检查编程语言运行时是否提供 loong64 原生包比如 OpenJDK、Python、Node.js基础库是否有对应平台构建比如 OpenSSL、zlib、libxml2最后才是业务应用自身的兼容性。6.2 建立统一的交叉编译环境如果团队开始做龙架构适配我强烈建议不要靠个人机器上零散安装的工具链而是维护一套统一的环境。具体落地方式在 CI 服务器上准备固定版本的交叉编译工具链。使用统一的 sysroot基于目标发行版 rootfs 生成。将所有依赖锁定到具体版本避免不同成员环境不一致。用 Docker 镜像固化编译环境保证构建可重复。一个最小化的构建脚本示例#!/usr/bin/env bash # 文件路径scripts/build-hello.sh set -euo pipefail TOOLCHAINloongarch64-linux-gnu SYSROOT/opt/loongarch-sysroot ${TOOLCHAIN}-gcc \ --sysroot${SYSROOT} \ -O2 \ -o hello-loongarch \ hello/hello.c qemu-loongarch64 -L ${SYSROOT} ./hello-loongarch将构建脚本纳入版本库后续任何人都可以复现同一份构建结果。6.3 架构适配清单在一个真实项目中适配龙架构不能只编译一个测试程序就算完成需要做系统性核对。推荐建立一份检查清单检查项说明内核版本确认操作系统内核支持 LoongArch且包涵所需驱动编译工具链确认 GCC/Clang 版本及-march优化参数运行环境确认 glibc、OpenJDK、Python 等版本第三方依赖逐个确认 C/C 库是否有 loong64 版本数据库与中间件确认连接驱动和客户端库可用性部署脚本检查脚本中的架构判断逻辑避免硬编码 x86_64监控与日志确认采集器、日志客户端有对应平台构建这些内容看起来琐碎但通常才是适配工作的主体。6.4 CI 与多架构镜像龙架构适配进入常态化后可以考虑把多架构构建接入 CI。常见的做法是使用 Docker Buildx 同时构建 amd64、arm64、loong64 镜像然后推送到同一个镜像仓库。这样业务方拉取镜像时Docker 会根据节点架构自动选择对应平台。构建前需要确认三件事构建机已注册 QEMU binfmt镜像仓库支持多架构 manifest依赖的基础镜像存在对应平台版本。如果基础镜像没有 loong64 版本多架构构建就会失败这时候需要先从基础镜像层做适配。6.5 安全与权限边界无论做什么平台的适配安全边界都不能放松。如果涉及生产环境部署权限要保持最小化只授予必要角色的必要权限。对于数据库、配置中心、密钥管理等组件要使用独立的账号和凭据避免在构建脚本中硬编码密钥。如果涉及系统级参数调整需要在测试环境充分验证后再发布变更前做好备份和回滚方案。这一点在龙架构适配初期尤为重要因为新平台的环境差异可能引入隐蔽问题规范变更流程能降低风险。7. 总结与学习路线这篇笔记从龙架构的背景概念开始讲到了指令集分层、ABI 约定、二进制翻译和软件适配全景图然后带大家走了一遍 QEMU 模拟、原生编译、交叉编译和 Docker 多架构构建的完整流程。相信你跟着操作后对龙架构不再只是一个模糊的新闻关键词而是有了亲手编译和运行的经验。下一步学习可以分成三条线。第一条线是深入指令集本身阅读 LoongArch 官方手册重点看基础指令的编码格式和典型汇编示例第二条线是参与系统软件适配可以尝试把一个小型 C 项目交叉编译到龙架构并修复编译问题第三条线是关注社区动态跟踪双周会的补丁合入情况了解内核和工具链的最新状态。在实际项目中优先关注的是基础软件层的版本兼容性而不是急着优化业务代码。只要 OpenJDK、Python、数据库客户端这些基础组件能在龙架构上稳定运行上层业务移植的难度会大大降低。如果你在操作过程中遇到报错欢迎在评论区带上完整输出一起分析。下一期我可以继续整理龙架构的启动流程、内核裁剪或者 Java 应用迁移实战大家可以根据自己的方向留言选择。动手跑通一遍比收藏十篇文章更有价值。