Introduction

本文记录了笔者学习 rCore Tutorial Book 第二章的过程,内容包括

  1. 生成用户程序镜像
  2. 在 qemu-riscv64 上测试用户程序
  3. 将用户程序镜像链接到 ELF 中
  4. 将即将运行的用户程序镜像加载到目标地址 const APP_BASE_ADDRESS: usize = 0x80400000
  5. 实现特权级切换、Trap、系统调用并执行用户程序
  6. 练习:sys_write 安全检查

相关链接如下

Rust The Programming Language 环境配置说明

rCore Tutorial Book

rCore 官方仓库

建议使用的 RustSBI 镜像

git clone https://github.com/rcore-os/rCore-Tutorial-v3.git
git checkout ch2

RustSBI 官方仓库

原理:特权级机制

RISC-V 架构中一共定义了 4 种特权级

级别编码名称
000用户/应用模式 (U, User/Application)
101监督模式 (S, Supervisor)
210虚拟监督模式 (H, Hypervisor)
311机器模式 (M, Machine)
物理 RISC-V CPU
│
├── M-Mode → RustSBI
│
├── S-Mode → rCore
│
└── U-Mode → 用户程序

Hypervisor 和虚拟机有关

                    物理 CPU
                       │
                    M-Mode
                       │
                    OpenSBI
                       │
                    S-Mode
                       │
                  Hypervisor
                       │
             ┌─────────┴─────────┐
             ↓                   ↓
          VS-Mode             VS-Mode
             │                   │
         Guest OS 1           Guest OS 2
             │                   │
          VU-Mode             VU-Mode
             │                   │
          App 1                App 2

一般而言,用户程序通过 ecall 触发处理器异常来跳转到 CSR 中的 stvec 指定的位置一般是 trap 处理的入口并切换状态到 S-Mode ,S-Mode 的内核同样也可以执行 ecall 来进行类似的操作,切换到 M-Mode 并跳转到 mtvec 指定的位置。返回时,mret 能够跳转到 mepc 的地址,而在触发异常时 mepc 会自动保存,返回也会自动从 M-Mode 切换回 S-Mode ,同样的 sret 会跳转到 sepc 指定的地址,并切换回 U-Mode.

trap 函数中通常可以访问 scause 和 stval 来判断造成异常/中断的原因,更多特权寄存器说明详见 RISC-V 手册

中译 RISC-V手册

八个控制状态寄存器(CSR)是机器模式下异常处理的必要部分:
- mtvec(Machine Trap Vector)它保存发生异常时处理器需要跳转到的地址。 
- mepc(Machine Exception PC)它指向发生异常的指令。 
- mcause(Machine Exception Cause)它指示发生异常的种类。 
- mie(Machine Interrupt Enable)它指出处理器目前能处理和必须忽略的中断。 
- mip(Machine Interrupt Pending)它列出目前正准备处理的中断。 
- mtval(Machine Trap Value)它保存了陷入(trap)的附加信息:地址例外中出错的地址、发生非法指令例外的指令本身,对于其他异常,它的值为0。 
- mscratch(Machine Scratch)它暂时存放一个字大小的数据。 
- mstatus(Machine Status)它保存全局中断使能,以及许多其他的状态,如图10.4 所示。 

实现用户程序

设计实现被批处理系统逐个加载并运行的应用程序至少需要考虑下面的问题

  1. 应用程序的内存布局
  2. 应用程序发出的系统调用
    • 应用程序的代码不能超过 U-Mode 的限制,如有必要,使用系统调用

而在操作系统一侧,则需要完成异常/中断的处理以及系统调用功能的实现,当应用程序使用非法指令/非法访问内存时,需要杀死进程。

用户程序的目录结构

在仓库中存放用户程序的 user 文件目录如下

user
├── Cargo.lock
├── Cargo.toml
├── Makefile
└── src
    ├── bin
    │   ├── 00hello_world.rs
    │   ├── 01store_fault.rs
    │   ├── 02power.rs
    │   ├── 03priv_inst.rs
    │   └── 04priv_csr.rs
    ├── console.rs
    ├── lang_items.rs
    ├── lib.rs
    ├── linker.ld
    └── syscall.rs

9 directories, 35 files

其中,user/src/bin 目录下的就是待执行的用户程序,而 *.rs 则是用户库,linker.ld 是内存布局说明,一个普通的 00hello_world.rs 如下

#![no_std]
#![no_main]

#[macro_use]
extern crate user_lib;

#[unsafe(no_mangle)]
fn main() -> i32 {
    println!("Hello, world!");
    0
}

其中大部分看起来都跟第一章的裸机程序差不多,比如 #![no_std], #![no_main], #[unsafe(no_mangle)], 而 #[macro_use] 引入了外部库 user_lib,也就是 user/src/*.rs 那些库。至于为什么是 user_lib,这是 user/Cargo.toml 中定义的名字:

