docs(memory): 更新内存管理文档完善架构说明

Author: moyanj

docs/architecture/memory.md

@@ -1,7 +1,7 @@
 # 内存管理
 
-Proka Kernel 的内存管理分为以下几个层次：
+Proka Kernel 的内存管理采用层次化架构，实现了从底层页帧管理到上层动态内存分配的完整链路：
 
-1. **物理页分配 (PMM)**: 管理物理内存帧。
-2. **虚拟内存分页 (VMM)**: 实现页表映射与保护。
-3. **内核堆 (Heap)**: 提供动态内存分配功能。
+1. **物理页分配 (PMM)**: 基于内存映射表的简单页帧分配器，负责管理物理页帧的生命周期。
+2. **虚拟内存管理 (VMM)**: 引入了 `VmArea` 和 `MemorySet` 抽象，支持按需分页 (Lazy Allocation) 和内存区域保护。
+3. **内核堆 (Heap)**: 基于 `talc` 的动态分配器，能够通过 VMM 自动扩展内存空间，解决固定堆大小的限制。

docs/architecture/memory/heap.md

@@ -1 +1,41 @@
-# Heap
+# 内核堆管理 (Heap)
+
+Proka 内核提供了一个可动态增长的堆管理器，基于 `talc` crate 实现。它支持全局内存分配 (`Box`, `Vec`, `Arc` 等) 并能根据内核运行需求自动扩展。
+
+## 分配器架构
+
+内核使用 `Talck` 分配器，这是一个基于 `talc` 且由 `spin::Mutex` 保护的线程安全包装。
+
+### 动态扩展 (OOM Handling)
+与静态预留空间的分配器不同，Proka 实现了 `talc::OomHandler`：
+1. **触发**: 当分配器中剩余的 `Span` 不足以满足分配请求时，触发 `handle_oom`。
+2. **区域扩展**:
+   - 处理器访问 `KERNEL_MEMORY_SET`。
+   - 将 "heap" 区域的结束地址向上推进（步进通常为 1MB）。
+3. **物理映射**: 
+   - 处理器**手动**在页表中建立新区域的物理映射。
+   - *注意*: 必须手动映射以避免在持有分配器锁时再次触发缺页异常导致的死锁。
+4. **资源声明**: 调用 `talc.claim()` 将新映射的虚拟地址范围告知分配器。
+
+## 引导序列 (Bootstrapping)
+
+由于 VMM 本身在管理区域时需要分配内存（如 `Vec<VmArea>`），这产生了一个初始化循环依赖：
+**VMM 需要 Heap -> Heap 增长依赖 VMM**
+
+Proka 通过以下步骤解决：
+1. **小规模预映射**: 在 `init_heap` 中，内核先手动映射一个 64KB 的物理区域。
+2. **基础堆初始化**: 分配器首先认领这 64KB。
+3. **VMM 启动**: VMM 初始化并接管 "heap" 区域的管理。
+4. **透明增长**: 随后的内存需求超出 64KB 时，动态扩展机制自动生效。
+
+## 关键参数
+
+- **起始地址**: `0x_4444_4444_0000` (位于规范的内核高半地址空间)。
+- **初始大小**: 64 KiB。
+- **扩展步长**: 1 MiB。
+
+## 实现细节
+
+代码位于 `kernel/src/memory/allocator.rs`。
+- 定义了 `KernelOomHandler`。
+- 导出 `#[global_allocator]`。

docs/architecture/memory/paging.md

