From 84120cd9cfe24145f4df225b809930c19ad8b4ce Mon Sep 17 00:00:00 2001
From: Yuekai Jia <equation618@gmail.com>
Date: Tue, 16 Jul 2024 14:13:09 +0800
Subject: [PATCH] Ready to publish page_table_entry to crates.io

---
 page_table_entry/README.md           | 37 ++++++++++++++++++++++++++++
 page_table_entry/src/arch/aarch64.rs |  3 +++
 page_table_entry/src/arch/riscv.rs   |  3 +++
 page_table_entry/src/arch/x86_64.rs  |  3 +++
 page_table_entry/src/lib.rs          | 15 +++--------
 5 files changed, 49 insertions(+), 12 deletions(-)
 create mode 100644 page_table_entry/README.md

diff --git a/page_table_entry/README.md b/page_table_entry/README.md
new file mode 100644
index 0000000..997526e
--- /dev/null
+++ b/page_table_entry/README.md
@@ -0,0 +1,37 @@
+# page_table_entry
+
+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`][1]
+- ARM: [`aarch64::A64PTE`][2]
+- RISC-V: [`riscv::Rv64PTE`][3]
+
+All these types implement the [`GenericPTE`][4] trait, which provides unified
+methods for manipulating various page table entries.
+
+[1]: https://docs.rs/page_table_entry/latest/page_table_entry/x86_64/struct.X64PTE.html
+[2]: https://docs.rs/page_table_entry/latest/page_table_entry/aarch64/struct.A64PTE.html
+[3]: https://docs.rs/page_table_entry/latest/page_table_entry/riscv/struct.Rv64PTE.html
+[4]: https://docs.rs/page_table_entry/latest/page_table_entry/trait.GenericPTE.html
+
+## Examples (x86_64)
+
+```rust
+use memory_addr::PhysAddr;
+use page_table_entry::{GenericPTE, MappingFlags, x86_64::X64PTE};
+use x86_64::structures::paging::page_table::PageTableFlags;
+
+let paddr = PhysAddr::from(0x233000);
+let pte = X64PTE::new_page(
+    paddr,
+    /*flags:*/ MappingFlags::READ | MappingFlags::WRITE,
+    /*is_huge:*/ false,
+);
+assert!(!pte.is_unused());
+assert!(pte.is_present());
+assert_eq!(pte.paddr(), paddr);
+assert_eq!(pte.bits(), 0x800_0000000233_003); // PRESENT | WRITE | NO_EXECUTE | paddr(0x233000)
+```
diff --git a/page_table_entry/src/arch/aarch64.rs b/page_table_entry/src/arch/aarch64.rs
index 5b88b97..902a04d 100644
--- a/page_table_entry/src/arch/aarch64.rs
+++ b/page_table_entry/src/arch/aarch64.rs
@@ -214,6 +214,9 @@ impl GenericPTE for A64PTE {
         self.0 = (self.0 & Self::PHYS_ADDR_MASK) | attr.bits();
     }
 
+    fn bits(self) -> usize {
+        self.0 as usize
+    }
     fn is_unused(&self) -> bool {
         self.0 == 0
     }
diff --git a/page_table_entry/src/arch/riscv.rs b/page_table_entry/src/arch/riscv.rs
index 16c9fc5..b735821 100644
--- a/page_table_entry/src/arch/riscv.rs
+++ b/page_table_entry/src/arch/riscv.rs
@@ -105,6 +105,9 @@ impl GenericPTE for Rv64PTE {
         self.0 = (self.0 & Self::PHYS_ADDR_MASK) | flags.bits() as u64;
     }
 
+    fn bits(self) -> usize {
+        self.0 as usize
+    }
     fn is_unused(&self) -> bool {
         self.0 == 0
     }
diff --git a/page_table_entry/src/arch/x86_64.rs b/page_table_entry/src/arch/x86_64.rs
index 9ae024c..ded3bb4 100644
--- a/page_table_entry/src/arch/x86_64.rs
+++ b/page_table_entry/src/arch/x86_64.rs
@@ -89,6 +89,9 @@ impl GenericPTE for X64PTE {
         self.0 = (self.0 & Self::PHYS_ADDR_MASK) | flags.bits()
     }
 
+    fn bits(self) -> usize {
+        self.0 as usize
+    }
     fn is_unused(&self) -> bool {
         self.0 == 0
     }
diff --git a/page_table_entry/src/lib.rs b/page_table_entry/src/lib.rs
index bd1a269..adf26b9 100644
--- a/page_table_entry/src/lib.rs
+++ b/page_table_entry/src/lib.rs
@@ -1,18 +1,7 @@
-//! 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(doc_auto_cfg)]
 #![feature(doc_cfg)]
+#![doc = include_str!("../README.md")]
 
 mod arch;
 
@@ -60,6 +49,8 @@ pub trait GenericPTE: Debug + Clone + Copy + Sync + Send + Sized {
     /// Set flags of the entry.
     fn set_flags(&mut self, flags: MappingFlags, is_huge: bool);
 
+    /// Returns the raw bits of this entry.
+    fn bits(self) -> usize;
     /// Returns whether this entry is zero.
     fn is_unused(&self) -> bool;
     /// Returns whether this entry flag indicates present.