[package]
name = "user_lib"
version = "0.1.0"
authors = ["Yifan Wu <shinbokuow@163.com>"]
edition = "2024"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
riscv = { version = "0.16", features = ["s-mode"] }

[profile.release]
debug = true

# [features]
# board_qemu = []
# board_k210 = []

用户库入口

在 lib.rs 中定义了用户库的入口 _start

unsafe extern "Rust" {
    fn main() -> i32;
}

#[unsafe(no_mangle)]
#[unsafe(link_section = ".text.entry")]
pub extern "C" fn _start() -> ! {
    clear_bss();
    unsafe {
        exit(main());
    }
    panic!("unreachable after sys_exit!");
}

这里新出现的 #[unsafe(link_section = ".text.entry")] 将 _start 这段代码编译后的汇编代码放在一个名为 .text.entry 的代码段中。而 main 则由 user/src/bin 下面的应用程序提供。

对应的 linker.ld 中调整了内存布局,起始地址设置成了 0x80400000 ,并且入口设置成了 _start,可以看到 .text 的第一部分就是所谓的 .text.entry 也就是 _start,后面 PC 只要跳到这里就可以开始执行 _start 的指令。需要注意的是,内核代码和用户库代码是分开编译的,这里的 _start 和第一章的 _start 是两个函数,编译出来的不是同一份 ELF.

OUTPUT_ARCH(riscv)
ENTRY(_start)

BASE_ADDRESS = 0x80400000;

SECTIONS
{
    . = BASE_ADDRESS;
    .text : {
        *(.text.entry)
        *(.text .text.*)
    }
    .rodata : {
        *(.rodata .rodata.*)
        *(.srodata .srodata.*)
    }
    .data : {
        *(.data .data.*)
        *(.sdata .sdata.*)
    }
    .bss : {
        start_bss = .;
        *(.bss .bss.*)
        *(.sbss .sbss.*)
        end_bss = .;
    }
    /DISCARD/ : {
        *(.eh_frame)
        *(.debug*)
    }
}

系统调用

查看 user/src/syscall.rs 代码如下

use core::arch::asm;

const SYSCALL_WRITE: usize = 64;
const SYSCALL_EXIT: usize = 93;

fn syscall(id: usize, args: [usize; 3]) -> isize {
    let mut ret: isize;
    unsafe {
        asm!(
            "ecall",
            inlateout("x10") args[0] => ret,
            in("x11") args[1],
            in("x12") args[2],
            in("x17") id
        );
    }
    ret
}

pub fn sys_write(fd: usize, buffer: &[u8]) -> isize {
    syscall(SYSCALL_WRITE, [fd, buffer.as_ptr() as usize, buffer.len()])
}

pub fn sys_exit(exit_code: i32) -> isize {
    syscall(SYSCALL_EXIT, [exit_code as usize, 0, 0])
}

这里 x10 到 x17 分别对应了寄存器 a0 至 a7,而 a7 便是存储系统调用号的寄存器,a0 到 a2 则是传递参数用的,同时 a0 也是存储返回值的寄存器。

in("x11") args[1] 表示将输入参数 args[1] 绑定到 ecall 的输入寄存器 x11 即 a1 中,编译器自动插入相关指令并保证在 ecall 指令被执行之前寄存器 a1 的值与 args[1] 相同。而 inlateout 则告诉编译器这个寄存器既是输入,也会在输出用到。

对 syscall 进行封装就得到了 sys_write 和 sys_exit 函数,进一步封装得到应用程序可以直接调用的 write() 和 exit()

// lib.rs
pub fn write(fd: usize, buf: &[u8]) -> isize {
    sys_write(fd, buf)
}
pub fn exit(exit_code: i32) -> isize {
    sys_exit(exit_code)
}

编译生成

在 user 目录下输入命令 make build 即可在 target/riscv64gc-unknown-none-elf/release 目录下生成一个同名的 ELF 可执行文件以及裁切后的二进制镜像文件,Makefile 相关内容如下

elf:
    @cargo build --release

binary: elf
    @$(foreach elf, $(ELFS), $(OBJCOPY) $(elf) --strip-all -O binary $(patsubst $(TARGET_DIR)/%, $(TARGET_DIR)/%.bin, $(elf));)

build: binary
sodium@nas-MacBook-Air-13 user % ls target/riscv64gc-unknown-none-elf/release 
00hello_world           01store_fault.bin       02power.d               04priv_csr              deps                    libuser_lib.rlib
00hello_world.bin       01store_fault.d         03priv_inst             04priv_csr.bin          examples
00hello_world.d         02power                 03priv_inst.bin         04priv_csr.d            incremental
01store_fault           02power.bin             03priv_inst.d           build                   libuser_lib.d

随便查看一个 ELF 的反汇编文件,可以看到 _start 被放到了 0x80400000

sodium@nas-MacBook-Air-13 user % rust-objdump -S target/riscv64gc-unknown-none-elf/release/00hello_world | grep -C 10 "_start"

