From b5e04ea5ad0d62aeb590b415972513e29d500b2f Mon Sep 17 00:00:00 2001
From: Zhang Junyang <zhangjunyang.zjy@antgroup.com>
Date: Fri, 21 Jul 2023 12:34:53 +0800
Subject: [PATCH] Fix boot documentations and comments

---
 .../jinux-frame/src/arch/x86/boot/memory_region.rs    | 11 +++++++----
 framework/jinux-frame/src/arch/x86/boot/mod.rs        |  8 ++++----
 .../jinux-frame/src/arch/x86/boot/multiboot2/mod.rs   |  4 +++-
 3 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/framework/jinux-frame/src/arch/x86/boot/memory_region.rs b/framework/jinux-frame/src/arch/x86/boot/memory_region.rs
index 187a392e2..304639b1b 100644
--- a/framework/jinux-frame/src/arch/x86/boot/memory_region.rs
+++ b/framework/jinux-frame/src/arch/x86/boot/memory_region.rs
@@ -6,8 +6,8 @@ use alloc::{vec, vec::Vec};
 
 use crate::config::PAGE_SIZE;
 
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 /// The type of initial memory regions that are needed for the kernel.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 pub enum MemoryRegionType {
     /// Maybe points to an unplugged DIMM module. It's bad anyway.
     BadMemory = 0,
@@ -27,9 +27,9 @@ pub enum MemoryRegionType {
     Usable = 7,
 }
 
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 /// The information of initial memory regions that are needed by the kernel.
 /// The sections are **not** guaranteed to not overlap. The region must be page aligned.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
 pub struct MemoryRegion {
     base: usize,
     len: usize,
@@ -43,12 +43,15 @@ impl MemoryRegion {
         let aligned_end;
         match typ {
             MemoryRegionType::Usable | MemoryRegionType::Reclaimable => {
-                // Align shrinked.
+                // Align shrinked. These regions may be used by the frame allocator.
                 aligned_base = base.align_up(PAGE_SIZE);
                 aligned_end = (base + len).align_down(PAGE_SIZE);
             }
             _ => {
-                // Align bloated.
+                // We can align other regions in a bloated manner since we do not
+                // use MemoryRegion as a way to deliver objects. They are just
+                // markers of untouchable memory areas or areas that need special
+                // treatments.
                 aligned_base = base.align_down(PAGE_SIZE);
                 aligned_end = (base + len).align_up(PAGE_SIZE);
             }
diff --git a/framework/jinux-frame/src/arch/x86/boot/mod.rs b/framework/jinux-frame/src/arch/x86/boot/mod.rs
index f93a3d4cb..65a887bbf 100644
--- a/framework/jinux-frame/src/arch/x86/boot/mod.rs
+++ b/framework/jinux-frame/src/arch/x86/boot/mod.rs
@@ -1,8 +1,8 @@
 //! The boot module defines the entrypoints of Jinux and the corresponding
 //! headers for different bootloaders.
 //!
-//! We currently support Multiboot2 and the Limine Boot Protocol. The
-//! support for Linux boot protocol is on its way.
+//! We currently support Multiboot2. The support for Linux Boot Protocol is
+//! on its way.
 //!
 //! In this module, we use println! to print information on screen rather
 //! than logging since the logger is not initialized here.
@@ -19,10 +19,10 @@ pub use memory_region::*;
 use alloc::{string::String, vec::Vec};
 use spin::Once;
 
-#[derive(Copy, Clone, Debug)]
 /// The boot crate can choose either providing the raw RSDP physical address or
 /// providing the RSDT/XSDT physical address after parsing RSDP.
 /// This is because bootloaders differ in such behaviors.
+#[derive(Copy, Clone, Debug)]
 pub enum BootloaderAcpiArg {
     /// Physical address of the RSDP.
     Rsdp(usize),
@@ -32,8 +32,8 @@ pub enum BootloaderAcpiArg {
     Xsdt(usize),
 }
 
-#[derive(Copy, Clone, Debug)]
 /// The framebuffer arguments.
+#[derive(Copy, Clone, Debug)]
 pub struct BootloaderFramebufferArg {
     pub address: usize,
     pub width: usize,
diff --git a/framework/jinux-frame/src/arch/x86/boot/multiboot2/mod.rs b/framework/jinux-frame/src/arch/x86/boot/multiboot2/mod.rs
index 7a6200d3f..435d48f38 100644
--- a/framework/jinux-frame/src/arch/x86/boot/multiboot2/mod.rs
+++ b/framework/jinux-frame/src/arch/x86/boot/multiboot2/mod.rs
@@ -182,12 +182,14 @@ pub fn init_memory_regions() {
     MEMORY_REGIONS.call_once(|| regions_unusable);
 }
 
+/// The entry point of kernel code, which should be defined by the package that
+/// uses jinux-frame.
 extern "Rust" {
     fn jinux_main() -> !;
 }
 
-#[no_mangle]
 /// The entry point of Rust code called by inline asm.
+#[no_mangle]
 unsafe extern "C" fn __multiboot2_entry(boot_magic: u32, boot_params: u64) -> ! {
     assert_eq!(boot_magic, MULTIBOOT2_ENTRY_MAGIC);
     MB2_INFO.call_once(|| unsafe {