sysprog21/elfuse

来源：https://github.com/sysprog21/elfuse

elfuse

直接从 macOS shell 运行 Linux ELF 二进制文件 —— 无需 Docker、无需完整虚拟机镜像、无需守护进程。elfuse 是一个进程级 Linux 用户空间运行时：每个来宾程序运行在一个轻量级的 Hypervisor.framework 虚拟机中，该虚拟机由 elfuse 进程自身拥有，Linux 系统调用由宿主机端处理器转换为 macOS 行为，而非由真正的 Linux 内核提供服务。

原生 aarch64-linux 直接在 CPU 上执行。x86_64-linux 通过同一虚拟机内 Apple 内置的 Rosetta 翻译器执行；架构会从 ELF 头部自动检测。支持静态链接和动态链接的来宾程序，动态链接器通过 --sysroot 指向外部系统根目录进行解析。

特性

• 单个原生 macOS 二进制文件（约 560 KiB 已签名），无需守护进程和磁盘镜像
• 毫秒级 VM 启动；单次系统调用的开销为微秒级
• 通过 Hypervisor.framework 实现原生 Apple Silicon 执行
• 静态和动态链接的 aarch64-linux ELF 二进制文件
• 通过 Apple Rosetta 实现静态和动态链接的 x86_64-linux ELF 二进制文件（从 ELF 头部自动检测，可使用 --no-rosetta 选项关闭）
• Linux 风格的进程、线程（与 HVF vCPU 1:1 对应，最多 64 个）、信号、定时器、futex（包括 PI 操作）和轮询
• 来宾程序直接读写 macOS 文件系统；无覆盖层或卷挂载层
• 模拟的 /proc 和选定的 /dev 设备，用于用户空间探测
• 来宾内部 FUSE：无需 macFUSE / FUSE-T / FSKit，即可使用 /dev/fuse 和 mount("fuse")
• 内置 GDB 远程串行协议存根，可从 gdb 或 lldb 使用
• 自包含的测试矩阵，可交叉校验 elfuse 与 QEMU，并执行独立的 Rosetta 验收测试套件

定位

elfuse 刻意保持专精范围。它运行单个 Linux 二进制文件（及其 fork/exec 子进程），开销极低；但它不承载 Linux 内核、命名空间、cgroup 或内核模块。对于需要完整内核特性、容器编排或 systemd 的工作负载，建议使用完整的虚拟机工具（如 Lima、UTM、OrbStack）或 Docker Desktop。对于单二进制工具、语言运行时、测试框架和调试器驱动的工作流程，elfuse 消除了这些工具带来的磁盘镜像和启动时间开销。

要求

• macOS 运行在 Apple Silicon 上
• macOS 13 或更新版本
• Xcode Command Line Tools、clang、codesign 和 GNU make
• GNU objcopy 或 llvm-objcopy
• Hypervisor 授权：com.apple.security.hypervisor

如果仅构建（make elfuse）而不运行测试，只需 Xcode Command Line Tools 和 objcopy（brew install binutils）。

对于来宾测试二进制文件，该项目还需要一个 AArch64 Linux 交叉工具链。mk/toolchain.mk 中的默认路径针对仓库测试套件使用的工具链布局，但 CROSS_COMPILE 和 BAREMETAL_CROSS 是可覆盖的。

请参阅 docs/testing.md 了解工具链设置指南。

快速开始

git clone https://github.com/sysprog21/elfuse
cd elfuse
make elfuse
make test-busybox
build/elfuse build/busybox

将 build/busybox 替换为 aarch64-linux 或 x86_64-linux 可执行文件。来宾架构会从 ELF 头部自动检测。

对于动态链接的来宾程序：

build/elfuse --sysroot /path/to/sysroot ./path/to/program

对于 x86_64-linux 来宾程序，Rosetta 默认启用。要禁用它：

build/elfuse --no-rosetta ./path/to/aarch64-only-binary

用于早期调试：

build/elfuse --gdb 1234 --gdb-stop-on-entry ./path/to/program

对于 x86_64 来宾程序，--gdb 会被拒绝，因为存根提供的是 Rosetta 产生的 aarch64 视图，而非原始 x86_64 架构状态。

构建过程会在使用前对 build/elfuse 进行签名。需要时可通过 SIGN_IDENTITY="Developer ID ..." 覆盖签名身份。

文档

• docs/usage.md：命令行选项、通过 Rosetta 运行 x86_64、通过 --sysroot 进行动态链接，以及将 gdb/lldb 附加到内置存根。
• docs/testing.md：构建前提、make check 流程、QEMU 和 Rosetta 交叉校验矩阵，以及测试夹具处理。
• docs/internals.md：权威技术参考 —— 运行时生命周期、HVF 约束、EL1 垫片和 HVC 协议、页表拆分、系统调用翻译表、线程/ futex、fork/clone IPC、信号、ptrace 和 GDB 存根。

构建与验证

最常用的目标：

make elfuse        # 构建并签名 build/elfuse
make check         # 快速单元测试套件 + BusyBox 应用冒烟测试
make test-gdbstub  # 调试器集成测试
make test-matrix   # 对同一测试集交叉校验 elfuse 与 QEMU
make lint          # clang-tidy 静态分析

make check 是推荐的提交前把关测试。make test-matrix 是涉及 procfs、动态链接、网络或进程语义修改时的推荐把关测试。make test-rosetta-all 单独覆盖 x86_64 验收测试套件。请参阅 docs/testing.md 获取完整目标列表、测试夹具流程以及按修改类型验证的指导。

限制

elfuse 运行单个 Linux 用户空间进程（及其 fork/exec 子进程）。它并非 Linux 内核。这一框架既决定了它能做什么，也明确了它明确不会做什么。

• 没有用户空间系统调用对应的 Linux 内核特性：命名空间、cgroup、内核模块、eBPF、io_uring、KVM、perf 事件。
• 不支持 Intel Mac。仅限 Apple Silicon（M1 及更新版本）。
• 不在来宾内部承载虚拟机。来宾无法使用 HVF 或 KVM。
• 每个 elfuse 宿主机进程对应一个来宾进程树。HVF 允许每个宿主机进程一个虚拟机；Linux 风格的 fork 通过 posix_spawn 启动一个新的 elfuse 宿主机进程并传递状态来实现（参见 docs/internals.md）。
• 每个虚拟机最多 64 个并发来宾线程（MAX_THREADS = 64）。
• 实现了约 213 个系统调用；任何不在 src/syscall/dispatch.tbl 中的调用都会返回 -ENOSYS，而非静默成功。
• FUTEX_LOCK_PI 及相关操作表现为普通的互斥锁获取/释放；未模拟真正的优先级继承调度。
• sched_setaffinity 被当作无操作（返回全 CPU 掩码）；实际 CPU 由宿主机调度器选择。
• /proc、/dev 和挂载数据是模拟的兼容性视图，并非宿主机透传。

许可证

Apache License 2.0。参见 LICENSE。

Copyright 2026 elfuse 贡献者
Copyright 2025 Moritz Angermann, zw3rk pte. Ltd.