target/riscv64gc-unknown-none-elf/release/00hello_world:        file format elf64-littleriscv

Disassembly of section .text:

0000000080400000 <_start>:
80400000: 1141          addi    sp, sp, -0x10
80400002: e406          sd      ra, 0x8(sp)
80400004: e022          sd      s0, 0x0(sp)
80400006: 0800          addi    s0, sp, 0x10

0000000080400008 <.Lpcrel_hi14>:
80400008: 00001517      auipc   a0, 0x1

000000008040000c <.Lpcrel_hi15>:
8040000c: 00001597      auipc   a1, 0x1

可以看到后面的符号名称都很奇怪,这就是必须要在 _start 这里使用 #[unsafe(no_mange)] 的原因,否则链接器找不到符号。

在 qemu-riscv64 上测试用户程序

qemu-riscv64 是一个直接支持运行 RISC-V 64 用户程序的半系统模拟器,它实际上是一个 RISC-V 架构下的 Linux 操作系统。使用的系统调用号、参数约定什么的是和 rCore 一致的,所以可以直接在这上面测试运行写好的用户程序。相比之下,qemu-system-riscv64 则是模拟了一台 RISC-V 64 裸机。

只需要执行下面的命令即可,这里 ./03priv_inst 是 ELF 文件,源码是 user/src/bin/03priv_inst.rs,内容是尝试执行一条特权指令 sret

qemu-riscv64 ./03priv_inst

在项目根目录执行 make build_docker (在 macOS 上需要先启动 OrbStack ) 和 make docker 后即可执行上面的命令

root@b9d77c863c4f:/mnt# qemu-riscv64 ./user/target/riscv64gc-unknown-none-elf/release/00hello_world
Hello, world!
root@b9d77c863c4f:/mnt# qemu-riscv64 ./user/target/riscv64gc-unknown-none-elf/release/03priv_inst  
Try to execute privileged instruction in U Mode
Kernel should kill this application!
Illegal instruction
root@b9d77c863c4f:/mnt# 

前面两行 Try... 和 Kernel... 是应用程序打印的信息,只有 Illegal instruction 是系统打印的信息,随后进程被杀死了。

实现批处理操作系统

在这一节中,需要实现将用户程序加载到内存中并让其运行在用户态。

将用户程序镜像链接到内核的数据段

在 os/src/main.rs 中有这样一行

global_asm!(include_str!("link_app.S"));

这相当于在 main.rs 的代码中插入了一份汇编代码—— link_app.S ,其内容如下

    .align 3
    .section .data
    .global _num_app
_num_app:
    .quad 5
    .quad app_0_start
    .quad app_1_start
    .quad app_2_start
    .quad app_3_start
    .quad app_4_start
    .quad app_4_end

    .section .data
    .global app_0_start
    .global app_0_end
app_0_start:
    .incbin "../user/target/riscv64gc-unknown-none-elf/release/00hello_world.bin"
app_0_end:

    .section .data
    .global app_1_start
    .global app_1_end
app_1_start:
    .incbin "../user/target/riscv64gc-unknown-none-elf/release/01store_fault.bin"
app_1_end:

    .section .data
    .global app_2_start
    .global app_2_end
app_2_start:
    .incbin "../user/target/riscv64gc-unknown-none-elf/release/02power.bin"
app_2_end:

    .section .data
    .global app_3_start
    .global app_3_end
app_3_start:
    .incbin "../user/target/riscv64gc-unknown-none-elf/release/03priv_inst.bin"
app_3_end:

    .section .data
    .global app_4_start
    .global app_4_end
app_4_start:
    .incbin "../user/target/riscv64gc-unknown-none-elf/release/04priv_csr.bin"
app_4_end:

其中

  • .align 3 通常表示按 8 字节对齐
  • .section .data 是表示切换到名为 .data 的 section
  • .global _num_app 表示 _num_app 全局可见,下一行定义了 _num_app 标签,表示当前位置的地址。
  • .quad 5 表示在镜像的当前位置写入一个 64 位(8 字节)的值,这里放的是整数 5 ,应该是表示有五个用户程序

这里的做法是把多个独立编译出来的用户程序,直接嵌入内核的 ELF 文件中,并生成一张记录它们位置的表。

app_X_start, app_X_end 就是镜像文件的原始字节。而前面的 .quad app_X_start 则是存储了这些镜像内容的起始地址。

找到并加载程序

封装 AppManager

os/src/batch.rs 中定义了结构体 AppManager

struct AppManager {
    num_app: usize,                         // app 的数量
    current_app: usize,                     // 目前的 app
    app_start: [usize; MAX_APP_NUM + 1],    // app 的起始位置
}
impl AppManager {
    pub fn print_app_info(&self) {...}      // 打印了 app 数量

    fn load_app(&self, app_id: usize) {...} // 