@@ -1 +1,44 @@
-# Paging
+# 虚拟内存管理 (VMM)
+
+Proka 采用基于 x86_64 四级页表的虚拟内存管理方案，并在 `x86_64` crate 的基础上封装了更高级的抽象，以支持按需分配 (On-demand Allocation) 和动态区域管理。
+
+## 核心概念
+
+### VmArea (虚拟内存区域)
+`VmArea` 代表一段连续的虚拟内存范围。它定义了：
+- **范围**: 起止虚拟地址（按页对齐）。
+- **权限**: 读、写、执行以及内核/用户态权限。
+- **语义**: 该区域的用途（如 `.text` 段、堆段、栈段等）。
+
+### MemorySet (地址空间)
+`MemorySet` 是 `VmArea` 的集合，代表一个完整的虚拟地址空间（通常对应一个页表）。
+- 管理一组不重叠的 `VmArea`。
+- 绑定一个 `OffsetPageTable` 实例。
+- 处理该地址空间内的特定逻辑，如缺页异常。
+
+## 缺页异常处理 (Page Fault)
+
+内核通过 `MemorySet` 实现 **懒加载 (Lazy Allocation)**。当 CPU 访问一个尚未建立物理映射的虚拟地址时，会触发 `#PF` 异常。
+
+1. **异常捕获**: 中断处理函数 `pagefault_handler` 获取出错地址。
+2. **区域查找**: 在 `KERNEL_MEMORY_SET` 中查找包含该地址的 `VmArea`。
+3. **按需分配**: 
+   - 如果地址在合法的 `VmArea` 内，内核会分配一个物理页帧。
+   - 根据 `VmArea` 定义的权限，在页表中建立映射。
+4. **恢复执行**: 映射建立后，CPU 重新执行触发异常的指令，此时访问成功。
+
+这种机制极大地减少了内核初始化时的页表开销，并支持了动态堆的无缝扩展。
+
+## 内核空间布局
+
+在内核初始化阶段，`MemorySet::new_kernel` 会通过链接器符号自动扫描内核镜像段，并建立初始映射：
+- **.text**: 只读，可执行。
+- **.rodata**: 只读，不可执行。
+- **.data / .bss**: 可读写，不可执行。
+- **Heap**: 初始建立一个小范围映射，支持按需扩展。
+
+## 实现细节
+
+代码位于 `kernel/src/memory/vmm.rs`。
+- 使用 `spin::Mutex` 保护全局 `KERNEL_MEMORY_SET`。
+- 依赖 `FrameAllocator` 提供物理页支持。

kernel/src/graphics/core.rs

