From: Minep <lunaixsky@qq.com>
Date: Sun, 20 Aug 2023 19:59:09 +0000 (+0100)
Subject: update readme for more up-to-date information
X-Git-Url: https://scm.lunaixsky.com/lunaix-os.git/commitdiff_plain/13a19dccebb7df5b78d984ce26f8f3225dd5130a

update readme for more up-to-date information
chore: housekeeping stuff
---

diff --git a/.gitignore b/.gitignore
index cd7d5b3..70b7f5e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
 workspace/
 **.odp
 drafts/
+**.drawio
\ No newline at end of file
diff --git a/README.md b/README.md
index 30dc1a2..064c6be 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,17 @@
 
 LunaixOS - 一个简单的，详细的，POSIX兼容的（但愿！），带有浓重个人风格的操作系统。开发过程以视频教程形式在Bilibili呈现：[《从零开始自制操作系统系列》](https://space.bilibili.com/12995787/channel/collectiondetail?sid=196337)。
 
+## 一些实用资源
+
+如果有意研读LunaixOS的内核代码和其中的设计，以下资料可能会对此有用。
+
++ [内核虚拟内存的详细布局](docs/img/lunaix-os-mem.png)
++ [LunaixOS启动流程概览](docs/img/boot_sequence.jpeg)
++ LunaixOS总体架构概览（WIP）
+
 ## 当前进度以及支持的功能
 
-该操作系统支持x86架构，运行在保护模式中，采用宏内核架构，目前仅支持单核心。内存结构采用经典的3:1划分，即低3GiB为用户地址空间（0x400000 ~ 0xBFFFFFFF），内核地址空间重映射至高1GiB（0xC0000000 ~ 0xFFFFFFFF）。内存的详细布局可参考[LunaixOS内存地图](docs/img/lunaix-os-mem.png)
+该操作系统支持x86架构，运行在保护模式中，采用宏内核架构，目前仅支持单核心。架构与内核的解耦合工作正在进行中。
 
 在下述列表中，则列出目前所支持的所用功能和特性。列表项按照项目时间戳进行升序排列。
 
diff --git a/docs/img/boot_sequence.jpeg b/docs/img/boot_sequence.jpeg
new file mode 100644
index 0000000..0d57d31
Binary files /dev/null and b/docs/img/boot_sequence.jpeg differ
diff --git a/lunaix-os/README.md b/lunaix-os/README.md
index f3d24d0..95df5cb 100644
--- a/lunaix-os/README.md
+++ b/lunaix-os/README.md
@@ -4,23 +4,23 @@
 
 ## 目录结构
 
-+ `arch` 平台相关代码，LunaixOS的内核引导就在这里。
-+ `hal`  硬件抽象层，存放主板相关的代码，提供了一些访问主板功能（比如CPU，计时器）的抽象
++ `arch` 平台，CPU架构相关代码。
++ `hal`  硬件抽象层，包含了平台设备基本驱动的实现。
 + `includes`  所有头文件
-+ `debug`  内核调试服务器
-+ `config` makefile配置问题
++ `makeinc` makefile配置文件
 + `kernel` 这里就是内核了
-  + `asm` 共内核使用的，且平台相关的代码。
+  + `block` 块IO抽象层
+  + `debug`  内核调试服务器
+  + `device` 设备（通用）抽象层
   + `ds` 提供一些基本的数据结构支持。
+  + `exe` 可执行文件的解析与加载。
+  + `fs` 文件系统。
   + `mm` 各类内存管理器。
   + `peripheral` 外部设备驱动（如键盘）。
-  + `time` 为内核提供基本的时间，计时服务。
-  + `tty` 提供基本的显存操作服务。
-  + `fs` 文件系统。
-  + `device` 设备（通用）抽象层
-  + `block` 块设备抽象层
   + `process` 进程相关
-  + `demos` 简单的测试程序
-+ `lib` 一些内核使用的运行时库，主要提供是内核模式下的一些C标准库里的实现。
+  + `time` 为内核提供基本的时间，计时服务。
+  + `tty` 提供基本的，CGA服务。
++ `libs` 一些内核使用的运行时库，主要提供是内核模式下的一些C标准库里的实现。
 + `link` 链接器脚本
-+ `scripts` 其他脚本（如：用于代码生成）
\ No newline at end of file
++ `scripts` 其他脚本（如：用于代码生成）
++ `usr` 用户空间代码库，包含了一些实用的用户程序，编译过程独立与内核。
diff --git a/lunaix-os/includes/lunaix/trace.h b/lunaix-os/includes/lunaix/trace.h
index 4fbddd9..9edf961 100644
--- a/lunaix-os/includes/lunaix/trace.h
+++ b/lunaix-os/includes/lunaix/trace.h
@@ -28,24 +28,61 @@ struct trace_context
     struct ksyms* ksym_table;
 };
 
