From e57b24e4d4fb933d3658f76dca16d0c48f907878 Mon Sep 17 00:00:00 2001 From: ayanami Date: Wed, 25 Sep 2024 15:36:58 +0800 Subject: [PATCH] docs(Lab4, Lab5): split README.md and integrated with current pages framework. Reviewed-by: Yiyang Wu Signed-off-by: Yiyang Wu --- Pages/Lab4.md | 16 +++++ Pages/Lab4/IPC.md | 54 +++++++++++++++ Pages/Lab4/assets/IPC-overview.png | Bin 0 -> 43964 bytes Pages/Lab4/multicore.md | 27 ++++++++ Pages/Lab4/performance.md | 35 ++++++++++ Pages/Lab4/scheduler.md | 105 +++++++++++++++++++++++++++++ Pages/Lab5.md | 8 +++ Pages/Lab5/FSM.md | 58 ++++++++++++++++ Pages/Lab5/base.md | 85 +++++++++++++++++++++++ Pages/SUMMARY.md | 9 +++ 10 files changed, 397 insertions(+) create mode 100644 Pages/Lab4.md create mode 100644 Pages/Lab4/IPC.md create mode 100644 Pages/Lab4/assets/IPC-overview.png create mode 100644 Pages/Lab4/multicore.md create mode 100644 Pages/Lab4/performance.md create mode 100644 Pages/Lab4/scheduler.md create mode 100644 Pages/Lab5.md create mode 100644 Pages/Lab5/FSM.md create mode 100644 Pages/Lab5/base.md diff --git a/Pages/Lab4.md b/Pages/Lab4.md new file mode 100644 index 00000000..46e9a981 --- /dev/null +++ b/Pages/Lab4.md @@ -0,0 +1,16 @@ +# Lab 4：多核调度与IPC + +在本实验中，ChCore将支持在多核处理器上启动（第一部分）；实现多核调度器以调度执行多个线程（第二部分）；最后实现进程间通信IPC（第三部分）。注释`/* LAB 4 TODO BEGIN (exercise #) */`和`/* LAB 4 TODO END (exercise #) */`之间代表需要填空的代码部分。 + +## Preparation + +实验 4 与实验 3相同，需要在根目录下拉取 `musl-libc` 代码。 + +>```bash +> git submodule update --init --recursive +>``` + +使用 `make build` 检查是否能够正确项目编译。 + +> [!WARNING] +> 请确保成功拉取`musl-libc`代码后再尝试进行编译。若未成功拉取`musl-libc`就进行编译将会自动创建`musl-libc`文件夹，这可能导致无法成功拉取`musl-libc`代码，也无法编译成功。出现此种情况可以尝试将`user/chcore-libc/musl-libc`文件夹删除，并运行以上指令重新拉取代码。 diff --git a/Pages/Lab4/IPC.md b/Pages/Lab4/IPC.md new file mode 100644 index 00000000..6d5bcc5f --- /dev/null +++ b/Pages/Lab4/IPC.md @@ -0,0 +1,54 @@ +# 进程间通信（IPC） + + + +在本部分，我们将实现ChCore的进程间通信，从而允许跨地址空间的两个进程可以使用IPC进行信息交换。 + +## ChCore进程间通讯概览 +![](./assets/IPC-overview.png) + +ChCore的IPC接口不是传统的send/recv接口。其更像客户端/服务器模型，其中IPC请求接收者是服务器，而IPC请求发送者是客户端。 服务器进程中包含三类线程: +* 主线程：该线程与普通的线程一样，类型为`TYPE_USER`。该线程会调用`ipc_register_server`将自己声明为一个IPC的服务器进程，调用的时候会提供两个参数:服务连接请求的函数client_register_handler和服务真正IPC请求的函数server_handler（即图中的`ipc_dispatcher`），调用该函数会创建一个注册回调线程; + +* 注册回调线程：该线程的入口函数为上文提到的client_register_handler，类型为`TYPE_REGISTER`。正常情况下该线程不会被调度执行，仅当有Client发起建立IPC连接的请求时，该线程运行并执行client_register_handler，为请求建立连接的Client创建一个服务线程（即图中的IPC handler thread）并在服务器进程的虚拟地址空间中分配一个可以用来映射共享内存的虚拟地址。 + +* 服务线程：当Client发起建立IPC连接请求时由注册回调线程创建，入口函数为上文提到的server_handler，类型为`TYPE_SHADOW`。正常情况下该线程不会被调度执行，仅当有Client端线程使用`ipc_call`发起IPC请求时，该线程运行并执行server_handler（即图中的`ipc_dispatcher`），执行结束之后会调用`ipc_return`回到Client端发起IPC请求的线程。 + +> [!IMPORTANT] 注意 +> 注册回调线程和服务线程都不再拥有调度上下文（Scheduling Context），也即不会主动被调度器调度到。其在客户端申请建立IPC连接或者发起IPC请求的时候才会被调度执行。为了实现该功能，这两种类型的线程会继承IPC客户端线程的调度上下文（即调度时间片budget），从而能被调度器正确地调度。 + +## ChCore IPC具体流程 +为了实现ChCore IPC的功能，首先需要在Client与Server端创建起一个一对一的IPC Connection。该Connection保存了IPC Server的服务线程（即上图中IPC handler Thread）、Client与Server的共享内存（用于存放IPC通信的内容）。同一时刻，一个Connection只能有一个Client接入，并使用该Connection切换到Server的处理流程。ChCore提供了一系列机制，用于创建Connection以及创建每个Connection对应的服务线程。下面将以具体的IPC注册到调用的流程，详细介绍ChCore的IPC机制： + +1. IPC服务器的主线程调用`ipc_register_server`（user/chcore-libc/musl-libc/src/chcore-port/ipc.c中）来声明自己为IPC的服务器端。 + + * 参数包括server_handler和client_register_handler，其中server_handler为服务端用于提供服务的回调函数（比如上图中IPC handler Thread的入口函数`ipc_dispatcher`）；client_register_handler为服务端提供的用于注册的回调函数，该函数会创建一个注册回调线程。 + + * 随后调用ChCore提供的的系统调用：`sys_register_server`。该系统调用实现在kernel/ipc/connection.c当中，该系统调用会分配并初始化一个`struct ipc_server_config`和一个`struct ipc_server_register_cb_config`。之后将调用者线程（即主线程）的general_ipc_config字段设置为创建的`struct ipc_server_config`，其中记录了注册回调线程和IPC服务线程的入口函数（即图中的`ipc_dispatcher`）。将注册回调线程的general_ipc_config字段设置为创建的`struct ipc_server_register_cb_config`，其中记录了注册回调线程的入口函数和用户态栈地址等信息。 + +2. IPC客户端线程调用`ipc_register_client`（定义在user/chcore-libc/musl-libc/src/chcore-port/ipc.c中）来申请建立IPC连接。 + + * 该函数仅有一个参数，即IPC服务器的主线程在客户端进程cap_group中的capability。该函数会首先通过系统调用申请一块物理内存作为和服务器的共享内存（即图中的Shared Memory）。 + + * 随后调用`sys_register_client`系统调用。该系统调用实现在kernel/ipc/connection.c当中，该系统调用会将刚才申请的物理内存映射到客户端的虚拟地址空间中，然后调用`create_connection`创建并初始化一个`struct ipc_connection`类型的内核对象，该内核对象中的shm字段会记录共享内存相关的信息（包括大小，分别在客户端进程和服务器进程当中的虚拟地址和capability）。 + + * 之后会设置注册回调线程的栈地址、入口地址和第一个参数，并切换到注册回调线程运行。 +3. 注册回调线程运行的入口函数为主线程调用`ipc_register_server`是提供的client_register_handler参数，一般会使用默认的`DEFAULT_CLIENT_REGISTER_HANDLER`宏定义的入口函数，即定义在user/chcore-libc/musl-libc/src/chcore-port/ipc.c中的`register_cb`。 + + * 该函数首先分配一个用来映射共享内存的虚拟地址，随后创建一个服务线程。 + + * 随后调用`sys_ipc_register_cb_return`系统调用进入内核，该系统调用将共享内存映射到刚才分配的虚拟地址上，补全`struct ipc_connection`内核对象中的一些元数据之后切换回客户端线程继续运行，客户端线程从`ipc_register_client`返回，完成IPC建立连接的过程。 + +4. IPC客户端线程调用`ipc_create_msg`和`ipc_set_msg_data`向IPC共享内存中填充数据，然后调用`ipc_call`（user/chcore-libc/musl-libc/src/chcore-port/ipc.c中）发起IPC请求。 + + * `ipc_call`中会发起`sys_ipc_call`系统调用（定义在kernel/ipc/connection.c中），该系统调用将设置服务器端的服务线程的栈地址、入口地址、各个参数，然后迁移到该服务器端服务线程继续运行。由于当前的客户端线程需要等待服务器端的服务线程处理完毕，因此需要更新其状态为TS_WAITING，且不要加入等待队列。 + +5. IPC服务器端的服务线程在处理完IPC请求之后使用`ipc_return`返回。 + * `ipc_return`会发起`sys_ipc_return`系统调用，该系统调用会迁移回到IPC客户端线程继续运行，IPC客户端线程从`ipc_call`中返回。 + +> [!CODING] 练习题 7 +> 在user/chcore-libc/musl-libc/src/chcore-port/ipc.c与kernel/ipc/connection.c中实现了大多数IPC相关的代码，请根据注释补全kernel/ipc/connection.c中的代码。之后运行ChCore可以看到 “[TEST] Test IPC finished!” 输出，你可以通过 Test IPC 测试点。 + + +> [!IMPORTANT] +> 以上为Lab4 Part3的所有内容 diff --git a/Pages/Lab4/assets/IPC-overview.png b/Pages/Lab4/assets/IPC-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..e2f9ad5e6dd93840d78a5ecb601b633ec3792006 GIT binary patch literal 43964 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 Lide+4 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 NJyzCMs!^~({vUu2n704` literal 0 HcmV?d00001 diff --git a/Pages/Lab4/multicore.md b/Pages/Lab4/multicore.md new file mode 100644 index 00000000..fa8ee9b4 --- /dev/null +++ b/Pages/Lab4/multicore.md @@ -0,0 +1,27 @@ +# 多核支持 + + + +本部分实验没有代码题，仅有思考题。为了让ChCore支持多核，我们需要考虑如下问题： + +- 如何启动多核，让每个核心执行初始化代码并开始执行用户代码？ +- 如何区分不同核心在内核中保存的数据结构（比如状态，配置，内核对象等）？ +- 如何保证内核中对象并发正确性，确保不会由于多个核心同时访问内核对象导致竞争条件？ + +在启动多核之前，我们先介绍ChCore如何解决第二个问题。ChCore对于内核中需要每个CPU核心单独存一份的内核对象，都根据核心数量创建了多份（即利用一个数组来保存）。ChCore支持的核心数量为PLAT_CPU_NUM（该宏定义在 kernel/common/machine.h 中，其代表可用CPU核心的数量，根据具体平台而异）。 比如，实验使用的树莓派3平台拥有4个核心，因此该宏定义的值为4。ChCore会CPU核心的核心ID作为数组的索引，在数组中取出对应的CPU核心本地的数据。为了方便确定当前执行该代码的CPU核心ID，我们在 kernel/arch/aarch64/machine/smp.c中提供了smp_get_cpu_id函数。该函数通过访问系统寄存器tpidr_el1来获取调用它的CPU核心的ID，该ID可用作访问上述数组的索引。 + +## 启动多核 +在实验1中我们已经介绍，在QEMU模拟的树莓派中，所有CPU核心在开机时会被同时启动。在引导时这些核心会被分为两种类型。一个指定的CPU核心会引导整个操作系统和初始化自身，被称为主CPU（primary CPU）。其他的CPU核心只初始化自身即可，被称为其他CPU（backup CPU）。CPU核心仅在系统引导时有所区分，在其他阶段，每个CPU核心都是被相同对待的。 + +> [!QUESTION] 思考题 1 +> 阅读汇编代码kernel/arch/aarch64/boot/raspi3/init/start.S。说明ChCore是如何选定主CPU，并阻塞其他其他CPU的执行的。 + +在树莓派真机中，还需要主CPU手动指定每一个CPU核心的的启动地址。这些CPU核心会读取固定地址的上填写的启动地址，并跳转到该地址启动。在kernel/arch/aarch64/boot/raspi3/init/init_c.c中，我们提供了wakeup_other_cores函数用于实现该功能，并让所有的CPU核心同在QEMU一样开始执行_start函数。 + +与之前的实验一样，主CPU在第一次返回用户态之前会在kernel/arch/aarch64/main.c中执行main函数，进行操作系统的初始化任务。在本小节中，ChCore将执行enable_smp_cores函数激活各个其他CPU。 + +> [!QUESTION] 思考题 2 +> 阅读汇编代码kernel/arch/aarch64/boot/raspi3/init/start.S, init_c.c以及kernel/arch/aarch64/main.c，解释用于阻塞其他CPU核心的secondary_boot_flag是物理地址还是虚拟地址？是如何传入函数enable_smp_cores中，又是如何赋值的（考虑虚拟地址/物理地址）？ + +> [!IMPORTANT] +> 以上为Lab4 part1 的所有内容 \ No newline at end of file diff --git a/Pages/Lab4/performance.md b/Pages/Lab4/performance.md new file mode 100644 index 00000000..eaa56ef1 --- /dev/null +++ b/Pages/Lab4/performance.md @@ -0,0 +1,35 @@ +# 实机运行与IPC性能优化 + + + +在本部分，你需要对IPC的性能进行优化。为此，你首先需要在树莓派3B实机上运行ChCore。 + +> [!CODING] 练习题 8 +> 请在树莓派3B上运行ChCore，并确保此前实现的所有功能都能正确运行。 + +在ChCore启动并通过测试后，在命令行运行 +```shell +$ ./test_ipc_perf.bin +``` + +你会得到如下输出结果 +```shell +[TEST] test ipc with 32 threads, time: xxx cycles +[TEST] test ipc with send cap, loop: 100, time: xxx cycles +[TEST] test ipc with send cap and return cap, loop: 100, time: xxx cycles +[TEST] Test IPC Perf finished! +``` + +> [!CODING] 练习题 9 +> 尝试优化在第三部分实现的IPC的性能，降低test_ipc_perf.bin的三个测试所消耗的cycle数 + +IPC性能测试程序的测试用例包括： +1. 创建多个线程发起IPC请求（不传递cap），Server收到IPC后直接返回。记录从创建线程到所有线程运行结束的时间。 +2. Client创建多个PMO对象，并发起IPC请求（传递PMO）；Server收到IPC后读取PMO，并依据读出的值算出结果，将结果写回随IPC传递的PMO中并返回；Client在IPC返回后读取PMO中的结果。将上述过程循环多次并记录运行时间。 +3. Client创建多个PMO对象，并发起IPC请求（传递PMO）；Server收到IPC后读取PMO，并依据读出的值算出结果，然后创建新的PMO对象，将结果写入新创建的PMO中，并通过`ipc_return_with_cap`返回；Client在IPC返回后读取返回的PMO中的结果。将上述过程循环多次并记录运行时间。 + +在测试能够顺利通过的前提下，你可以修改任意代码。（测试程序所调用的函数位于 `user/chcore-libc/libchcore/porting/overrides/src/chcore-port/ipc.c`） + + +> [!SUCCESS] +> 以上为Lab4 的所有内容 \ No newline at end of file diff --git a/Pages/Lab4/scheduler.md b/Pages/Lab4/scheduler.md new file mode 100644 index 00000000..fb7861bf --- /dev/null +++ b/Pages/Lab4/scheduler.md @@ -0,0 +1,105 @@ +# 多核调度 + + + +ChCore已经可以启动多核，但仍然无法对多个线程进行调度。本部分将首先实现协作式调度，从而允许当前在CPU核心上运行的线程主动退出或主动放弃CPU时，CPU核心能够切换到另一个线程继续执行。其后，我们将驱动树莓派上的物理定时器，使其以一定的频率发起中断，使得内核可以在一定时间片后重新获得对CPU核心的控制，并基于此进一步实现抢占式调度。 + +ChCore中与调度相关的函数与数据结构定义在kernel/include/sched/sched.h中。 +sched_ops是用于抽象ChCore中调度器的一系列操作。它存储指向不同调度操作的函数指针，以支持不同的调度策略。 +cur_sched_ops则是一个sched_ops的实例，其在内核初始化过程中（main函数）调用sched_init进行初始化。 +ChCore用在 kernel/include/sched/sched.h 中定义的静态函数封装对cur_sched_ops的调用。sched_ops中定义的调度器操作如下所示： + +* sche_init：初始化调度器。 +* sched：进行一次调度。即将正在运行的线程放回就绪队列，然后在就绪队列中选择下一个需要执行的线程返回。 +* sched_enqueue：将新线程添加到调度器的就绪队列中。 +* sched_dequeue：从调度器的就绪队列中取出一个线程。 +* sched_top：用于debug,打印当前所有核心上的运行线程以及等待线程的函数。 + +在本部分将实现一个基本的Round Robin（时间片轮转）调度器，该程序调度在同一CPU核心上运行的线程，因此内核初始化过程调用sched_init时传入了&rr作为参数。该调度器的调度操作（即对于sched_ops定义的各个函数接口的实现）实现在kernel/sched/policy_rr.c中，这里简要介绍其涉及的数据结构： + +`current_threads`是一个数组，分别指向每个CPU核心上运行的线程。而`current_thread`则利用`smp_get_cpu_id`获取当前运行核心的id，从而找到当前核心上运行的线程。 + +`struct queue_meta`定义了round robin调度器使用的就绪队列，其中`queue_head`字段是连接该就绪队列上所有等待线程的队列，`queue_len`字段是目前该就绪队列的长度，`queue_lock`字段是用于保证该队列并发安全的锁。 kernel/sched/policy_rr.c定义了一个全局变量`rr_ready_queue_meta`,该变量是一个`struct queue_meta`类型的数组，数组大小由`PLAT_CPU_NUM`定义，即代表每个CPU核心都具有一个就绪队列。运行的CPU核心可以通过`smp_get_cpu_id`获取当前运行核心的id，从而在该数组中找到当前核心对应的就绪队列。 + +## 调度队列初始化 +内核初始化过程中会调用`sched_init`初始化调度相关的元数据，`sched_init`定义在kernel/sched/sched.c中，该函数首先初始化idle_thread(每个CPU核心拥有一个idle_thread，当调度器的就绪队列中没有等待线程时会切换到idle_thread运行)，然后会初始化`current_threads`数组，最后调用`struct sched_ops rr`中定义的sched_init函数，即`rr_sched_init`。 +> [!CODING] 练习题 1 +> 在 kernel/sched/policy_rr.c 中完善 `rr_sched_init` 函数，对 `rr_ready_queue_meta` 进行初始化。在完成填写之后，你可以看到输出“Scheduler metadata is successfully initialized!”并通过 Scheduler metadata initialization 测试点。 + +> [!HINT] Tip +> sched_init 只会在主 CPU 初始化时调用，因此 rr_sched_init 需要对每个 CPU 核心的就绪队列都进行初始化。 + +## 调度队列入队 +内核初始化过程结束之后会调用`create_root_thread`来创建第一个用户态进程及线程，在`create_root_thread`最后会调用`sched_enqueue`函数将创建的线程加入调度队列之中。`sched_enqueue` +最终会调用kernel/sched/policy_rr.c中定义的`rr_sched_enqueue`函数。该函数首先挑选合适的CPU核心的就绪队列（考虑线程是否绑核以及各个CPU核心之间的负载均衡），然后调用`__rr_sched_enqueue`将线程插入到选中的就绪队列中。 +> [!CODING] 练习 2 +> 在 kernel/sched/policy_rr.c 中完善 `__rr_sched_enqueue` 函数，将`thread`插入到`cpuid`对应的就绪队列中。 + +> [!SUCCESS] +> 在完成填写之后，你可以看到输出“Successfully enqueue root thread”并通过 Schedule Enqueue 测试点。 + +## 调度队列出队 +内核初始化过程结束并调用`create_root_thread`创建好第一个用户态进程及线程之后，在第一次进入用户态之前，会调用`sched`函数来挑选要返回到用户态运行的线程（虽然此时就绪队列中只有root thread一个线程）。`sched`最终会调用kernel/sched/policy_rr.c中定义的`rr_sched`函数。 +该调度函数的操作非常直观，就是将现在正在运行的线程重新加入调度器的就绪队列当中，并从就绪队列中挑选出一个新的线程运行。 +由于内核刚刚完成初始化，我们还没有设置过`current_thread`，所以`rr_sched`函数中`old`为`NULL`，后面的练习中我们会考虑`old`不为`NULL`的情况。紧接着`rr_sched`会调用`rr_sched_choose_thread`函数挑选出下一个运行的线程，并切换到该线程。 + +`rr_sched_choose_thread`内部会调用`find_runnable_thread`从当前CPU核心的就绪队列中选取一个可以运行的线程并调用`__rr_sched_dequeue`将其从就绪队列中移除。 +> [!CODING] 练习 3 +> 在 kernel/sched/sched.c 中完善 `find_runnable_thread` 函数，在就绪队列中找到第一个满足运行条件的线程并返回。 在 kernel/sched/policy_rr.c 中完善 `__rr_sched_dequeue` 函数，将被选中的线程从就绪队列中移除。 + +> [!SUCCESS] +> 在完成填写之后，运行 ChCore 将可以成功进入用户态，你可以看到输出“Enter Procmgr Root thread (userspace)”并通过 Schedule Enqueue 测试点。 + +## 协作式调度 +顾名思义，协作式调度需要线程主动放弃CPU。为了实现该功能，我们提供了`sys_yield`这一个系统调用(syscall)。该syscall可以主动放弃当前CPU核心，并调用上述的`sched`接口完成调度器的调度工作。kernel/sched/policy_rr.c中定义的`rr_sched`函数中，如果当前运行线程的状态为`TS_RUNNING`，即还处于可以运行的状态，我们应该将其重新加入到就绪队列当中，这样该线程在之后才可以被再次调度执行。 + +> [!CODING] 练习 4 +> 在kernel/sched/sched.c中完善系统调用`sys_yield`，使用户态程序可以主动让出CPU核心触发线程调度。 +> 此外，请在kernel/sched/policy_rr.c 中完善`rr_sched`函数，将当前运行的线程重新加入调度队列中。 + +> [!SUCCESS] +> 在完成填写之后，运行 ChCore 将可以成功进入用户态并创建两个线程交替执行，你可以看到输出“Cooperative Schedluing Test Done!”并通过 Cooperative Schedluing 测试点。 + +## 抢占式调度 + +使用刚刚实现的协作式调度器，ChCore能够在线程主动调用`sys_yield`系统调用让出CPU核心的情况下调度线程。然而，若用户线程不想放弃对CPU核心的占据，内核便只能让用户线程继续执行，而无法强制用户线程中止。 因此，在这一部分中，本实验将实现抢占式调度，以帮助内核定期重新获得对CPU核心的控制权。 + +ChCore启动的第一个用户态线程（执行user/system-services/system-servers/procmgr/procmgr.c的`main`函数）将创建一个“自旋线程”，该线程在获得CPU核心的控制权后便会执行无限循环，进而导致无论是该程序的主线程还是ChCore内核都无法重新获得CPU核心的控制权。就保护系统免受用户程序中的错误或恶意代码影响而言，这一情况显然并不理想，任何用户应用线程均可以如该“自旋线程”一样，通过进入无限循环来永久“霸占”整个CPU核心。 + +为了处理“自旋线程”的问题，ChCore内核必须具有强行中断一个正在运行的线程并夺回对CPU核心的控制权的能力，为此我们必须扩展ChCore以支持处理来自物理时钟的外部硬件中断。 + +**物理时钟初始化** + +本部分我们将通过配置ARM提供的Generic Timer来使能物理时钟并使其以固定的频率发起中断。 +我们需要处理的系统寄存器如下([Refer](https://developer.arm.com/documentation/102379/0101/The-processor-timers)): +* CNTPCT_EL0: 它的值代表了当前的 system count。 +* CNTFRQ_EL0: 它的值代表了物理时钟运行的频率，即每秒钟 system count 会增加多少。 +* CNTP_CVAL_EL0: 是一个64位寄存器，操作系统可以向该寄存器写入一个值，当 system count 达到或超过该值时，物理时钟会触发中断。 +* CNTP_TVAL_EL0: 是一个32位寄存器，操作系统可以写入 TVAL，处理器会在内部读取当前的系统计数，加上写入的值，然后填充 CVAL。 +* CNTP_CTL_EL0: 物理时钟的控制寄存器，第0位ENABLE控制时钟是否开启，1代表enble，0代表disable；第1位IMASK代表是否屏蔽时钟中断，0代表不屏蔽，1代表屏蔽。 + +对物理时钟进行初始化的代码位于kernel/arch/aarch64/plat/raspi3/irq/timer.c的`plat_timer_init`函数。 + +> [!CODING] 练习 5 +> 请根据代码中的注释在kernel/arch/aarch64/plat/raspi3/irq/timer.c中完善`plat_timer_init`函数，初始化物理时钟。需要完成的步骤有： +> * 读取 CNTFRQ_EL0 寄存器，为全局变量 cntp_freq 赋值。 +> * 根据 TICK_MS（由ChCore决定的时钟中断的时间间隔，以ms为单位，ChCore默认每10ms触发一次时钟中断）和cntfrq_el0 （即物理时钟的频率）计算每两次时钟中断之间 system count 的增长量，将其赋值给 cntp_tval 全局变量，并将 cntp_tval 写入 CNTP_TVAL_EL0 寄存器！ +> * 根据上述说明配置控制寄存器CNTP_CTL_EL0。 + +> [!HINT] +> 由于启用了时钟中断，但目前还没有对中断进行处理，所以会影响评分脚本的评分，你可以通过运行ChCore观察是否有`"[TEST] Physical Timer was successfully initialized!: OK"`输出来判断是否正确对物理时钟进行初始化。 + +**物理时钟中断与抢占** + +我们在lab3中已经为ChCore配置过异常向量表（kernel/arch/aarch64/irq/irq_entry.S），当收到来自物理时钟的外部中断时，内核会进入`handle_irq`中断处理函数，该函数会调用平台相关的`plat_handle_irq`来进行中断处理。`plat_handle_irq`内部如果判断中断源为物理时钟，则调用`handle_timer_irq`。 + +ChCore记录每个线程所拥有的时间片（`thread->thread_ctx->sc->budget`），为了能够让线程之间轮转运行，我们应当在处理时钟中断时递减当前运行线程的时间片，并在当前运行线程的时间片耗尽时进行调度，选取新的线程运行。 + +> [!CODING] 练习 6 +> 请在kernel/arch/aarch64/plat/raspi3/irq/irq.c中完善`plat_handle_irq`函数，当中断号irq为INT_SRC_TIMER1（代表中断源为物理时钟）时调用`handle_timer_irq`并返回。 请在kernel/irq/irq.c中完善`handle_timer_irq`函数，递减当前运行线程的时间片budget，并调用sched函数触发调度。 请在kernel/sched/policy_rr.c中完善`rr_sched`函数，在将当前运行线程重新加入就绪队列之前，恢复其调度时间片budget为DEFAULT_BUDGET。 + +> [!SUCCESS] +> 在完成填写之后，运行 ChCore 将可以成功进入用户态并打断创建的“自旋线程”让内核和主线程可以拿回CPU核心的控制权，你可以看到输出`"Hello, I am thread 3. I'm spinning."`和`“Thread 1 successfully regains the control!”`并通过 `Preemptive Scheduling` 测试点。 + +> [!IMPORTANT] +> 以上为Lab4 Part2的所有内容 diff --git a/Pages/Lab5.md b/Pages/Lab5.md new file mode 100644 index 00000000..5c2021a3 --- /dev/null +++ b/Pages/Lab5.md @@ -0,0 +1,8 @@ +# Lab 5：虚拟文件系统 + +虚拟文件系统（Virtual File System，VFS）提供了一个抽象层，使得不同类型的文件系统可以在应用程序层面以统一的方式进行访问。这个抽象层隐藏了不同文件系统之间的差异，使得应用程序和系统内核可以以一致的方式访问各种不同类型的文件系统，如 ext4、tmpfs、 FAT32 等。在 ChCore 中，我们通过 FSM 系统服务以及 FS_Base 文件系统 wrapper 将不同的文件系统整合起来，给运行在 ChCore 上的应用提供了统一的抽象。 + +> [!CODING] 练习1 +> 阅读 `user/chcore-libc/libchcore/porting/overrides/src/chcore-port/file.c` 的 `chcore_openat` 函数，分析 ChCore 是如何处理 `openat` 系统调用的，关注 IPC 的调用过程以及 IPC 请求的内容。 + +Lab5 的所有代码都运行在用户态，不同应用间通过 IPC 进行通信，可调用的 IPC 相关函数定义在 `user/chcore-libc/libchcore/porting/overrides/include/chcore/ipc.h`。 diff --git a/Pages/Lab5/FSM.md b/Pages/Lab5/FSM.md new file mode 100644 index 00000000..ad5c9f0b --- /dev/null +++ b/Pages/Lab5/FSM.md @@ -0,0 +1,58 @@ +# FSM + + + +只要实现了 FSBase 和 FSWrapper 的接口的 IPC 服务，都可以成为一个文件系统示例。FSM 负责管理文件系统，为用户态建立文件系统连接并创建 IPC 的客户端，由于文件系统与其挂载点密切相关，所以 FSM 会处理以下类型的请求： + +```C +/* Client send fsm_req to FSM */ +enum fsm_req_type { + FSM_REQ_UNDEFINED = 0, + + FSM_REQ_PARSE_PATH, + FSM_REQ_MOUNT, + FSM_REQ_UMOUNT, + + FSM_REQ_SYNC, +}; +``` + +当 FSM 收到 Client 的FSM_REQ_MOUNT 类型的请求时，其会执行挂载文件系统的操作，**增加挂载的文件系统数量**，创建对应的 `mount_info_node` 添加到挂载信息表中，直至最后**与文件系统建立 IPC 连接**，并将创建完的 IPC 客户端保存在挂载信息中，总而言之，FSM 仅负责挂载和文件系统同步有关的工作，剩下的其他功能由每个具体的FS服务进行处理。 + +```c +struct mount_point_info_node { + cap_t fs_cap; + char path[MAX_MOUNT_POINT_LEN + 1]; + int path_len; + ipc_struct_t *_fs_ipc_struct; // fs_client + int refcnt; + struct list_head node; +}; + +``` + +> [!CODING] 练习题 2 +> 实现 `user/system-services/system-servers/fsm/fsm.c` 的 `fsm_mount_fs` 函数。 + + +> [!HINT] 提示： +> 你应当回顾Lab4的代码以查看ChCore是怎么基于IPC服务的cap来创建并维护连接的。 + +当 FSM 收到 Client 的 FSM_REQ_PARSE_PATH 类型的请求时，其首先会尝试解析 IPC 请求中访问文件的路径，通过遍历挂载信息链表，找到对应的最匹配的文件系统以及其挂载点路径。通过匹配的文件系统，获取到该文件系统的客户端 cap。如果 Client 已经获取到了文件系统的 cap，则直接返回解析后的`挂载点路径`；否则 FSM 会把挂载路径以及其对应的文件系统的 cap 也一并返回给 Client，并记录该 Client 已获取的文件系统 cap 的信息（FSM 会记录所有已经发送给某个 Client 的文件系统的 cap，见 `user/system-services/system-servers/fsm/fsm_client_cap.h`）。 + +> [!CODING] 练习题 3 +> 实现 `user/system-services/system-servers/fsm/fsm.c` 的 IPC 请求处理函数。 + + +> [!HINT] 提示： +> * 完成 `user/system-services/system-servers/fsm/fsm_client_cap.c` 中的相关函数。 +> * 所有关于挂载点有关的helper函数都在 `user/system-services/system-servers/fsm/mount_info.c` +> * IPC handler 返回的 IPC msg 的数据类型为 `struct fsm_request`，其有关的含义在 `user/chcore-libc/libchcore/porting/overrides/include/chcore-internal/fs_defs.h` 有详细的解释。 +> * 使用 `user/system-services/system-servers/fsm/mount_info.h` 定义的函数来帮助你实现 IPC handler。 +> * 你应当回顾 Lab4 代码以查看 ChCore 是怎么将 cap 对象在进程间收发的，以及 ChCore 中是怎么使用共享内存完成 IPC 调用的。 +> * 由于 printf 并不经过FS所以你可以放心使用。 + +我们提供了所有需要实现的文件的 Obj 版本，你可以修改 CMakeLists.txt，将编译所需的源文件从未实现的 C 文件替换为包含了正确实现的 Obj 文件，以此验证某一部分练习的正确性。如果你需要调试某一个部分，你可以将 `scripts/grade/cmakelists` 下的CMakeLists对应复制到 `FSM` 以及 `FS_Base` 的目录下覆盖并重新编译，运行 `make qemu` 后你就可以查看到 printf 的调试信息。 + +> [!SUCCESS] +> 完成第一部分后，执行 `make grade`，可以得到 `Scores: 20/100`。 \ No newline at end of file diff --git a/Pages/Lab5/base.md b/Pages/Lab5/base.md new file mode 100644 index 00000000..53ea2525 --- /dev/null +++ b/Pages/Lab5/base.md @@ -0,0 +1,85 @@ +# FS_Base + + + +在 ChCore 中，FS_Base 是文件系统的一层 wrapper，IPC 请求首先被 FS_Base 接收，再由 FS_Base 调用实际的文件系统进行处理。 + +## vnode + +在 FS_Base wrapper 中，ChCore 实现了 vnode 抽象，为文件系统中的对象（如文件、目录、符号链接等）提供一个统一的表示方式。 + +ChCore 中 vnode 的定义为： +```C +struct fs_vnode { + ino_t vnode_id; /* identifier */ + struct rb_node node; /* rbtree node */ + + enum fs_vnode_type type; /* regular or directory */ + int refcnt; /* reference count */ + off_t size; /* file size or directory entry number */ + struct page_cache_entity_of_inode *page_cache; + cap_t pmo_cap; /* fmap fault is handled by this */ + void *private; + + pthread_rwlock_t rwlock; /* vnode rwlock */ +}; +``` + +其中，`private` 表示文件系统特定的私有数据，例如对 inode 的引用，refcnt 代表该 vnode 被引用的次数，在下文的 `server_entry` 中会提到。 + +> [!CODING] 练习4 +> 实现 `user/system-services/system-servers/fs_base/fs_vnode.c` 中 vnode 的 `alloc_fs_vnode`、`get_fs_vnode_by_id`、`inc_ref_fs_vnode`、`dec_ref_fs_vnode` 函数。 + +> [!HINT] Tip +> +> - 你可能需要回顾Lab2中的代码去了解红黑树的操作方法。 + +> [!SUCCESS] +> 完成练习4后，执行 `make grade`，可以得到 `Scores: 35/100`。 + +## server_entry + +文件描述符（File Descriptor，简称 fd）是操作系统用于管理文件和其他输入/输出资源（如管道、网络连接等）的一种抽象标识符。我们来回顾一下计算机系统基础课中学习的unix文件系统抽象。在类 Unix 系统（如 Linux、macOS）中，文件描述符是一个非负整数，它指向一个内核中的文件表项，每个表项包含了文件的各种状态信息和操作方法。ChCore 将进程的 fd 保存在 chcore-libc 当中，同时在文件系统中通过 server_entry 维护了各个 Client 的 fd 的信息，把各个 Client 的 fd 和在文件系统侧的 fid 对应起来（(client_badge, fd) -> fid(server_entry)），也就是说 server_entry 对应着每个文件系统实例所对应的文件表项，其包含了对应文件表项的文件 offset 以及 `vnode` 引用。由于一个 `vnode` 可能会对应多个文件表项，所以 `vnode` 的引用数需要进行维护。 + +FS_Base 的 IPC handler 在处理 IPC 请求时，会先把 IPC 消息中包含的文件 fd 转换为 fid，所以我们需要把进程的 fd 和实际所对应的文件表项的映射建立起来，而在 ChCore 中对应的就是 `server_mapping` 链表。每当处理 IPC 请求时，文件系统都会通过进程发起的 badge 号找到与之对应的映射表，最终得到文件表项的 ID。 + +> [!CODING] 练习5 +> 实现 `user/system-services/system-servers/fs_base/fs_wrapper.c` 中的 `fs_wrapper_set_server_entry` 和 `fs_wrapper_get_server_entry` 函数。 + +> [!HINT] Tip +> +> - 通过全局变量 `struct list_head server_entry_mapping` 遍历 `server_entry_node`。 +> - 你可以参考 `fs_wrapper_clear_server_entry` 来理解每一个变量的含义。 + +> [!SUCCESS] +> 完成练习5后，执行 `make grade`，可以得到 `Scores: 50/100`。 + +## fs_wrapper_ops + +当我们拥有了文件表项和VNode抽象后，我们便可以实现真正的文件系统操作了。 + +我们可以将 FS_Base 以及 FS_Wrapper 的所有逻辑看成一个 VFS 的通用接口，其暴露出的接口定义为 `strcut fs_server_ops`。对于每一个文件系统实例，其都需要定义一个全局的名为 `server_ops` 的全局句柄，并将实际的文件系统操作的实现注册到该句柄中。你可以通过查看 `user/system-services/system-servers/tmpfs/tmpfs.c` 中查看 ChCore 的默认 `tmpfs` 文件系统是怎么将其注册到 `FS_Wrapper` 中的。而到了实际处理文件请求时，上层的 FS_Wrapper 在响应 IPC 请求的时候，只需要调用 `server_ops` 中的函数指针即可，不需要实际真正调用每一个文件系统实现的操作函数， 这样便完成了一个统一的文件操作逻辑。例如在 `tmpfs` 中实际的读命令为 `tmpfs_read` 但在上层的 `fs_wrapper` 看来其调用只需要调用 `server_ops->read` 即可而不需要真正知晓 `tmpfs` 中的函数签名。 + +对于本 Lab 你只需要实现最基本的 Posix 文件操作即可，即 Open，Close，Read, Write 以及 LSeek 操作。而其下层每个文件系统除了 `Open` 操作，每当 FS_Base 尝试处理 Posix 文件请求时，其都会调用 `translate_fd_to_fid` 将对应的 `fd` 翻译成 `fid` 并重新写回 `struct fs_request` 中的 `fd`，所以请注意**不需要在实际的fs_wrapper_函数中再次调用该函数**。下面将简述一下每一个函数的语义。 + +对于 Open 以及 Close 来说，其主要的目的就是创建以及回收 Server Entry 即文件表项。由于在 VFS 中 VNode 的创建是动态的，所以当进程尝试发出 `Open` 中，我们需要调用与之对应的 `server_ops` 并同时分配对应的文件表项。对于每一个新增的文件表项，我们需要将其关联到对应的内存 `VNode` 中。由于文件表项所对应的 `VNode` 可能不在内存中，所以当文件系统返回 inode 号时我们需要尝试查找相应的 `vnode`，如果不存在则尝试分配并将其添加至对应的红黑树中。当完成 `VNode` 关联后，我们需要使用上一步实现的映射函数，将 `server_entry` 与用户 `fd` 映射，完成文件表项的创建。对于 `Close`，我们需要采取类似的逻辑，即回退所有的文件表项操作，减少引用计数，并尝试回收对应的系统资源。 + +针对 `Read/Write/Lseek` 操作，你需要参考 `man` 以及对应的 `tests/fs_test` 下的所有测试文件，按照 `Posix` 语义相应地维护 `server_entry` 以及 `vnode` 信息，并将数据返回给用户进程。 + +针对 mmap 操作，我们知道针对文件的 mmap 操作是采取 Demand Paging 的内存映射来实现的，当用户进程调用 `mmap` 时，FS 会首先为用户新增一个 `pmo` 即内存对象，并将其对应的类型设置为 `PMO_FILE`，并为其创建 `Page_Fault` 映射(`user/system-services/system-servers/fs_base/fs_page_fault.c`)，最后将该 `pmo` 对象发回用户进程并让其进行映射。当用户尝试访问该内存对象，并发生缺页异常时，内核会根据 pmo 的所有者(badge)将异常地址调用到对应FS处理函数进行处理，处理函数为每一个文件系统中的 `user_fault_handler`，此时 FS 服务器会根据缺页地址分配新的内存页，填充文件内容并完成缺页的处理，最终返回内核态，从而递交控制权到原来的用户进程。 + +> [!CODING] 练习6 +> 实现 `user/system-services/system-servers/fs_base/fs_wrapper_ops.c` 中的 `fs_wrapper_open`、`fs_wrapper_close`、`fs_wrapper_read`、`fs_wrapper_pread`、`fs_wrapper_write`、`fs_wrapper_pwrite`、`fs_wrapper_lseek`、`fs_wrapper_fmap` 函数。 + +> [!HINT] Tip +> * `user/chcore-libc/libchcore/porting/overrides/include/chcore-internal/fs_defs.h` 中定义了 `struct fs_request`，其中定义了文件系统收到的 IPC 信息所包含的数据。 +> * 针对文件表项的helper函数如 `alloc_entry` 和 `free_entry` 在 `user/system-services/system-servers/fs_base/fs_vnode.c` 中定义。 +> * `user/system-services/system-servers/tmpfs/tmpfs.c` 中定义了 tmpfs 文件系统提供的文件操作接口 server_ops，fs_wrapper 接口会调用到 server_ops 进行实际的文件操作。 +> * 用户态的所有针对文件的请求，首先会被路由到 `user/chcore-libc/libchcore/porting/overrides/src/chcore-port/file.c` 中，该文件包含了在调用 `ipc` 前后的预备和收尾工作。 +> * 你应当回顾 Lab2 的代码，去了解针对 PMO_FILE，内核是怎么处理缺页并将其转发到FS中的。同时你需要查看 `user/system-services/system-servers/fs_base/fs_page_fault.c` 中的 `page_fault` 处理函数，了解 FS 是如何处理 mmap 缺页异常的。 + +> [!SUCCESS] +> 完成练习6后，执行 `make grade`，可以得到 `Scores: 100/100`。 + +> [!QUESTION] 练习7 +> 思考 ChCore 当前实现 VFS 的方式有何利弊？如果让你在微内核操作系统上实现 VFS 抽象，你会如何实现？ diff --git a/Pages/SUMMARY.md b/Pages/SUMMARY.md index 1ff6104e..a847c588 100644 --- a/Pages/SUMMARY.md +++ b/Pages/SUMMARY.md @@ -29,6 +29,15 @@ - [系统调用](./Lab3/syscall.md) - [用户态程序编写](./Lab3/userland.md) +- [Lab4: 多核调度与IPC](./Lab4.md) + - [多核支持](./Lab4/multicore.md) + - [多核调度](./Lab4/scheduler.md) + - [进程间通信(IPC)](./Lab4/IPC.md) + - [实机运行与IPC性能优化](./Lab4/performance.md) + +- [Lab5: 虚拟文件系统](./Lab5.md) + - [FSM](./Lab5/FSM.md) + - [FS_Base](./Lab5/base.md) - [附录](./Appendix.md) - [Bomb: 工具教程](./Appendix/toolchains.md)