ch4:注释代码2

Author: Kodp

os/src/linker.ld

@@ -11,10 +11,10 @@ SECTIONS
     .text : {
         *(.text.entry)
         . = ALIGN(4K);
-        strampoline = .;
-        *(.text.trampoline);
+        strampoline = .;  /* 定义符号 strampoline 指向 trampoline 段起始 */
+        *(.text.trampoline);  /* 放置 trampoline 代码 (__alltraps, __restore) */
         . = ALIGN(4K);
-        *(.text .text.*)
+        *(.text .text.*)   /* 放置其余内核代码 */
     }
 
     . = ALIGN(4K);

os/src/mm/frame_allocator.rs

@@ -49,8 +49,8 @@ trait FrameAllocator {
 }
 /// an implementation for frame allocator
 pub struct StackFrameAllocator {
-    current: usize,
-    end: usize,
+    current: usize,  // 起始页号
+    end: usize,      // 结束页号
     recycled: Vec<usize>,
 }
 

os/src/mm/memory_set.rs

@@ -33,7 +33,7 @@ lazy_static! {
     pub static ref KERNEL_SPACE: Arc<UPSafeCell<MemorySet>> =
         Arc::new(unsafe { UPSafeCell::new(MemorySet::new_kernel()) });
 }
-/// address space
+/// 地址空间
 pub struct MemorySet {
     page_table: PageTable,
     areas: Vec<MapArea>,
@@ -63,22 +63,31 @@ impl MemorySet {
             None,
         );
     }
+    ///@ push 将一个MapArea push到自己的areas，如果有数据就写入数据到内存。 
+    /// 把MapArea内的每个都页都放入页表（map）
+    /// 对于每个应用程序，其trampoline虚拟地址对应的物理页号也都放入了自己的地址空间，这样它才能跳转到trap处理程序
     fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) {
         map_area.map(&mut self.page_table);
         if let Some(data) = data {
             map_area.copy_data(&mut self.page_table, data);
         }
         self.areas.push(map_area);
     }
-    /// Mention that trampoline is not collected by areas.
+    /// 将跳板页面映射到地址空间.
+    /// 注意: 跳板页面不由 MemoryArea 管理.
     fn map_trampoline(&mut self) {
+
+        //@ 将TRAMPOLINE->strampoline放入页表
         self.page_table.map(
+            // 虚拟地址: TRAMPOLINE (最高虚拟页,说最高是因为 TRAMPOLINE 定义为 usizeMAX - 1Page)
             VirtAddr::from(TRAMPOLINE).into(),
+            // 物理地址: strampoline 符号的地址 (代码所在物理页帧)
             PhysAddr::from(strampoline as usize).into(),
+            // 权限: 可读 (R) | 可执行 (X)
             PTEFlags::R | PTEFlags::X,
         );
     }