+/**
+ * @brief Init the trace service using loaded modksyms module
+ *
+ * @param bhctx
+ */
 void
 trace_modksyms_init(struct boot_handoff* bhctx);
 
+/**
+ * @brief Locate the symbol which is the closest to given pc.
+ *
+ * @param pc
+ * @return struct ksym_entry*
+ */
 struct ksym_entry*
 trace_sym_lookup(ptr_t pc);
 
+/**
+ * @brief Walk the stack backwards to generate stack trace
+ *
+ * @param tb_buffer
+ * @param fp
+ * @param limit
+ * @param last_fp
+ * @return int
+ */
 int
 trace_walkback(struct trace_record* tb_buffer,
                ptr_t fp,
                int limit,
                ptr_t* last_fp);
 
+/**
+ * @brief Print the stack trace starting from the given frame pointer
+ *
+ * @param fp
+ */
 void
 trace_printstack_of(ptr_t fp);
 
+/**
+ * @brief Print the stack trace given the current interrupt context. In addition
+ * to the stacktrace, this will also print all context switches happened
+ * beforehand, and all stack trace in each context. Recommended for verbose
+ * debugging.
+ *
+ * @param isrm
+ */
 void
 trace_printstack_isr(const isr_param* isrm);
 
+/**
+ * @brief Print the stack trace starting from caller's frame pointer.
+ *
+ */
 void
 trace_printstack();
 
diff --git a/lunaix-os/kernel/debug/trace.c b/lunaix-os/kernel/debug/trace.c
index a3553f1..e43d873 100644
--- a/lunaix-os/kernel/debug/trace.c
+++ b/lunaix-os/kernel/debug/trace.c
@@ -1,5 +1,5 @@
-#include <lunaix/mm/mmio.h>
 #include <lunaix/mm/page.h>
+#include <lunaix/mm/vmm.h>
 #include <lunaix/process.h>
 #include <lunaix/spike.h>
 #include <lunaix/syslog.h>
@@ -23,13 +23,14 @@ trace_modksyms_init(struct boot_handoff* bhctx)
     for (size_t i = 0; i < bhctx->mods.mods_num; i++) {
         struct boot_modent* mod = &bhctx->mods.entries[i];
         if (streq(mod->str, "modksyms")) {
-            // In case boot loader does not place our ksyms on page boundary
-            ptr_t start = PG_ALIGN(mod->start);
+            assert(PG_ALIGNED(mod->start));
+
             ptr_t end = ROUNDUP(mod->end, PG_SIZE);
-            ptr_t ksym_va = (ptr_t)ioremap(start, (end - start));
+            ptr_t ksym_va =
+              (ptr_t)vmm_vmap(mod->start, (end - mod->start), PG_PREM_R);
 
-            trace_ctx.ksym_table =
-              (struct ksyms*)(ksym_va + (mod->start - start));
+            assert(ksym_va);
+            trace_ctx.ksym_table = (struct ksyms*)ksym_va;
         }
     }
 }
@@ -126,7 +127,7 @@ trace_printstack()
     trace_printstack_of(cpu_get_fp());
 }
 
-void
+static void
 trace_printswctx(const isr_param* p, char* direction)
 {