    pub fn get_current_app(&self) -> usize {
        self.current_app
    }
    pub fn move_to_next_app(&mut self) {    // 注意这里是可修改的引用类型
        self.current_app += 1;
    }
}

因为 current_app 需要修改,所以整个结构体实例只能定义为 mut ,Rust The Programming Book 原文如下

Rust doesn’t allow us to mark only certain fields as mutable. As with any expression, we can construct a new instance of the struct as the last expression in the function body to implicitly return that new instance.

Defining and Instantiating Structs

但是将 AppManager 实例定义为全局可修改变量并不是一个安全的做法。所以需要声明一个初始化之后就不可变的变量,来包裹这样一个可变的变量。

我们通常使用 RefCell 包裹可被借用的值,随后调用 borrow 和 borrow_mut 便可发起借用并获得一个对值的不可变/可变借用的标志,它们可以像引用一样使用。为了终止借用,我们只需手动销毁这些标志或者等待它们被自动销毁。

use std::cell::RefCell;
fn main() {
    let a: RefCell<i32> = RefCell::new(3);
    *a.borrow_mut() = 4;
    println!("{}", a.borrow());
}

打印结果就是 4

但是将 RefCell 声明为全局变量会报错,因为 rust 编译器假定了全局变量会被并发访问,所以还需要再封装一层 UPSafeCell 让其在单核上能够正常编译运行,并安全地使用。

// os/src/sync/up.rs
use core::cell::{RefCell, RefMut};

pub struct UPSafeCell<T> {
    inner: RefCell<T>,
}

unsafe impl<T> Sync for UPSafeCell<T> {}

impl<T> UPSafeCell<T> {
    pub unsafe fn new(value: T) -> Self {
        Self {
            inner: RefCell::new(value),
        }
    }
    pub fn exclusive_access(&self) -> RefMut<'_, T> {
        self.inner.borrow_mut()
    }
}
  • core:Rust 的核心库,不依赖操作系统提供的标准库环境。rCore 使用 #![no_std],因此不能像普通应用一样随意使用 std。

  • cell:提供内部可变性相关的类型。

  • RefCell<T>:允许通过不可变引用 &self 获取内部数据的可变借用,但在运行时检查借用规则。

  • RefMut<T>:表示通过 RefCell 获得的可变借用。

  • unsafe impl<T> Sync for UPSafeCell<T> {} 表示为泛型类型 UPSafeCell<T> 实现 Sync trait

    • 这里意味着程序员手动向 Rust 编译器承诺:UPSafeCell<T> 满足 Sync 的安全要求。
  • exclusive_access 函数封装了 borrow_mut 函数

  • RefMut<'_, T> 是返回类型

    • RefMut:代表可变借用的守卫对象。
    • T:被借用的数据类型。
    • '_:由编译器推断的生命周期,关联于这次方法调用所借用的 self。
  • unsafe 在 new 这里是依靠使用者自己来保证访问内部数据时首先调用 exclusive_access 获得数据的可变借用标记,通过它可以完成数据的读写,在操作完成之后我们需要销毁这个标记,此后才能开始对该数据的下一次访问。相比 RefCell 它不再允许多个读操作同时存在。

  • 另一个 unsafe 则是向编译器承诺这一类型不会引发并发问题,而检查功能保证了内存安全

初始化 AppManager

lazy_static! {
    static ref APP_MANAGER: UPSafeCell<AppManager> = unsafe {
        UPSafeCell::new({
            unsafe extern "C" {
                safe fn _num_app();
            }
            let num_app_ptr = linker_symbol_addr!(_num_app) as *const usize;
            let num_app = num_app_ptr.read_volatile();
            let mut app_start: [usize; MAX_APP_NUM + 1] = [0; MAX_APP_NUM + 1];
            let app_start_raw: &[usize] =
                core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1);
            app_start[..=num_app].copy_from_slice(app_start_raw);
            AppManager {
                num_app,
                current_app: 0,
                app_start,
            }
        })
    };
}
  • lazy_static! 是一个宏,用于声明延迟初始化的静态变量。
    • 普通的 static 通常要求初始值能够在编译期确定;但这里的初始化过程包含读取链接符号、访问指针、复制地址表等运行时操作,不能简单地写成普通的编译期常量初始化.
    • lazy_static! 会生成相应的初始化机制,使变量在第一次被访问时才初始化,并确保初始化过程受到同步保护。
  • let mut app_start: [usize; MAX_APP_NUM + 1] = [0; MAX_APP_NUM + 1];
    • 这行代码创建一个长度为 MAX_APP_NUM + 1 的 usize 数组,并把所有元素初始化为 0。
    • 最后一个应用也需要一个结束地址,所以加一
  • core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1);
    • 从 num_app_ptr 后面的第一个 usize 开始,把连续的 num_app + 1 个元素视为一个只读切片。
  • app_start[..=num_app].copy_from_slice(app_start_raw);
    • ..=num_app:包含右边界。..num_app:不包含右边界
    • 执行后 app_start:[app_0_start, app_1_start, app_2_start, app_3_start, app_4_start, app_4_end, 0, ...]