@@ -59,7 +59,7 @@ impl<'a> Renderer<'a> {
         // Init BF, color = black (0)
         let back_buffer = vec![0; buffer_size];
         Self {
-            framebuffer: framebuffer,
+            framebuffer,
             back_buffer,
             pixel_size,
             clear_color: color::BLACK,
@@ -87,7 +87,7 @@ impl<'a> Renderer<'a> {
             let value: u32 = ((color.r as u32) << self.framebuffer.red_mask_shift())
                 | ((color.g as u32) << self.framebuffer.green_mask_shift())
                 | ((color.b as u32) << self.framebuffer.blue_mask_shift());
-            return value;
+            value
         } else if self.bpp == 24 {
             color.to_u32(false)
         } else {
@@ -96,6 +96,11 @@ impl<'a> Renderer<'a> {
     }
 
     /// Draw pixel to BF
+    ///
+    /// # Safety
+    ///
+    /// This function is unsafe because it does not check if the coordinates are within the
+    /// framebuffer boundaries. The caller must ensure that `x` and `y` are valid.
     #[inline(always)]
     pub unsafe fn set_pixel_raw_unchecked(&mut self, x: u64, y: u64, color: &color::Color) {
         let offset = self.get_buffer_offset(x, y);
@@ -177,17 +182,15 @@ impl<'a> Renderer<'a> {
     pub fn clear(&mut self) {
         let width = self.framebuffer.width();
         let height = self.framebuffer.height();
-        let color = self.clear_color.clone();
+        let color = self.clear_color;
         // Optimize clear operation
         let masked_clear_color = self.mask_color(&color);
         let pixel_bytes = masked_clear_color.to_le_bytes(); // To byte array
         let bytes_to_fill = &pixel_bytes[..self.pixel_size];
         for y in 0..height {
             for x in 0..width {
                 let offset = self.get_buffer_offset(x, y);
-                for i in 0..self.pixel_size {
-                    self.back_buffer[offset + i] = bytes_to_fill[i];
-                }
+                self.back_buffer[offset..offset + self.pixel_size].copy_from_slice(bytes_to_fill);
             }
         }
 
@@ -200,8 +203,8 @@ impl<'a> Renderer<'a> {
     /* ======== Drawing Example functions ======== */
     /// Draw a line
     pub fn draw_line(&mut self, p1: Pixel, p2: Pixel, color: color::Color) {
-        let dx_abs = ((p2.x as i64 - p1.x as i64).abs()) as u64;
-        let dy_abs = ((p2.y as i64 - p1.y as i64).abs()) as u64;
+        let dx_abs = (p2.x as i64 - p1.x as i64).unsigned_abs();
+        let dy_abs = (p2.y as i64 - p1.y as i64).unsigned_abs();
         let steep = dy_abs > dx_abs;
         let (mut x1, mut y1) = p1.to_coord();
         let (mut x2, mut y2) = p2.to_coord();
@@ -214,7 +217,7 @@ impl<'a> Renderer<'a> {
             core::mem::swap(&mut y1, &mut y2);
         }
         let dx = x2 - x1;
-        let dy = (y2 as i64 - y1 as i64).abs() as u64;
+        let dy = (y2 as i64 - y1 as i64).unsigned_abs();
         let mut error = (dx / 2) as i64;
         let y_step = if y1 < y2 { 1 } else { -1 };
         let mut y = y1 as i64;
@@ -348,7 +351,7 @@ impl<'a> Renderer<'a> {
     }
 
     /// Draw a rectangle
-    pub fn draw_rect(&mut self, pixel: Pixel, width: u64, height: u64, color: color::Color) -> () {
+    pub fn draw_rect(&mut self, pixel: Pixel, width: u64, height: u64, color: color::Color) {
         let (x, y) = pixel.to_coord();
         let x2 = x + width;
         let y2 = y + height;
@@ -364,9 +367,9 @@ impl<'a> Renderer<'a> {
         let (x_min, y_min) = pixel.to_coord();
         let x_max = x_min + width;
         let y_max = y_min + height;
-        let x_start = x_min.max(0);
+        let x_start = x_min;
         let x_end = x_max.min(self.width() - 1);
-        let y_start = y_min.max(0);
+        let y_start = y_min;
         let y_end = y_max.min(self.height() - 1);
         for y in y_start..=y_end {
             for x in x_start..=x_end {

kernel/src/libs/time/tsc.rs

@@ -57,11 +57,7 @@ pub fn init() {
         // time = pit_delta / PIT_FREQ
         // freq = tsc_delta * PIT_FREQ / pit_delta
 
-        if pit_delta == 0 {
-            0 // Failed
-        } else {
-            (tsc_delta * PIT_FREQ) / pit_delta
-        }
+        (tsc_delta * PIT_FREQ).checked_div(pit_delta).unwrap_or(0)
     });
 
     TSC_FREQUENCY.store(freq, Ordering::Relaxed);

kernel/src/memory/allocator.rs

@@ -3,7 +3,6 @@
 //! This module implements the heap allocator for the kernel.
 //! It uses the `talc` crate to manage heap memory with dynamic growth support.
 
-use crate::config::KERNEL_DEFAULT_HEAP_SIZE;
 use talc::{Span, Talc, Talck};
 use x86_64::{
     structures::paging::{
@@ -22,45 +21,56 @@ impl talc::OomHandler for KernelOomHandler {
     fn handle_oom(talc: &mut Talc<Self>, _layout: core::alloc::Layout) -> Result<(), ()> {
         // Expand by 1MB at least
         let expand_size = 1024 * 1024;
-        
+
         let mut ms_lock = crate::memory::vmm::KERNEL_MEMORY_SET.lock();
         let memory_set = ms_lock.as_mut().ok_or(())?;
-        
+
         // Find heap area
         let (old_end, new_end) = {
-            let heap_area = memory_set.areas.iter_mut().find(|a| a.name == "heap").ok_or(())?;
+            let heap_area = memory_set
+                .areas
+                .iter_mut()
+                .find(|a| a.name == "heap")
+                .ok_or(())?;
             let old_end = heap_area.end;
             let new_end = old_end + expand_size;
             heap_area.end = new_end;
             (old_end, new_end)
         };
-        
+
         // Map the new pages MANUALLY to avoid deadlock via #PF
         let page_range = {
             let start_page = Page::containing_address(old_end);
             let end_page = Page::containing_address(new_end - 1u64);
             Page::range_inclusive(start_page, end_page)
         };
-        
+
         let memory_map_response = crate::MEMORY_MAP_REQUEST
             .get_response()
             .expect("Failed to get memory map response");
-        let mut frame_allocator = unsafe { crate::memory::paging::init_frame_allocator(memory_map_response) };
-        
+        let mut frame_allocator =
+            unsafe { crate::memory::paging::init_frame_allocator(memory_map_response) };
+
         for page in page_range {
             let frame = frame_allocator.allocate_frame().ok_or(())?;
-            let flags = PageTableFlags::PRESENT | PageTableFlags::WRITABLE | PageTableFlags::NO_EXECUTE;
+            let flags =
+                PageTableFlags::PRESENT | PageTableFlags::WRITABLE | PageTableFlags::NO_EXECUTE;
             unsafe {
-                memory_set.page_table.map_to(page, frame, flags, &mut frame_allocator).map_err(|_| ())?.flush();
+                memory_set
+                    .page_table
+                    .map_to(page, frame, flags, &mut frame_allocator)
+                    .map_err(|_| ())?
+                    .flush();
             }
         }
-        
-        drop(ms_lock); 
-        
+
+        drop(ms_lock);
+
         unsafe {
-            talc.claim(Span::new(old_end.as_mut_ptr(), new_end.as_mut_ptr())).map_err(|_| ())?;
+            talc.claim(Span::new(old_end.as_mut_ptr(), new_end.as_mut_ptr()))
+                .map_err(|_| ())?;
         }
-        
+
         Ok(())
     }
 }

kernel/src/memory/mod.rs

@@ -4,6 +4,9 @@ pub mod paging;
 pub mod protection;
 pub mod vmm;
 
+pub use paging::{phys_to_virt, virt_to_phys_direct};
+pub use vmm::translate_addr;
+
 pub fn init() {
     let memory_map_response = crate::MEMORY_MAP_REQUEST
         .get_response()

kernel/src/memory/paging.rs

@@ -14,7 +14,7 @@ use limine::response::MemoryMapResponse;
 use x86_64::{
     registers::control::Cr3,
     structures::paging::{OffsetPageTable, PageTable},
-    VirtAddr,
+    PhysAddr, VirtAddr,
 };
 
 /// Retrieve the HHDM (Higher Half Direct Map) offset from Limine
@@ -29,6 +29,19 @@ pub fn get_hhdm_offset() -> VirtAddr {
     )
 }
 
+/// Convert physical address to virtual address using HHDM
+pub fn phys_to_virt(phys: PhysAddr) -> VirtAddr {
+    VirtAddr::new(phys.as_u64() + get_hhdm_offset().as_u64())
+}
+
+/// Convert virtual address to physical address (only for HHDM)
+///
+/// # Safety
+/// The caller must ensure the virtual address is within the HHDM region.
+pub unsafe fn virt_to_phys_direct(virt: VirtAddr) -> PhysAddr {
+    PhysAddr::new(virt.as_u64() - get_hhdm_offset().as_u64())
+}
+
 /// Initialize an OffsetPageTable for accessing page tables
 ///
 /// # Arguments