tuxrun-qemu Docker镜像文档

镜像概述

tuxrun-qemu是一个集成TuxRun工具与QEMU模拟器的Docker镜像，旨在为Linux内核开发者提供便捷、一致的内核测试环境。通过容器化方式封装TuxRun的自动化测试能力与QEMU的多架构模拟功能，无需手动配置复杂依赖，即可快速在模拟环境中验证Linux内核的启动、功能及稳定性。

核心功能特性

• 多架构支持：兼容x86_64、ARMv7、ARM64 (aarch64)、RISC-V等主流架构，满足跨平台内核测试需求。
• 自动化测试流程：内置TuxRun的自动化测试逻辑，支持从内核镜像加载、QEMU实例启动到测试结果收集的全流程自动化。
• 丰富测试场景：覆盖内核启动测试（boot test）、基础功能测试、内核模块加载测试等常见场景，可通过配置扩展自定义测试。
• 轻量级配置：支持通过环境变量或配置文件灵活定义测试参数（如内核路径、根文件系统、模拟硬件配置等），降低使用门槛。
• 标准化结果输出：测试结果以结构化格式（如JSON、TAP）输出，便于集成至CI/CD系统或测试报告工具。

使用场景

• 内核开发测试：内核开发者验证新功能、修复漏洞后的内核镜像在不同架构下的启动与运行状态。
• CI/CD流程集成：作为持续集成环节的一部分，在代码提交后自动触发内核测试，快速反馈质量问题。
• 架构模拟与研究：教育或研究场景中，模拟不同硬件架构环境，学***内核跨平台适配原理。

使用方法

基本使用（docker run）

docker run -it --rm \
  -v /path/to/local/kernel:/kernel \  # 挂载本地内核文件目录
  -v /path/to/rootfs:/rootfs \        # 挂载根文件系统目录（可选，默认使用内置最小根fs）
  -e TARGET_ARCH="x86_64" \           # 指定目标架构（如x86_64、aarch64、riscv64）
  -e KERNEL_IMAGE="/kernel/bzImage" \ # 指定内核镜像路径（容器内路径）
  tuxrun-qemu

环境变量说明

配置参数（命令行）

可通过命令行参数覆盖环境变量配置，格式为--<参数名> <值>，例如：

docker run -it --rm \
  -v /local/kernel:/kernel \
  tuxrun-qemu --arch aarch64 --kernel /kernel/Image --mem 2G --test basic

常用参数：--arch（同TARGET_ARCH）、--kernel（同KERNEL_IMAGE）、--mem（同QEMU_MEM）、--test（同TEST_SCENARIO）。

测试结果查看

测试完成后，结果文件（如results.json、日志文件）将输出至OUTPUT_DIR指定的目录。若需在宿主机查看，可通过-v挂载宿主机目录至OUTPUT_DIR，例如：

docker run -it --rm \
  -v /local/kernel:/kernel \
  -v /local/output:/tuxrun/output \  # 挂载宿主机输出目录
  -e OUTPUT_DIR="/tuxrun/output" \
  tuxrun-qemu

宿主机可在/local/output目录下获取测试结果。

注意事项

• 性能优化：宿主机需启用KVM（如modprobe kvm），并在docker run时添加--device /dev/kvm，以利用硬件加速提升QEMU模拟性能。
• 权限配置：挂载的本地目录需确保容器内用户（默认uid=1000）有读写权限，可通过-u $(id -u):$(id -g)指定宿主机用户ID。
• 架构依赖：部分架构（如RISC-V）可能需要额外QEMU固件支持，可通过-v挂载对应固件至/usr/share/qemu/目录。