需要注意的是使用 lazy_static! 宏需要添加依赖

# os/Cargo.toml

[dependencies]
lazy_static = { version = "1.4.0", features = ["spin_no_std"] }

让 AppManager 加载用户程序

impl AppManager {
    ...
    fn load_app(&self, app_id: usize) {
        if app_id >= self.num_app {
            println!("All applications completed!");
            shutdown(false);
        }
        println!("[kernel] Loading app_{}", app_id);
        unsafe {
            // clear app area
            core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, APP_SIZE_LIMIT).fill(0);
            let app_src = core::slice::from_raw_parts(
                self.app_start[app_id] as *const u8,
                self.app_start[app_id + 1] - self.app_start[app_id],
            );
            let app_dst =
                core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, app_src.len());
            app_dst.copy_from_slice(app_src);
            asm!("fence.i");
        }
    }
}

load_app 程序首先通过 from_raw_parts_mut 清空了 APP_BASE_ADDRESS 为起点,长度为 APP_SIZE_LIMIT 的内存区域,然后读取 app_start 数组来获取应用程序镜像的起始位置和结束位置,并且将这部分复制到了起点为 APP_BASE_ADDRESS 为起点的内存中。这里的 unsafe 主要是因为函数直接操作了原始指针和指定内存地址,Rust 编译器无法自动证明这些操作是安全的。

最后 fence.i 指令的功能是保证在它之后的取指过程必须能够看到在它之前的所有对于取指内存区域的修改,避免取到错误的指令。

特权级切换

当 CPU 执行完一条指令(如 ecall )并准备从用户特权级 陷入( Trap )到 S 特权级的时候,硬件会自动完成如下这些事情:

  • sstatus 的 SPP 字段会被修改为 CPU 当前的特权级(U/S)。
  • sepc 会被修改为被中断或触发异常的指令的地址。如 CPU 执行 ecall 指令会触发异常,则 sepc 会被设置为 ecall 指令的地址。
  • scause/stval 分别会被修改成这次 Trap 的原因以及相关的附加信息。
  • CPU 会跳转到 stvec 所设置的 Trap 处理入口地址,并将当前特权级设置为 S ,然后从Trap 处理入口地址处开始执行。
  • sret 具体完成以下功能:
    • CPU 会将当前的特权级按照 sstatus 的 SPP 字段设置为 U 或者 S ;
    • CPU 会跳转到 sepc 寄存器指向的那条指令,然后继续执行。
对比项DirectVectored
stvec.MODE01
同步异常入口BASEBASE
中断入口BASEBASE + 4 × cause
是否需要统一分派通常需要中断可以直接分流
实现难度较简单需要布置中断向量入口

上下文保存

用户程序经过 ecall 进入 trap 之后,需要将寄存器状态保存在内核栈而非用户栈,这是为了安全起见。

rCore 声明了两个类型 KernelStack 和 UserStack 分别表示内核栈和用户栈,它们都只是字节数组的简单包装:

// os/src/batch.rs
const USER_STACK_SIZE: usize = 4096 * 2;
const KERNEL_STACK_SIZE: usize = 4096 * 2;
#[repr(align(4096))]
struct KernelStack {
    data: [u8; KERNEL_STACK_SIZE],
}

#[repr(align(4096))]
struct UserStack {
    data: [u8; USER_STACK_SIZE],
}

static KERNEL_STACK: KernelStack = KernelStack {
    data: [0; KERNEL_STACK_SIZE],
};
static USER_STACK: UserStack = UserStack {
    data: [0; USER_STACK_SIZE],
};

impl KernelStack {
    fn get_sp(&self) -> usize {
        self.data.as_ptr() as usize + KERNEL_STACK_SIZE
    }
    pub fn push_context(&self, cx: TrapContext) -> &'static mut TrapContext {
        let cx_ptr = (self.get_sp() - core::mem::size_of::<TrapContext>()) as *mut TrapContext;
        unsafe {
            *cx_ptr = cx;
        }
        unsafe { cx_ptr.as_mut().unwrap() }
    }
}

impl UserStack {
    fn get_sp(&self) -> usize {
        self.data.as_ptr() as usize + USER_STACK_SIZE
    }
}

两个类型是以全局变量的形式实例化在批处理操作系统的 .bss 段中的。

上下文保存时,为了避免嵌套 Trap 把需要使用的 sstatus, sepc 覆盖掉,所以它们也需要保存。而 scause 和 stval 一般会第一时间就使用完,无需保存。

// os/src/trap/context.rs
use riscv::register::sstatus::{self, SPP, Sstatus};
/// Trap Context
#[repr(C)]                      // 确保 Rust 结构体在内存中的字段布局符合预期,使汇编代码能够按照固定偏移访问各个字段。
pub struct TrapContext {
    /// general regs[0..31]
    pub x: [usize; 32],
    /// CSR sstatus      
    pub sstatus: Sstatus,
    /// CSR sepc
    pub sepc: usize,
}

