跳转到内容
OpenOS

快速开始

环境要求

Section titled “环境要求”
工具版本用途
Rust nightly1.99+#![feature(abi_x86_interrupt)]、build-std
QEMU8.xx86_64 系统模拟
NASM2.16+汇编器（用户空间程序）
Python 33.xmkinitrd.py 工具

安装依赖

Section titled “安装依赖”
Terminal window
# Rust nightly
rustup install nightly
rustup component add rust-src llvm-tools-preview clippy rustfmt --toolchain nightly


# 系统包
sudo apt install nasm lld llvm qemu-system-x86 gdb-multiarch python3

获取源码

Section titled “获取源码”
Terminal window
git clone https://github.com/openos/openos.git
cd openos

构建流程

Section titled “构建流程”

OpenOS 使用四步构建流程：

1. nasm + ld      → 用户空间 ELF 程序
2. mkinitrd.py    → initrd 归档
3. cargo build    → 内核二进制
4. cargo run      → BIOS 磁盘镜像

一键构建

Section titled “一键构建”
Terminal window
make build

此命令将：

  1. 汇编 user/hello.asm 和 user/console_svc.asm
  2. 创建 target/debug/initrd.img
  3. 编译内核
  4. 创建 BIOS 磁盘镜像

分步构建

Section titled “分步构建”
Terminal window
# 1. 构建用户空间程序
make user


# 2. 构建 initrd
make initrd


# 3. 构建内核 + 磁盘镜像
make build

运行

Section titled “运行”

串口输出（推荐）

Section titled “串口输出（推荐）”
Terminal window
make run

输出示例：

=================================
  OpenOS Microkernel v0.3.0
=================================


[...] Initializing IPC subsystem
[OK] IPC subsystem initialized
[...] Initializing task scheduler
[OK] Task scheduler initialized
[OK] Kernel initialization complete
[...] Ramdisk loaded (12984 bytes)
[...] Channel: handle_a=0x103ff00000001, handle_b=0x103ff00000002
[...] Kernel sent message to channel
[...] Launching console service (user-space)
[SYSCALL] channel_receive: got 31 bytes
Hello from user-space service!


[SYS_EXIT] status=0
[OK] Kernel halted

图形显示

Section titled “图形显示”
Terminal window
make run-gui

GDB 调试

Section titled “GDB 调试”
Terminal window
make debug

在另一个终端：

Terminal window
gdb-multiarch target/x86_64-unknown-none/debug/openos-kernel
(gdb) target remote :1234
(gdb) break kernel_main
(gdb) continue

常用命令

Section titled “常用命令”
命令说明
make build构建内核 + initrd + 磁盘镜像
make release优化构建
make runQEMU 串口输出
make run-guiQEMU 图形显示
make debugQEMU + GDB
make checkfmt + clippy + build
make lintclippy 检查
make fmt格式检查
make test运行测试
make clean清理构建产物
make user构建用户空间程序
make initrd构建 initrd

项目结构

Section titled “项目结构”
openos/
├── Cargo.toml              # 工作区配置
├── Makefile                # 构建脚本
├── kernel/                 # 内核 crate
│   └── src/
│       ├── main.rs         # 内核入口
│       ├── handle.rs       # Handle/Rights 系统
│       ├── ipc/            # Channel IPC
│       ├── syscall/        # 系统调用分发
│       ├── task/           # 任务管理
│       ├── elf.rs          # ELF 加载器
│       ├── initrd.rs       # initrd 解析器
│       └── ...
├── user/                   # 用户空间程序
│   ├── hello.asm           # 发送消息示例
│   └── console_svc.asm     # Console 服务
├── tools/
│   └── mkinitrd.py         # initrd 创建工具
└── src/
    └── main.rs             # 磁盘镜像构建器

用户空间程序

Section titled “用户空间程序”

hello.asm

Section titled “hello.asm”

发送消息到 Channel，然后退出：

BITS 64
SECTION .text


global _start


_start:
    mov rbx, rdi                ; 保存 handle_a


    ; channel_send(handle_a, msg, len)
    mov rdi, rbx
    lea rsi, [rel msg]
    mov rdx, msg_len
    mov rax, 0x02               ; SYS_CHANNEL_SEND
    syscall


    ; process_exit(0)
    mov rdi, 0
    mov rax, 0x32               ; SYS_PROCESS_EXIT
    syscall


SECTION .rodata
msg:     db "Hello from initrd!", 10
msg_len equ $ - msg

console_svc.asm

Section titled “console_svc.asm”

接收消息，打印到串口，回复 “OK”，退出：

BITS 64
SECTION .text


global _start


_start:
    mov rbx, rdi                ; 保存 handle (end B)


    ; channel_receive(handle, buf, 256)
    mov rdi, rbx
    lea rsi, [rel buf]
    mov rdx, 256
    mov rax, 0x03               ; SYS_CHANNEL_RECEIVE
    syscall


    ; console_write(buf, len)
    mov rcx, rax
    lea rdi, [rel buf]
    mov rsi, rcx
    mov rax, 0xF0               ; SYS_CONSOLE_WRITE
    syscall


    ; channel_reply(handle, "OK", 2)
    mov rdi, rbx
    lea rsi, [rel ok_msg]
    mov rdx, 2
    mov rax, 0x05               ; SYS_CHANNEL_REPLY
    syscall


    ; process_exit(0)
    mov rdi, 0
    mov rax, 0x32               ; SYS_PROCESS_EXIT
    syscall


SECTION .bss
buf:    resb 256


SECTION .rodata
ok_msg: db "OK"

故障排除

Section titled “故障排除”

编译错误

Section titled “编译错误”

问题: error[E0658]: feature not stable 解决: 确保使用 nightly：rustup default nightly

问题: cannot find -lld 解决: 安装 LLD：sudo apt install lld

QEMU 问题

Section titled “QEMU 问题”

问题: QEMU 无法启动 解决: 确保安装 qemu-system-x86

问题: 无串口输出 解决: 检查是否使用 make run

下一步

Section titled “下一步”