X-Git-Url: https://scm.lunaixsky.com/lunaix-os.git/blobdiff_plain/b60166b327a9108b07e3069fa6568a451529ffd9..9e622bd093f8e106b7e8a00f55620f13cc5cd87f:/README.md?ds=sidebyside

diff --git a/README.md b/README.md
index 49ec98f..fe73edc 100644
--- a/README.md
+++ b/README.md
@@ -3,204 +3,323 @@
 </p>
 
 <p align="center">
-  <a href="#lunaixos-project">简体中文</a> | <a href="docs/README_en.md">English</a>
+  <a href="docs/README.cn.md">简体中文</a> | <a href="#the-lunaixos-project">English</a>
 </p>
 
-# The LunaixOS Project
-
-LunaixOS - 一个简单的，详细的，POSIX兼容的（但愿！），带有浓重个人风格的操作系统。开发过程以视频教程形式在Bilibili呈现：[《从零开始自制操作系统系列》](https://space.bilibili.com/12995787/channel/collectiondetail?sid=196337)。
-
-## 1. 一些实用资源
-
-如果有意研读LunaixOS的内核代码和其中的设计，以下资料可能会对此有用。
-
-+ [最新的LunaixOS源代码分析教程](docs/tutorial/0-教程介绍和环境搭建.md)
-+ [内核虚拟内存的详细布局](docs/img/lunaix-os-mem.png)
-+ [LunaixOS启动流程概览](docs/img/boot_sequence.jpeg)
-+ LunaixOS总体架构概览（WIP）
+# The Lunaix Project
+
+The Lunaix kernel (or soon-to-be LunaixOS) is a hobby kernel, written entirely from scratch. Designed to be POSIX-compliance, performance critical and modern, with some independent thoughts being applied in architectural design.
+
+
+This project is built entirely from first principles - meaning no code was copy-pasted or recycled from other OS projects or tutorials. Lunaix didn't begin as an attempt to outperform anything; it started as a personal challenge to learn OS theory and explore advanced kernel features through original design and implementation. Everything you see here was developed solo, part-time, with only hardware specs and my beloved **Modern Operating Systems** as guidance.
+
+If you're a kernel hobbyist looking for a fresh take or tired of mass-produced projects, then welcome, you're in the right place!
+
+
+| ![showcase_lunaix-over-serial.png](docs/img/showcase_lunaix-over-serial.png) |
+|:--:|
+| *Lunaix over serial* (`console=/dev/ttyS0`) |
+
+| ![showcase_lunaix-over-serial.png](docs/img/showcase_lunaix-over-vga-text.png) |
+|:--:|
+| *Lunaix over VGA text mode* (`console=/dev/ttyVCON0`) |
+
+> By the way, do you know there is an online video course  by the author on the design of lunaix? [Check it out](https://space.bilibili.com/12995787/channel/collectiondetail?sid=196337) (although it is in Chinese!)
+
+## Features
+
+Lunaix is a multi-architecture, general-purpose kernel built with performance, modularity, and robustness in mind. Its design emphasizes advanced abstractions, proactive error detection, and subsystem isolation. Lunaix is
+
++ **Fully-preemptive** for responsive multi-tasking
++ **Modular** with compile-time configurable components and extensible subsystems
++ **High-performance**, leveraging modern caching strategies and efficient infrastructures.
++ **Fault-tolerant**, with built-in error handling and stack backtracing
++ **Robust by design**, using mechanisms like proactive deadlock detection and driver isolation
+
+A significant amount of effort has gone into crafting clean abstractions, implementing advanced kernel features, and applying performance optimizations throughout the system.
+
+To better illustrate the scope of work already done, the following non-exhaustive list outlines currently supported features in Lunaix:
+
+<details>
+
+<summary>List of all features implemented</summary>
+
++ Multi-ISA
+  + x86_32
+  + x86_64
+  + Aarch64 (WIP)
++ Boot protocol
+  + abstraction for different protocol
+  + configurable kernel boot-time parameters
++ Platform resource management and definition
+  + read-only ACPI table interpretation
+  + full devicetree implementation
++ Memory management
+  + architecture-neutral abstraction
+  + highmem
+  + copy-on-write
+  + page sharing
+  + explicit huge page
+  + on-demand paging
+  + compound page
+  + reverse mapping (rmap)
+  + memory compaction (WIP)
+  + slab-style object allocator
+  + inter-process address space access
++ Multi-tasking
+  + fully preemptive
+  + protection levels
+  + process isolation
+  + native threading
+  + signal mechanism
+  + round-robin scheduler (for now)
+  + kernel level multi-tasking (i.e. kernel threads)
+  + taskfs: file system interface to process and threads
++ File system
+  + POSIX-compliant interface
+  + virtual file system framework
+  + file system mounting mechanism
+  + page cache for file IO
+  + inode/dnode caching
+  + ext2 (rev.0, rev.1)
+  + iso9660 (rock-ridge)
+  + twifs: kernel state fs interface.
++ Device management and interrupt handling
+  + unified IRQ framework
+  + unified driver framework for heterogenous devices
+  + modular driver model allow compiled-time toggling
+  + asynchronous operation model supported
+  + devfs: device fs interface.
++ Block I/O (blkio)
+  + unified block IO interface
+  + IO request packets caching
+  + asynchronous IO operation
++ Serial I/O
+  + POSIX-compliant serial IO model
++ Caching Infrastructure
+  + LRU replacement policy and pooling
+  + kernel daemon for dynamic and transparent cache managements
++ Error handling and detection
+  + stack backtracing with symbol resolution
+  + stack unwinding for nested exception
+  + CPU state dumping
+  + deadlock/hung-up detection
+
+</details>
+
+<details>
+
+<summary>List of currently supported device</summary>
+
++ Architecture Neutral
+  + UART 16650-compatible driver
+  + Serial ATA AHCI
+  + PCI 3.0
+  + PCIe 1.1
+  + Standard VGA
++ Intel x86
+  + RTC (Intel PCH)
+  + IOAPIC IRQ controller
+  + APIC Timer
+  + Legacy i8042 keyboard controller
++ ARM
+  + GICv3
+  + PL011 (WIP)
+</details>
+
+## Project Structure
+
+| Path | Description |
+|-----|------|
+| [lunaix-os](../lunaix-os/) | LunaixOS source code |
+| [slides](../slides/) | Slides used in my videos |
+| [reference-material](../reference-material/)| References |
+
+## Compile and Build
+
+Building lunaix is simple, no more bloated dependencies to install, basic `build-essentials` installation plus a python are sufficient.
+
++ gcc (recommend v12+)
++ binutils
++ make
++ python (recommend v3.11+)
 
-## 2. 当前进度以及支持的功能
+And also one should have environment variable `ARCH=<arch>` exported, where `<arch>` is one of the supported arhcitecture (`x86_32`, `x86_64`, `aarch64`).
 
-该操作系统支持x86架构，运行在保护模式中，采用宏内核架构，目前仅支持单核心。架构与内核的解耦合工作正在进行中。
+For cross compilation, also export `CX_PREFIX` to the gcc prefix for the corresponding `<arch>`.
 
-在下述列表中，则列出目前所支持的所用功能和特性。列表项按照项目时间戳进行升序排列。
+The following `make` actions are then available to use.
 
-+ 使用Multiboot进行引导启动
-+ APIC/IOAPIC作为中断管理器和计时器
-+ ACPI
-+ 虚拟内存
-+ 内存管理与按需分页
-+ 键盘输入
-+ 进程模型
-+ 54个常见的Linux/POSIX系统调用（[附录1](#appendix1)）
-+ 用户模式
-+ 信号机制
-+ PCI 3.0
-+ PCIe 1.1 (WIP)
-+ Serial ATA AHCI
-+ 文件系统
-  + 虚拟文件系统
-  + ISO9660
-    + 原生
-    + Rock Ridge拓展
-+ 远程GDB串口调试 (COM1@9600Bd)
-+ 用户程序加载与执行
-+ 动态链接 (WIP)
-+ 通用设备抽象层
-+ 通用图形设备抽象层
-  + 标准VGA实现
-+ 虚拟终端设备接口（兼容 POSIX.1-2008）
-+ 线程模型
+| Make command | Usage |
+| ---- | ---- |
+| `make all`               | Build the kernel bin |
+| `make rootfs`            | Build the stock rootfs |
+| `make clean`             | clean |
+| `make config`            | menuconfig |
 
-已经测试过的环境：
+A successful build will give `build/bin/kernel.bin`.
 
-+ QEMU (>=7.0.0)
-+ Bochs（SATA功能不支持）
-+ Virtualbox
-+ Dell G3 3779
+**Please note: this is the kernel, not a bootable image, it require a bootloader to boot and specify the rootfs.**
 
-## 3. 目录结构
+## Get Started
 
-|                                           |                              |
-| ----------------------------------------- | ---------------------------- |
-| [lunaix-os](lunaix-os/)                   | LunaixOS源代码               |
-| [slides](slides/)                         | 视频中所用的幻灯片和补充材料 |
-| [reference-material](reference-material/) | 标准，技术文档和参考文献     |
+If you are impatient, or just want something to run and don't want to went through tedious process of configuring rootfs and tweak kernel parameters. You can use the `live_debug.sh` provided in the lunaix root directory to quickly bring up the system with default parameters (also used by the author for debugging).
 
-## 4. 编译与构建
+### Quick Start
 
-构建该项目需要满足以下条件：
+This will get you up and running real quick. We will use `x86_64` as example.
 
-+ gcc 工具链
-+ make
-+ xorriso
-+ grub-mkrescue
+Assuming a Linux or other Unix-like shell environment.
 
-### 4.1 使用 GNU CC 工具链
+#### Select your target
+```sh
+$ export ARCH=x86_64
+```
 
-正如同大多数OS一样，LunaixOS 是一个混合了 C 和汇编的产物。这就意味着你得要使用一些标准的C编译器来构建Lunaix。在这里，我推荐使用 GNU CC 工具链来进行构建。至于其他的工具链，如llvm，也可以去尝试，但对此我就不能作任何的保证了。
+#### Check Python
+```sh
+$ python --version
+```
 
-如果你使用的是基于 x86 指令集的Linux系统，不论是64位还是32位，**其本机自带的gcc就足以编译Lunaix**。 当然了，如果说你的平台是其他非x86的，你也可以指定使用某个针对x86_32的gcc套件来进行交叉编译——在`make`时通过`CX_PREFIX`变量来指定gcc套件的前缀。如下例所示，我们可以在任意平台上，如risc-v，单独使用一个面向x86_32的gcc来进行交叉编译：
+Ensure at least `3.11`
 
-```
-make CX_PREFIX=i686-linux-gnu- all
+#### Check compiler
+```sh
+$ gcc -dumpmachine
 ```
 
-由于目前Lunaix仅支持x86_32微架构， `CX_PREFIX` 指向的gcc必须具有针对x86_32架构进行交叉编译的能力。
+Ensure `x86_64-linux-gnu` or anything resemble `x86_64`
 
-### 4.2 Docker镜像
+#### Check QEMU
+```sh
+$ which qemu-system-x86_64
+```
 
-对于开发环境，本项目也提供了Docker镜像封装。开箱即用，无需配置，非常适合懒人或惜时者。详细使用方法请转到：[Lunaix OSDK项目](https://github.com/Minep/os-devkit)。
+Should display a valid installation path
 
-### 4.3 构建选项
+#### Optional: Setting up Cross-Compiler
+```sh
+$ export CX_PREFIX=x86_64-linux-gnu-
+```
 
-假若条件满足，那么可以直接执行`make all`进行构建，完成后可在生成的`build`目录下找到可引导的iso。
+#### Run Configuration
+```sh
+make config
+```
 
-本项目支持的make命令：
-| 命令                     | 用途                                            |
-| ------------------------ | ----------------------------------------------- |
-| `make all`               | 构建镜像（`-O2`，但禁用CSE相关的优化项 **※** ） |
-| `make instable`          | 构建镜像（`-O2`，开启CSE相关优化）              |
-| `make all-debug`         | 构建适合调试用的镜像（`-Og`）                   |
-| `make run`               | 使用QEMU运行build目录下的镜像                   |
-| `make debug-qemu`        | 构建并使用QEMU进行调试                          |
-| `make debug-bochs`       | 构建并使用Bochs进行调试                         |
-| `make debug-qemu-vscode` | 用于vscode整合                                  |
-| `make clean`             | 删除build目录                                   |
+Then hitting `q` in the interactive shell to save and quit
 
-**※：由于在`-O2`模式下，GCC会进行CSE优化，这导致LunaixOS会出现一些非常奇怪、离谱的bug，从而影响到基本运行。具体原因有待调查。**
+#### Build stock rootfs
 
-### 4.4 设置内核启动参数
+```sh
+make rootfs
+```
 
-在 make 的时候通过`CMDLINE`变量可以设置内核启动参数列表。该列表可以包含多个参数，通过一个或多个空格来分割。每个参数可以为键值对 `<key>=<val>` 或者是开关标志位 `<flag>`。目前 Lunaix 支持以下参数：
+#### Build & Run
+```sh
+./live_debug.sh
+```
 
-+ `console=<dev>` 设置系统终端的输入输出设备（tty设备）。其中 `<dev>` 是设备文件路径 （注意，这里的设备文件路径是针对Lunaix，而非Linux）。关于LunaixOS设备文件系统的介绍可参考 Lunaix Wiki（WIP）
+you should see gdb now take control of your shell
 
-如果`CMDLINE`未指定，则将会载入默认参数：
+#### Connect to serial via telnet
 
-```
-console=/dev/ttyFB0
+Open up another window or session
+```sh
+telnet localhost 12345
 ```
 
-其中，`/dev/ttyFB0` 指向基于VGA文本模式的tty设备，也就是平时启动QEMU时看到的黑色窗口。
+#### Commence simulation
 
-当然，读者也可以使用 `/dev/ttyS0` 来作为默认tty设备，来验证 Lunaix 的灵活性与兼容性。该路径指向第一个串口设备。可以通过telnet协议在`12345`端口上进行访问——端口号可以自行修改QEMU启动参数（位于：`makeinc/qemu.mkinc`）来变更。
+Back to the gdb session and type `c` to countine
 
-**注意：** 根据操作系统和键盘布局的不同，telnet客户端对一些关键键位的映射（如退格，回车）可能有所差别（如某些版本的Linux会将退格键映射为`0x7f`，也就是ASCII的`<DEL>`字符，而非我们熟知`0x08`）。如果读者想要通过串口方式把玩Lunaix，请修改`usr/init/init.c`里面的终端初始化代码，将`VERASE`设置为正确的映射（修改方式可以参考 POSIX termios 的使用方式。由于Lunaix的终端接口的实现是完全兼容POSIX的，读者可以直接去查阅Linux自带的帮助`man termios`，无需作任何的转换）
 
-## 5. 运行，分支以及 Issue
+#### Watch Lunaix booting!
 
-### 5.1 虚拟磁盘（非必须）
+Congrats, enjoy your lunaix! (or submit an issue)
 
-你可以绑定一个虚拟磁盘镜像，可以使用如下命令快速创建一个：
 
-```bash
-qemu-img create -f vdi machine/disk0.vdi 128M
-```
+### Not so Quick Start
 
-如果你想要使用别的磁盘镜像，需要修改`configs/make-debug-tool`
+Here is a slower and yet more verbose steps:
 
-找到这一行：
+1. Select an architecture `<arch>`
+2. Check the compilation prerequisites and presence of `qemu-system-<arch>`
+3. Optionally export `CX_PREFIX` if you are building for another architecture.
+4. Run `make ARCH=<arch> rootfs` to build stock rootfs image, require support of `dd`，`mkfs.ext2`, `mount -o loop`, `mktemp`.
+5. Run `ARCH=<arch> live_debug.sh` to boot in QEMU with gdb hooked (one should see a gdb session)
+6. telnet to `localhost:12345`, this is QEMU emulated serial port
+7. type `c` in the active gdb session and commence emulation.
+8. Congrats, enjoy your lunaix!
+(or submit an issue)
 
-```
--drive id=disk,file="machine/disk0.vdi",if=none \
-```
 
-然后把`machine/disk0.vdi`替换成你的磁盘路径。
+## Booting the kernel
 
-有很多办法去创建一个虚拟磁盘，比如[qemu-img](https://qemu-project.gitlab.io/qemu/system/images.html)。
+Since lunaix is a kernel, much like linux. It requires additional setup to do the magic. And, as in "much like linux", methods to make linux kernel boot can also apply to lunaix without or with little translation, as we will discuss below.
 
-### 5.2 代码稳定性
+The bootloader part is generic, any bootloader, for example GRUB will work (not tested for UEFI, but I expect this would be an exception), or booting up in QEMU using `-kernel` option
 
-主分支一般是稳定的。因为在大多数情况下，我都会尽量保证本机运行无误后，push到该分支中。至于其他的分支，则是作为标记或者是开发中的功能。前者标记用分支一般会很快删掉；后者开发分支不能保证稳定性，这些分支的代码有可能没有经过测试，但可以作为Lunaix当前开发进度的参考。
+The kernel command line, is however, a bit differentiated.
+The syntax is similar, both takes form of space-separated array of `<key>=<val>` pairs or boolean `<flag>`.
 
-该系统是经过虚拟机和真机测试。如果发现在使用`make all`之后，虚拟机中运行报错，则一般是编译器优化问题。这个问题笔者一般很快就会修复，如果你使用别的版本的gcc（笔者版本11.2），出现了此问题，欢迎提issue。请参考[附录3：Issue的提交](#appendix3)
+Currently, lunaix support the following options
 
-下面列出一些可能会出现的问题。
+| Option | Default Value | Optional | Usage |
+| ------ | ----          |  -----   | ----  |
+| console | `/dev/ttyS0`   | No | Specify the system console device, path within lunaix's devfs |
+| rootfs | `/dev/block/sda` | No | Specify the device contain rootfs image, path within lunaix's devfs |
+| init | `/init` | Yes | Path within rootfs of the `init` |
 
-#### 问题#1： QEMU下8042控制器提示找不到
 
-这是QEMU配置ACPI时的一个bug，在7.0.0版中修复了。
+## Submit an Issue
 
-#### 问题#2：多进程运行时，偶尔会出现General Protection错误
+If one ran into bug, one can submit an issue by filling up the following template
 
-这很大概率是出现了竞态条件。虽然是相当不可能的。但如果出现了，还是请提issue。
+```
+1. Describe the problem
+    "How does it look like, anything descriptive: visual, sonic, emotional experience"
 
-#### 问题#3：Bochs无法运行，提示找不到AHCI控制器
+2. Steps to reproduce
+    "How you ran into this mess?"
 
-正常，**因为Bochs不支持SATA**。请使用QEMU或VirtualBox。
+3. Expected behaviour
+    "What do you intended/expected to achieve/to be"
 
-## 6. 调试 Lunaix 内核
+4. Lunaix's panic trace (if applicable)
 
-除了[附录4：串口GDB远程调试](#appendix4)描述的一种用于实机调试的方式以外。LunaixOS还提供了LunaDBG调试套件。这是一个GDB客户端插件，包含了对GDB原生命令集的一些扩充，主要用于改善与简化内核调试的过程。目前包含以下几个命令：
+5. Other clues that you think might be helpful
+```
 
-+ `vmrs [pid]` 列举进程`<pid>`的内存区域图（Memory Regions），如果`<pid>`未指定，则默认为正在运行的进程（smp=1）。
-+ `proc [pid]` 打印进程`<pid>`的进程控制块状态，如果`<pid>`未指定，则默认为正在运行的进程（smp=1）。
-+ `sched <threads | procs> [-l]` 查看调度器信息，接受两个参数：
-  + `threads` 打印所有依然在调度器中有注册的线程
-  + `procs` 打印所有依然在调度器中有注册的进程
-  + 可选开关 `-l` 决定是否以长列表打印（更详细的信息）
 
-该插件可以通过运行以下命令来进行安装：
+## Limitations
 
-```shell
-./scripts/gdb/install_lunadbg
-```
+The development process is still in motion, any limitation can be categorised as a feature yet to be. However, some features that the author considered to be the most urgent and wish the matters to be discussed.
+
+Lunaix is under impression of uniprocessor and not capable of running in SMP environment. This is major held back of being a modern operating system. It has the highest priority among all other tasks
 
-## 7. 参考教程
+Lunaix do not have a mature (or even, an infant) user space ecosystem, mainly because the lack of a proper and sophisticated libc. Efforts need to be done for porting one to the target. However, given the author's tight schedule, this task is unfortunately still beyond the horizon.
 
-**没有！！** 本教程以及该操作系统均为原创，没有基于任何市面上现行的操作系统开发教程，且并非是基于任何的开源内核的二次开发。
+## Acknowledgement
 
-为了制作LunaixOS，作者耗费大量时间和精力钻研技术文档，手册，理论书籍以及现行工业标准，从而尽量保证了知识的一手性。（这样一来，读者和听众们也算是拿到了二手的知识，而不是三手，四手，甚至n手的知识）。
+Albeit one must realise that the author has mentioned it in the very beginning, the author would like to emphaise **again** on the nature of this project.
 
-大部分的文档和标准可以在上述的[reference-material](reference-material/)中找到。
+As a personal challenge, this project is independently developed by the author single-handly, which means:
 
-当然，您也可以参考以下列表来了解现阶段的LunaixOS都使用了哪些资料（本列表会随着开发进度更新）：
++ No reference to existing tutorials, books, online courses or any open source project that might provide any example, hint or working prototype on the design and implementation of kernel, subsystems or anythings that can be contributed towards a working prototype.
++ The author has no prior knowledge on Linux kernel through out 90% of the project time.
++ All knowledge on the kernel design is coming from the basic textbook on operating system theory, that is, *Modern Operating System* by Tanenbaum.
++ All knowledge on the system programming is coming from the basic textbook, that is, *Computer System - A Programmer's Perspective Third Edition*
++ All knowledge on the generic framework design and driver development are ingested from various technical specifications gathered across the Internet.
 
-#### 手册，标准，技术文档
+## References
 
-+ [Intel 64 and IA-32 Architecture Software Developer's Manual (Full Volume Bundle)](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html)
-+ [ACPI Specification (version 6.4)](https://uefi.org/sites/default/files/resources/ACPI_Spec_6_4_Jan22.pdf)
++ Intel 64 and IA-32 Architecture Software Developer's Manual (Full Volume Bundle)
++ ACPI Specification (version 6.4)
++ Devicetree Specification
++ ARM® Generic Interrupt Controller (v3)
++ Arm® Architecture Reference Manual (Profile-A)
++ Procedure Call Standard for the Arm® 64-bit Architecture (AArch64)
 + IBM PC/AT Technical Reference
 + IBM VGA/XGA Technical Reference
 + 82093AA I/O Advanced Programmable Controller (IOAPIC) (Datasheet)
@@ -213,32 +332,20 @@ qemu-img create -f vdi machine/disk0.vdi 128M
 + Serial ATA: High Speed Serialized AT Attachment, Revision 3.2
 + SCSI Command Reference Manual
 + ATA/ATAPI Command Set - 3 (ACS-3)
-+ [ECMA-119 (ISO9660)](https://www.ecma-international.org/publications-and-standards/standards/ecma-119/)
++ ECMA-119 (ISO9660)
 + Rock Ridge Interchange Protocol (RRIP: IEEE P1282)
 + System Use Sharing Protocol (SUSP: IEEE P1281)
 + Tool Interface Standard (TIS) Portable Formats Specification (Version 1.1)
-
-**免责声明：PCI相关的标准最终解释权归PCI-SIG所有。此处提供的副本仅供个人学习使用。任何商用目的须向PCI-SIG购买。**
-
-#### 理论书籍
-
-+ *Computer System - A Programmer's Perspective Third Edition (CS:APP)* (Bryant, R & O'Hallaron, D)
++ *Computer System - A Programmer's Perspective Third Edition* (Bryant, R & O'Hallaron, D), a.k.a. CS:APP
 + *Modern Operating System* (Tanenbaum, A)
++ Free VGA, http://www.osdever.net/FreeVGA/home.htm 
++ GNU CC & LD online documentation.
++ PCI Lookup, https://www.pcilookup.com/
++ Linux man pages
 
-#### 网站
-
-+ [OSDev](https://wiki.osdev.org/Main_Page) - 杂七杂八的参考，很多过来人的经验。作者主要用于上古资料查询以及收集；技术文献，手册，标准的粗略总结；以及开发环境/工具链的搭建。
-+ [FreeVGA](http://www.osdever.net/FreeVGA/home.htm) - 98年的资源！关于VGA编程技术的宝藏网站。
-+ GNU CC 和 GNU LD 的官方文档。
-+ [PCI Lookup](https://www.pcilookup.com/) - PCI设备编号查询
-
-#### 其他
-
-+ Linux Manual - 用于查询*nix API的一些具体行为。
-
-## 附录1：实现的 POSIX 系统接口 <a id="appendix1"></a>
+## Appendix 1: Supported System Call<a id="appendix1"></a>
 
-LunaixOS 提供对以下POSIX的系统接口的实现。内核定义的系统调用号可以参考 [LunaixOS系统调用表](docs/lunaix-syscall-table.md) 。
+**Unix/Linux/POSIX**
 
 1. `sleep(3)`
 1. `wait(2)`
@@ -253,7 +360,7 @@ LunaixOS 提供对以下POSIX的系统接口的实现。内核定义的系统调
 1. `_exit(2)`
 1. `sigreturn(2)`
 1. `sigprocmask(2)`
-1. `sigaction(2)`
+1. `signal(2)`
 1. `kill(2)`
 1. `sigpending(2)`
 1. `sigsuspend(2)`
@@ -266,11 +373,11 @@ LunaixOS 提供对以下POSIX的系统接口的实现。内核定义的系统调
 2. `readdir(2)`
 2. `readlink(2)`
 2. `readlinkat(2)`
-2. `rmdir(2)`※
-2. `unlink(2)`※
-2. `unlinkat(2)`※
-2. `link(2)`※
-2. `fsync(2)`※
+2. `rmdir(2)`
+2. `unlink(2)`
+2. `unlinkat(2)`
+2. `link(2)`
+2. `fsync(2)`
 2. `dup(2)`
 2. `dup2(2)`
 2. `symlink(2)`
@@ -279,7 +386,7 @@ LunaixOS 提供对以下POSIX的系统接口的实现。内核定义的系统调
 2. `getcwd(2)`
 2. `rename(2)`※
 2. `mount(2)`
-2. `unmount` (a.k.a `umount(2)`)※
+2. `unmount` (a.k.a `umount(2)`)
 2. `getxattr(2)`※
 2. `setxattr(2)`※
 2. `fgetxattr(2)`※
@@ -301,28 +408,43 @@ LunaixOS 提供对以下POSIX的系统接口的实现。内核定义的系统调
 4. `pthread_kill`
 4. `pthread_detach`
 4. `pthread_sigmask`
+4. `getuid`
+4. `getgid`
+4. `geteuid`
+4. `getegid`
+4. `getgroups`
+4. `setuid`
+4. `setgid`
+4. `seteuid`
+4. `setegid`
+4. `setgroups`
+4. `chroot`
+4. `fchmodat`
+4. `fchownat`
+4. `faccessat`
 
+**LunaixOS**
 
-( **※**：该系统调用暂未经过测试 )
+1. `yield`
+2. `geterrno`
+3. `realpathat`
 
-## 附录2：Issue的提交<a id="appendix3"></a>
+( **※**：Indicate syscall is not tested )
 
-假若Lunaix的运行出现任何问题，还请按照以下的描述，在Issue里面提供详细的信息。
+## Appendix 2: Debugging with GDB remotely via UART
 
-+ 可用于复现问题的描述和指引（如Lunaix运行平台的软硬件配置）
-+ 错误症状描述
-+ LunaixOS在panic时打印的调试信息（如无法复制，可以截图）
+**(((( Broken after a refactoring years ago, need rework ))))**
 
-## 附录3：串口GDB远程调试<a id="appendix4"></a>
+The LunaixOS kernel comes with a built-in GDB debugging server, which runs on COM1@9600Bd. However, LunaixOS must be in debug mode before involving GDB.
 
-**（该功能正在重构，目前不可用）**
+One could trigger the debug mode by writing a byte sequence `0x40` `0x63` `0x6D` `0x63`, to the same serial port. A text "DEBUG MODE" with magenta-coloured background shall be present at the bottom of the screen.
 
-LunaixOS内核集成了最基本的GDB远程调试服务器。可通过串口COM1在9600波特率上与之建立链接。但是，在将GDB与内核链接起来之前，还需要让内核处在调试模式下。
+Note that, whenever the text appears, the LunaixOS always halt all activities other than the debugging server, which means no scheduling and no external interrupt servicing. Users are now recommended to attach their GDB and drive the kernel with the debugging workflow.
 
-要进入调试模式，需要往串口（波特率如上）写入字节串 `0x40` `0x63` `0x6D` `0x63`。此时，如果屏幕底部出现一条品红色背景的`DEBUG` 字样，那么就说明LunaixOS已处在调试模式下。
+Currently, LunaixOS implements the required minimal server-side command subset required by GDB Remote Protocol, namely, `g`, `G`, `p`, `P`, `Q`, `S`, `k`, `?`, `m`, `M`, `X`. Which should be enough to cover most debugging activities.
 
-注意，在这个时候，LunaixOS会开始在`COM1`上监听GDB协议信息，并且暂停一切的活动（如调度，以及对外部中断的一切响应）。用户此时需要将GDB与其挂载，并使用GDB的工作流来指示内核下一步的动作。
+When debugging is finished, one shall disconnect with `kill` command. This command will not force LunaixOS to power down the computer, instead it just resume the execution (identical behavior as `c` command). However, disconnecting does not means exiting of debug mode. The debug mode is still actived and any subsequent GDB attaching request shall remain the highest priority amongst all other activity. One shall deactivate the debug mode by writing byte sequence `0x40` `0x79` `0x61` `0x79` to the port, after GDB detached.
 
-在目前，为了防止代码过于臃肿，LunaixOS实现的是GDB远程协议要求的最小服务端命令子集：`g`, `G`, `p`, `P`, `Q`, `S`, `k`, `?`, `m`, `M`, `X`。足以满足大部分的调试需求。
+### Limitations
 
-当结束调试的时候，请使用GDB的`kill`指令进行连接的断开。注意，这个指令会使得LunaixOS恢复所有暂停的活动，进入正常的运行序列，但并不会退出调试模式。GDB的挂载请求依然在LunaixOS中享有最高优先权。如果需要退出调试模式，需要往串口写入字节串：`0x40` `0x79` `0x61` `0x79`。
+Currently, one should avoid the use of `info stack`, `bt` or any other command that involves stack unwinding or stack backtracing. As it will somehow corrupt the stack layout and result in undefined behaviour. This issue should be addressed in future releases.