impl TrapContext {
    /// set stack pointer to x_2 reg (sp)
    pub fn set_sp(&mut self, sp: usize) {
        self.x[2] = sp;
    }
    /// init app context
    pub fn app_init_context(entry: usize, sp: usize) -> Self {
        let mut sstatus = sstatus::read(); // CSR sstatus
        sstatus.set_spp(SPP::User); //previous privilege mode: user mode
        let mut cx = Self {
            x: [0; 32],
            sstatus,
            sepc: entry, // entry point of app
        };
        cx.set_sp(sp); // app's user stack pointer
        cx // return initial Trap Context of app
    }
}

在 C 中,结构体字段按照声明顺序排列本来就是语言层面的保证;而 Rust 默认不提供这一保证,需要通过 #[repr(C)] 显式要求采用 C 兼容的布局规则。

这里通过设置 SSP 为 U,sepc 为用户程序的开始地点能够让第一次执行 sret 时开始执行用户程序

Trap 管理

处理完 sepc, sstatus 以及上下文之后现在还需要初始化 stvec

// os/src/trap/mod.rs
mod context;

use crate::batch::run_next_app;
use crate::syscall::syscall;
use core::arch::global_asm;
use riscv::interrupt::{Exception, Interrupt, Trap};
use riscv::register::{mtvec::TrapMode, scause, stval, stvec};

global_asm!(include_str!("trap.S"));

/// initialize CSR `stvec` as the entry of `__alltraps`
pub fn init() {
    unsafe extern "C" {
        safe fn __alltraps();
    }
    unsafe {
        stvec::write(stvec::Stvec::new(
            linker_symbol_addr!(__alltraps),
            TrapMode::Direct,
        ));
    }
}

这里的外部符号 __alltraps 就是 trap.S 中的入口

# os/src/trap/trap.S

.altmacro
.macro SAVE_GP n
    sd x\n, \n*8(sp)
.endm
.macro LOAD_GP n
    ld x\n, \n*8(sp)
.endm
    .section .text
    .globl __alltraps
    .globl __restore
    .align 2
__alltraps:
    csrrw sp, sscratch, sp
    # now sp->kernel stack, sscratch->user stack
    # allocate a TrapContext on kernel stack
    addi sp, sp, -34*8
    # save general-purpose registers
    sd x1, 1*8(sp)
    # skip sp(x2), we will save it later
    sd x3, 3*8(sp)
    # skip tp(x4), application does not use it
    # save x5~x31
    .set n, 5
    .rept 27
        SAVE_GP %n
        .set n, n+1
    .endr
    # we can use t0/t1/t2 freely, because they were saved on kernel stack
    csrr t0, sstatus
    csrr t1, sepc
    sd t0, 32*8(sp)
    sd t1, 33*8(sp)
    # read user stack from sscratch and save it on the kernel stack
    csrr t2, sscratch
    sd t2, 2*8(sp)
    # set input argument of trap_handler(cx: &mut TrapContext)
    mv a0, sp
    call trap_handler

__restore:
    # case1: start running app by __restore
    # case2: back to U after handling trap
    mv sp, a0
    # now sp->kernel stack(after allocated), sscratch->user stack
    # restore sstatus/sepc
    ld t0, 32*8(sp)
    ld t1, 33*8(sp)
    ld t2, 2*8(sp)
    csrw sstatus, t0
    csrw sepc, t1
    csrw sscratch, t2
    # restore general-purpuse registers except sp/tp
    ld x1, 1*8(sp)
    ld x3, 3*8(sp)
    .set n, 5
    .rept 27
        LOAD_GP %n
        .set n, n+1
    .endr
    # release TrapContext on kernel stack
    addi sp, sp, 34*8
    # now sp->kernel stack, sscratch->user stack
    csrrw sp, sscratch, sp
    sret

这里和 xv6 一样使用了 sscratch 来存储额外的数据,这里是存储了 kernel stack 的地址,保存了除了 x4 以外的全部通用寄存器以及 sstatus 和 sepc。恢复时,除了恢复通用寄存器以外,还将 kernel stack 的高位边界地址写入到了 sscratch 中。

现在看 call trap_handler 的目标地址,进入前,a0 传入的值来自于 sp,也就是 TrapContext 的低位边界地址

// os/src/trap/mod.rs
use riscv::interrupt::{Exception, Interrupt, Trap};
use riscv::register::{mtvec::TrapMode, scause, stval, stvec};

