doc: add documents of some crates

Author: equation314

Cargo.toml

@@ -3,8 +3,11 @@ name = "page_table_entry"
 version = "0.1.0"
 edition = "2021"
 authors = ["Yuekai Jia <[email protected]>"]
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+description = "Page table entry definition for various hardware architectures"
+license = "GPL-3.0-or-later OR Apache-2.0"
+homepage = "https://github.com/rcore-os/arceos"
+repository = "https://github.com/rcore-os/arceos/tree/main/crates/page_table_entry"
+documentation = "https://rcore-os.github.io/arceos/page_table_entry/index.html"
 
 [dependencies]
 bitflags = "2.1"

src/arch/aarch64.rs

@@ -1,3 +1,5 @@
+//! AArch64 VMSAv8-64 translation table format descriptors.
+
 use core::fmt;
 use memory_addr::PhysAddr;
 
@@ -135,13 +137,19 @@ impl From<MappingFlags> for DescriptorAttr {
     }
 }
 
+/// A VMSAv8-64 translation table descriptor.
+///
+/// Note that the **AttrIndx\[2:0\]** (bit\[4:2\]) field is set to `0` for device
+/// memory, and `1` for normal memory. The system must configure the MAIR_ELx
+/// system register accordingly.
 #[derive(Clone, Copy)]
 #[repr(transparent)]
 pub struct A64PTE(u64);
 
 impl A64PTE {
     const PHYS_ADDR_MASK: usize = 0x0000_ffff_ffff_f000; // bits 12..48
 
+    /// Creates an empty descriptor with all bits set to zero.
     pub const fn empty() -> Self {
         Self(0)
     }

src/arch/riscv.rs

@@ -1,3 +1,5 @@
+//! RISC-V page table entries.
+
 use core::fmt;
 use memory_addr::PhysAddr;
 
@@ -69,7 +71,7 @@ impl From<MappingFlags> for PTEFlags {
     }
 }
 
-/// Sv39 and Sv48 page table entry.
+/// Sv39 and Sv48 page table entry for RV64 systems.
 #[derive(Clone, Copy)]
 #[repr(transparent)]
 pub struct Rv64PTE(u64);

src/arch/x86_64.rs

@@ -1,6 +1,9 @@
+//! x86 page table entries on 64-bit paging.
+
 use core::fmt;
 use memory_addr::PhysAddr;
-use x86_64::structures::paging::page_table::PageTableFlags as PTF;
+
+pub use x86_64::structures::paging::page_table::PageTableFlags as PTF;
 
 use crate::{GenericPTE, MappingFlags};
 
@@ -48,6 +51,7 @@ impl From<MappingFlags> for PTF {
     }
 }
 
+/// An x86_64 page table entry.
 #[derive(Clone, Copy)]
 #[repr(transparent)]
 pub struct X64PTE(u64);

src/lib.rs

@@ -1,3 +1,15 @@
+//! This crate provides the definition of page table entry for various hardware
+//! architectures.
+//!
+//! Currently supported architectures and page table entry types:
+//!
+//! - x86: [`x86_64::X64PTE`]
+//! - ARM: [`aarch64::A64PTE`]
+//! - RISC-V: [`riscv::Rv64PTE`]
+//!
+//! All these types implement the [`GenericPTE`] trait, which provides unified
+//! methods for manipulating various page table entries.
+
 #![no_std]
 #![feature(const_trait_impl)]
 #![feature(doc_auto_cfg)]
@@ -11,20 +23,30 @@ use memory_addr::PhysAddr;
 pub use self::arch::*;
 
 bitflags::bitflags! {
+    /// Generic page table entry flags that indicate the corresponding mapped
+    /// memory region permissions and attributes.
     #[derive(Debug, Clone, Copy)]
     pub struct MappingFlags: usize {
+        /// The memory is readable.
         const READ          = 1 << 0;
+        /// The memory is writable.
         const WRITE         = 1 << 1;
+        /// The memory is executable.
         const EXECUTE       = 1 << 2;
+        /// The memory is user accessible.
         const USER          = 1 << 3;
+        /// The memory is device memory.
         const DEVICE        = 1 << 4;
     }
 }
 
+/// A generic page table entry.
+///
+/// All architecture-specific page table entry types implement this trait.
 pub trait GenericPTE: Debug + Clone + Copy + Sync + Send + Sized {
-    // Create a page table entry point to a terminate page or block.
+    /// Create a page table entry point to a terminate page or block.
     fn new_page(paddr: PhysAddr, flags: MappingFlags, is_huge: bool) -> Self;
-    // Create a page table entry point to a next level page table.
+    /// Create a page table entry point to a next level page table.
     fn new_table(paddr: PhysAddr) -> Self;
 
     /// Returns the physical address mapped by this entry.