-    /// Without kernel stacks.
+    ///@ 建立页表恒等映射 (Identity Mapping)
     pub fn new_kernel() -> Self {
         let mut memory_set = Self::new_bare();
         // map trampoline
@@ -94,8 +103,10 @@ impl MemorySet {
         info!("mapping .text section");
         memory_set.push(
             MapArea::new(
+                // 指定虚拟地址范围
                 (stext as usize).into(),
                 (etext as usize).into(),
+                // 指定恒等映射
                 MapType::Identical,
                 MapPermission::R | MapPermission::X,
             ),
@@ -132,6 +143,7 @@ impl MemorySet {
             None,
         );
         info!("mapping physical memory");
+        // ekernel 到 MEMORY_END 的映射，使内核可以用简单的、与物理地址相同的虚拟地址来访问任意物理内存（例如，用于物理页帧分配、访问设备寄存器等）。
         memory_set.push(
             MapArea::new(
                 (ekernel as usize).into(),
@@ -141,26 +153,49 @@ impl MemorySet {
             ),
             None,
         );
+        // 上述一通push完成，当系统启用分页后：
+        // CPU 产生的任何虚拟地址，如果落在了 .text, .rodata, .data, .bss 或 ekernel 到 MEMORY_END 的范围内，
+        // MMU 通过查询内核页表进行地址转换时，找到的物理地址与该虚拟地址完全相同。
+        // 恒等映射也保证了我们启动分页的平滑过渡：启动分页前最后一条指令和启动分页后第一条指令连续。
+
+        //? 问题：恒等映射的这些页表占多少空间？
+        // 含这个问题的上下文的ai： https://gemini.google.com/app/51ce53f706953582
         memory_set
     }
     /// Include sections in elf and trampoline and TrapContext and user stack,
     /// also returns user_sp_base and entry point.
+    /// 解析 ELF 文件，根据其中的信息创建用户程序的代码、数据、栈、Trap 上下文等内存区域，
+    /// 并建立这些区域对应的页表映射。
+    /// 返回一个元组，包含：
+    ///     - 构建好的 MemorySet 实例，代表用户程序的地址空间。
+    ///     - 用户栈的栈顶虚拟地址，作为用户程序启动时的栈指针。
+    ///     - 用户程序的入口点虚拟地址，即程序开始执行的第一条指令的地址。
     pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) {
         let mut memory_set = Self::new_bare();
         // map trampoline
+        // 跳板页用于用户态和内核态之间的切换。它在所有用户地址空间中映射到TRAMPOLINE位置
         memory_set.map_trampoline();
+
         // map program headers of elf, with U flag
+        // 使用 xmas_elf 库解析输入的 ELF 文件数据。
         let elf = xmas_elf::ElfFile::new(elf_data).unwrap();
         let elf_header = elf.header;
         let magic = elf_header.pt1.magic;
+        // 检查 ELF 文件头的 magic number ([0x7f, 'E', 'L', 'F'])，确保是有效的 ELF 格式。
         assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!");
         let ph_count = elf_header.pt2.ph_count();
         let mut max_end_vpn = VirtPageNum(0);
+
+        // 遍历 ELF 文件中的程序头 (Program Headers)，程序头描述了 ELF 文件中各个段（如代码段、数据段）应该如何被加载到内存中。
         for i in 0..ph_count {
             let ph = elf.program_header(i).unwrap();
+            // 只处理类型为 'Load' 的程序头，其要被加载到虚拟地址空间并建立映射的。
             if ph.get_type().unwrap() == xmas_elf::program::Type::Load {
+                // 获取该加载段在虚拟地址空间中的起始地址和结束地址 (基于其内存大小)。
                 let start_va: VirtAddr = (ph.virtual_addr() as usize).into();
                 let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into();
+
+                // 根据 ELF 段的标志 (flags) 确定该内存区域的访问权限。
                 let mut map_perm = MapPermission::U;
                 let ph_flags = ph.flags();
                 if ph_flags.is_read() {
@@ -172,20 +207,38 @@ impl MemorySet {
                 if ph_flags.is_execute() {
                     map_perm |= MapPermission::X;
                 }
+                // 创建一个 MapArea 实例，添加到 MemorySet 中，并提供段的初始数据。
                 let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm);
-                max_end_vpn = map_area.vpn_range.get_end();
+                max_end_vpn = map_area.vpn_range.get_end();  // 最大虚拟页号
+                // push 方法会执行以下操作：
+                //      - 调用 map_area.map()：遍历 MapArea 范围内的虚拟页，
+                //        为每个页分配物理页帧 (因为 MapType::Framed)，并在页表中建立 vpn -> ppn 的映射。
+                //      - 调用 map_area.copy_data()：将 ELF 文件中该段的内容复制到刚刚分配的物理页帧中。
+                //      - 将 map_area 添加到 memory_set.areas 列表中。
+                
                 memory_set.push(
-                    map_area,
-                    Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]),
+                    map_area, // data: Some(&[u8])
+                    Some(&elf.input[ph.offset() as usize .. (ph.offset() + ph.file_size()) as usize]),
                 );
             }
         }
         // map user stack with U flags
+        // 映射用户栈区域。
         let max_end_va: VirtAddr = max_end_vpn.into();
         let mut user_stack_bottom: usize = max_end_va.into();
         // guard page
+        // 在用户栈和 ELF 段之间留出一个页大小的未映射或特殊映射区域。
+        // 这样，如果用户栈溢出，触碰到这个 Guard Page 会立即触发页错误，而不是覆盖到前面的代码/数据段。
+        // 这里通过简单地将栈底地址跳过一个页大小PAGE_SIZE来实现，Guard Page 本身没有被 push 到 areas 中，因此是未映射的。
         user_stack_bottom += PAGE_SIZE;
+
+        // 计算用户栈的栈顶地址 (栈从高地址向低地址增长，所以栈顶地址 > 栈底地址)
         let user_stack_top = user_stack_bottom + USER_STACK_SIZE;
+        
+        // 创建并映射用户栈的 MapArea。
+        //    映射类型为 Framed (需要分配新的物理页帧作为栈空间)。
+        //    权限为 用户可读写 (R | W | U)，用户栈不需要可执行。
+        //    初始数据为 None，因为栈内容由程序运行时动态生成。
         memory_set.push(
             MapArea::new(
                 user_stack_bottom.into(),
@@ -195,17 +248,22 @@ impl MemorySet {
             ),
             None,
         );
-        // used in sbrk
+        // 映射 sbrk 区域 (用于支持动态堆扩展)。
+        //     通常在用户栈之后放置一个零大小的 MapArea，标记动态内存分配（如堆）的起始位置。
+        //     用户程序通过 sbrk 等系统调用请求更多内存时，OS 会扩展这个 MapArea
         memory_set.push(
             MapArea::new(
-                user_stack_top.into(),
-                user_stack_top.into(),
+                user_stack_top.into(),  // sbrk 区域起始地址，通常紧随用户栈顶
+                user_stack_top.into(),  // sbrk 区域结束地址，初始大小为 0
                 MapType::Framed,
-                MapPermission::R | MapPermission::W | MapPermission::U,
+                MapPermission::R | MapPermission::W | MapPermission::U,  // 用户可读写权限
             ),
             None,
         );
-        // map TrapContext
+        // 映射 Trap 上下文 (TrapContext) 区域。
+        //     TrapContext 用于在用户/内核模式切换时保存用户态的 CPU 寄存器状态。
+        //     它被放置在用户地址空间中一个固定的高地址 (TRAP_CONTEXT_BASE)，紧邻跳板下方。
+        //     这样在内核处理 Trap 时，可以通过一个固定的虚拟地址访问到保存的用户上下文。
         memory_set.push(
             MapArea::new(
                 TRAP_CONTEXT_BASE.into(),
@@ -215,16 +273,22 @@ impl MemorySet {
             ),
             None,
         );
+        // 返回构建好的 MemorySet、初始用户栈顶地址和程序入口点。
+        //     操作系统调度器在第一次运行这个用户进程时会使用这些信息：
+        //     - 将 memory_set 的根页表地址加载到 satp 寄存器。
+        //     - 将 user_stack_top 加载到用户栈指针寄存器 (如 sp)。
+        //     - 将 entry_point 加载到程序计数器 (PC)，开始执行用户程序。
         (
             memory_set,
             user_stack_top,
-            elf.header.pt2.entry_point() as usize,
+            elf.header.pt2.entry_point() as usize, // 用户进程执行的第一个指令地址
         )
     }
     /// Change page table by writing satp CSR Register.
     pub fn activate(&self) {
         let satp = self.page_table.token();
         unsafe {
+            // 从执行 satp::write 指令的时刻起，SV39 分页模式就被启用了，MMU 开始使用内核地址空间的多级页表进行后续的地址转换。
             satp::write(satp);
             asm!("sfence.vma");
         }
@@ -287,23 +351,23 @@ impl MapArea {
             map_perm,
         }
     }
-    /// 建立单页VPN的映射
+    /// 建立单页VPN的映射：向自身添加VPN->PPN（直接映射）、向页表里添加一个VPN->PPN（三级映射）。
     pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) {
         let ppn: PhysPageNum;
         //1. 更新data_frames
         match self.map_type {
             MapType::Identical => {
-                // 不向data_frames里推数据
+                // 不向data_frames里推数据（恒等映射）
                 ppn = PhysPageNum(vpn.0);
             }
             MapType::Framed => {
-                let frame = frame_alloc().unwrap();
+                let frame = frame_alloc().unwrap(); // 自己分配一个物理页
                 ppn = frame.ppn;
                 self.data_frames.insert(vpn, frame);
             }
         }
         let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap();
-        //2. 更新页表
+        // 页表内添加vpn->ppn的映射
         page_table.map(vpn, ppn, pte_flags);
     }
     #[allow(unused)]
@@ -340,7 +404,9 @@ impl MapArea {
     }
     /// data: start-aligned but maybe with shorter length
     /// assume that all frames were cleared before
-    /// 将数据放入物理页，一页一页的放，顺序是虚拟页递增的顺序。
+    /// 向已经分配并映射好的物理页帧中写入数据
+    /// 通常是在MapArea 调用了 map 方法完成所有页的映射后（此时 map 内部多次调用了 map_one），data_frames 被填充了需要追踪的物理页帧信息，
+    /// 然后才会调用 copy_data 来向这些已分配并映射的物理页写入数据。
     pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) {
         assert_eq!(self.map_type, MapType::Framed);
         let mut start: usize = 0;
@@ -384,8 +450,9 @@ bitflags! {
     }
 }
 
-/// Return (bottom, top) of a kernel stack in kernel space.
+/// 根据 app_id 计算内核栈在内核地址空间中的位置 (bottom, top)
 pub fn kernel_stack_position(app_id: usize) -> (usize, usize) {
+    // 内核栈位于跳板页下方，每个栈之间有一个 PADDING 页
     let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE);
     let bottom = top - KERNEL_STACK_SIZE;
     (bottom, top)
@@ -394,10 +461,12 @@ pub fn kernel_stack_position(app_id: usize) -> (usize, usize) {
 /// remap test in kernel space
 #[allow(unused)]
 pub fn remap_test() {
+    // 获取代码段、只读数据段、数据段中间位置的虚拟地址
     let mut kernel_space = KERNEL_SPACE.exclusive_access();
     let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into();
     let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into();
     let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into();
+    // 检查页面是否不可写（代码段和只读数据段的页面不可写）
     assert!(!kernel_space
         .page_table
         .translate(mid_text.floor())
@@ -408,6 +477,7 @@ pub fn remap_test() {
         .translate(mid_rodata.floor())
         .unwrap()
         .writable(),);
+    // 检查数据段页面不可执行
     assert!(!kernel_space
         .page_table
         .translate(mid_data.floor())

os/src/mm/mod.rs

@@ -24,5 +24,5 @@ pub use page_table::{PTEFlags, PageTable};
 pub fn init() {
     heap_allocator::init_heap();
     frame_allocator::init_frame_allocator();
-    KERNEL_SPACE.exclusive_access().activate();
+    KERNEL_SPACE.exclusive_access().activate();  // 开启分页
 }

os/src/mm/page_table.rs

@@ -56,7 +56,7 @@ impl PageTableEntry {
         PTEFlags::from_bits(self.bits as u8).unwrap()
     }
     /// The page pointered by page table entry is valid?
-    pub fn is_valid(&self) -> bool {
+    pub fn is_valid(&self) -> bool {  //? 什么时候变为无效？
         (self.flags() & PTEFlags::V) != PTEFlags::empty()
     }
     /// The page pointered by page table entry is readable?
@@ -74,7 +74,11 @@ impl PageTableEntry {
 }
 
 /// page table structure
-/// 页表结构：根页号，页帧
+/// 页表结构：根页号，FrameTracker向量
+/// FrameTracker向量：这些FrameTracker里的物理页号都是页表页号，包含所有的一级、二级、三级页表页。**页号**实际上存在三级页表页内。
+/// 当页表被释放，这个向量也被释放；向量里对应的FrameTracker会释放；FrameTracker的Drop实现了对FrameTraker
+/// 自身包含的物理页号指向的物理页的释放。所以这会释放PTE指向的页.
+/// 
 pub struct PageTable {
     root_ppn: PhysPageNum,
     frames: Vec<FrameTracker>,
@@ -87,7 +91,7 @@ impl PageTable {
         let frame = frame_alloc().unwrap();
         PageTable {
             root_ppn: frame.ppn,
-            frames: vec![frame],
+            frames: vec![frame],  // root_ppn指向的一级页表放在里面
         }
     }
     /// Temporarily used to get arguments from user space.
@@ -98,10 +102,10 @@ impl PageTable {
         }
     }
     /// Find PageTableEntry by VirtPageNum, create a frame for a 4KB page table if not exist
-    /// 根据给定的虚拟页号 vpn，在多级页表树中查找对应的三级（叶子）页表项 (PTE)。
+    /// 根据给定的虚拟页号 vpn，在多级页表树中查找对应的PTE（不是物理页号）。
     /// 如果在查找过程中发现任何中间级别的页表节点不存在（即父级 PTE 无效），它会自动分配
-    /// 一个新的物理页帧来创建该节点，并更新父级 PTE 使其指向新节点。
-    /// 这个方法常用于建立新的虚拟地址映射时，确保页表路径完整。
+    /// 一个新的物理页来创建该节点，并更新父级 PTE 使其指向新节点。
+    /// !返回的页可能是无效的 
     // 1. 首先获取 `vpn` 的三级索引。
     // 2. 从根页表（一级页表，其位置由 `self.root_ppn` 给出）开始。
     // 3. 循环遍历页表层级（一级 -> 二级 -> 三级）。在每一级：
@@ -162,6 +166,7 @@ impl PageTable {
         }
         result
     }
+    /// 要求传来一个物理页号，调用者要分配一个物理页。
     /// 在当前的页表 (self) 中，为虚拟页号 VPN 建立一个到物理页号 PPN 的映射，
     /// 并设置该映射的权限和状态标志 flags。
     #[allow(unused)]
@@ -197,11 +202,14 @@ impl PageTable {
     }
     /// get the page table entry from the virtual page number
     pub fn translate(&self, vpn: VirtPageNum) -> Option<PageTableEntry> {
-        self.find_pte(vpn).map(|pte| *pte)
+        self.find_pte(vpn)
+        .map(|pte| *pte)
     }
-    /// get the token from the page table
+    /// 获取本页表的satp
     pub fn token(&self) -> usize {
+        // |Mode| ASID |  PPN |, Mode=8表示开启SV39，Umode和Smode的访存都视为39位虚拟地址。
         8usize << 60 | self.root_ppn.0
+        // https://rcore-os.cn/rCore-Tutorial-Book-v3/chapter4/3sv39-implementation-1.html#satp-layout
     }
 }