#[unsafe(no_mangle)]
/// handle an interrupt, exception, or system call from user space
pub fn trap_handler(cx: &mut TrapContext) -> &mut TrapContext {
    let scause = scause::read(); // get trap cause
    let stval = stval::read(); // get extra value
    let trap: Trap<Interrupt, Exception> = match scause.cause().try_into() {
        Ok(trap) => trap,
        Err(_) => panic!(
            "Unsupported trap {:?}, stval = {:#x}!",
            scause.cause(),
            stval
        ),
    };
    match trap {
        Trap::Exception(Exception::UserEnvCall) => {
            cx.sepc += 4;
            cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize;
        }
        Trap::Exception(Exception::StoreFault) | Trap::Exception(Exception::StorePageFault) => {
            println!("[kernel] PageFault in application, kernel killed it.");
            run_next_app();
        }
        Trap::Exception(Exception::IllegalInstruction) => {
            println!("[kernel] IllegalInstruction in application, kernel killed it.");
            run_next_app();
        }
        _ => {
            panic!("Unsupported trap {:?}, stval = {:#x}!", trap, stval);
        }
    }
    cx
}
pub use context::TrapContext;

正常的 trap_handler 完成时,传入的 a0 和传出的 a0 是一样的,都是 TrapContext 的地址。

这里出现的 cause() 和 try_into() 是为了转换类型用的

  • scause: Scause
  • cause():返回 Trap<usize, usize>
  • try_info():返回 Result<Trap<Interrupt, Exception>>

随后就可以使用 match 匹配异常类型

为了使用 riscv 库,需要

# os/Cargo.toml

[dependencies]
riscv = { version = "0.16", features = ["s-mode"] }

系统调用功能

// os/src/syscall/mod.rs
const SYSCALL_WRITE: usize = 64;
const SYSCALL_EXIT: usize = 93;

mod fs;
mod process;
use fs::*;
use process::*;

/// handle syscall exception with `syscall_id` and other arguments
pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize {
    match syscall_id {
        SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]),
        SYSCALL_EXIT => sys_exit(args[0] as i32),
        _ => panic!("Unsupported syscall_id: {}", syscall_id),
    }
}

syscall 根据系统调用号和参数调用不同的函数

// os/src/syscall/fs.rs
//! File and filesystem-related syscalls

const FD_STDOUT: usize = 1;

/// write buf of length `len`  to a file with `fd`
pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize {
    match fd {
        FD_STDOUT => {
            let slice = unsafe { core::slice::from_raw_parts(buf, len) };
            let str = core::str::from_utf8(slice).unwrap();
            print!("{}", str);
            len as isize
        }
        _ => {
            panic!("Unsupported fd in sys_write!");
        }
    }
}
// os/src/syscall/process.rs
//! App management syscalls
use crate::batch::run_next_app;

/// task exits and submit an exit code
pub fn sys_exit(exit_code: i32) -> ! {
    println!("[kernel] Application exited with code {}", exit_code);
    run_next_app()
}

执行应用程序

从前面的分析可以得到,要执行应用程序,实际上需要初始化完成之后进入 __restore,并且设置传入值为内核栈地址

在从操作系统内核返回到运行应用程序之前,要完成如下这些工作:

  1. 构造应用程序开始执行所需的 Trap 上下文;
  2. 通过 __restore 函数,从刚构造的 Trap 上下文中,恢复应用程序执行的部分寄存器;
  3. 设置 sepc CSR的内容为应用程序入口点 0x80400000;
  4. 切换 scratch 和 sp 寄存器,设置 sp 指向应用程序用户栈;
  5. 执行 sret 从 S 特权级切换到 U 特权级。
/// run next app
pub fn run_next_app() -> ! {
    let mut app_manager = APP_MANAGER.exclusive_access();
    let current_app = app_manager.get_current_app();
    app_manager.load_app(current_app);
    app_manager.move_to_next_app();
    drop(app_manager);
    // before this we have to drop local variables related to resources manually
    // and release the resources
    unsafe extern "C" {
        unsafe fn __restore(cx_addr: usize);
    }
    unsafe {
        __restore(KERNEL_STACK.push_context(TrapContext::app_init_context(
            APP_BASE_ADDRESS,
            USER_STACK.get_sp(),
        )) as *const _ as usize);
    }
    panic!("Unreachable in batch::run_current_app!");
}

sys_write 安全检查

实验练习中要求为 sys_write 增加安全检查

在 os 目录下执行 make run TEST=1 测试 sys_write 安全检查的实现,正确执行目标用户测例,并得到预期输出(详见测例注释)。

注意:如果设置默认 log 等级,从 lab2 开始关闭所有 log 输出。

因为没有看到测例注释,所以这里只是让 sys_write 返回负一,代码如下

// fs.rs
/// write buf of length `len`  to a file with `fd`
use crate::batch::check_legal_address;

pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize {
    if !check_legal_address(buf as usize, len) {
        log::error!(
            "[sys_write] illegal addr: buf={:#x}, len={:#x}",
            buf as usize,
            len
        );
        return -1;
    }
    match fd {
        FD_STDOUT => {
            let slice = unsafe { core::slice::from_raw_parts(buf, len) };
            let str = core::str::from_utf8(slice).unwrap();
            print!("{}", str);
            len as isize
        }
        _ => {
            panic!("Unsupported fd in sys_write!");
        }
    }
}
// batch.rs
/// check if the addr is user legal addr
pub fn check_legal_address(addr: usize, len: usize) -> bool {
    let Some(end) = addr.checked_add(len) else {
        return false;
    };
    let app_manager = APP_MANAGER.exclusive_access();
    let current_app = app_manager.current_app - 1;
    let start_addr = APP_BASE_ADDRESS;
    let end_addr = APP_BASE_ADDRESS + app_manager.app_start[current_app + 1]
        - app_manager.app_start[current_app];
    drop(app_manager);
    let stack_start = USER_STACK.data.as_ptr() as usize;
    let stack_end = USER_STACK.get_sp();
    (addr >= start_addr && end <= end_addr) || (end <= stack_end && addr >= stack_start)
}

三条斜杠是文档注释,#![deny(missing_docs)] 要求公共接口必须有文档注释

下面是 GPT 生成的测试代码

// 05test_sys_write.rs
#![no_std]
#![no_main]

#[macro_use]
extern crate user_lib;
use core::arch::asm;
const SYS_WRITE: usize = 64;

fn raw_sys_write(fd: usize, buf: *const u8, len: usize) -> isize {
    let ret: isize;
    unsafe {
        asm!(
            "ecall",
            inlateout("x10") fd => ret,
            in("x11") buf as usize,
            in("x12") len,
            in("x17") SYS_WRITE,
        );
    }
    ret
}

#[unsafe(no_mangle)]
fn main() -> i32 {
    println!("=== sys_write address check test ===");

    // Test 1:合法静态字符串
    let msg = b"Hello from static data!\n";
    let ret = raw_sys_write(1, msg.as_ptr(), msg.len());
    println!("[Test 1] return = {}", ret);

    // Test 2:合法用户栈缓冲区
    let stack_buf = *b"STACK_OK\n";
    let ret = raw_sys_write(1, stack_buf.as_ptr(), stack_buf.len());
    println!("[Test 2] return = {}", ret);

    // Test 3:零长度缓冲区
    let ret = raw_sys_write(1, msg.as_ptr(), 0);
    println!("[Test 3] return = {}", ret);

    // Test 4:整数溢出
    let ret = raw_sys_write(1, usize::MAX as *const u8, 16);
    println!("[Test 4] return = {}", ret);

    // Test 5:明显非法的地址
    let ret = raw_sys_write(1, 0x1000 as *const u8, 8);
    println!("[Test 5] return = {}", ret);

    // Test 6:合法起始地址,但请求长度超出应用程序边界
    //
    // 使用当前应用程序末尾之前的地址作为起点,
    // 让请求范围跨过 APP_END。
    //
    // 该测试只有在内核先做完整范围检查、拒绝非法请求,
    // 且不解引用 buf 时才是安全的。
    const APP_END: usize = 0x80401268;
    let buf = (APP_END - 4) as *const u8;
    let ret = raw_sys_write(1, buf, 8);
    println!("[Test 6] return = {}", ret);

    println!("=== tests finished ===");
    0
}

输出如下

test

同样的测试程序也可以跑在 qemu-riscv64 上

sodium@nas-MacBook-Air-13 rCore-Tutorial-v3 % make docker
docker run --rm -it -v /Users/sodium/Developer/rust/rCore-Tutorial-v3:/mnt -w /mnt --name rcore-tutorial-v3 rcore-tutorial-v3:latest bash
root@3d74d6c5ce79:/mnt# qemu-riscv64 ./user/target/riscv64gc-unknown-none-elf/release/05test_sys_write
=== sys_write address check test ===
Hello from static data!
[Test 1] return = 24
STACK_OK
[Test 2] return = 9
[Test 3] return = 0
[Test 4] return = -14
[Test 5] return = -14
cea 2026[Test 6] return = 8
=== tests finished ===
root@3d74d6c5ce79:/mnt# 

这里 Test 6 被判定成了用户合法 VA,而两个错误返回的是错误码

附录

异常一览表

Code异常含义rCore 中常见程度
0Instruction address misaligned指令地址未对齐★
1Instruction access fault指令访问错误★
2Illegal instruction非法指令★★★
3Breakpoint断点★★
4Load address misalignedLoad 地址未对齐★
5Load access faultLoad 访问错误★★
6Store/AMO address misalignedStore/AMO 地址未对齐★
7Store/AMO access faultStore/AMO 访问错误★★
8Environment call from U-modeU-mode 执行 ecall★★★★★
9Environment call from S-modeS-mode 执行 ecall★
10Reserved保留—
11Environment call from M-modeM-mode 执行 ecall★
12Instruction page fault指令页错误★★★
13Load page faultLoad 页错误★★★
14Reserved保留—
15Store/AMO page faultStore/AMO 页错误★★★