fix: hal 内部不再输出文档

Signed-off-by: YdrMaster <ydrml@hotmail.com>

Author: YdrMaster

fast-trap/Cargo.toml

@@ -16,7 +16,3 @@ categories = ["embedded", "hardware-support", "no-std"]
 [features]
 riscv-s = []
 riscv-m = []
-
-[package.metadata.docs.rs]
-targets = ["riscv32imac-unknown-none-elf", "riscv64imac-unknown-none-elf"]
-features = ["riscv-s", "riscv-m"]

fast-trap/src/hal/mod.rs

@@ -1,13 +1,50 @@
-mod riscv;
-#[cfg(feature = "riscv-m")]
-#[macro_use]
-mod riscv_m;
-#[cfg(feature = "riscv-s")]
-#[macro_use]
-mod riscv_s;
+#[cfg(not(doc))]
+mod riscv;
 
+#[cfg(not(doc))]
 pub use riscv::*;
-#[cfg(feature = "riscv-m")]
-pub use riscv_m::*;
-#[cfg(feature = "riscv-s")]
-pub use riscv_s::*;
+
+mod doc {
+    #![allow(unused)]
+
+    /// 设置全局陷入入口。
+    ///
+    /// # Safety
+    ///
+    /// 这个函数操作硬件寄存器，寄存器里原本的值将丢弃。
+    pub unsafe fn load_direct_trap_entry() {}
+
+    /// 把当前栈复用为陷入栈，预留 Handler 空间。
+    ///
+    /// # Safety
+    ///
+    /// 裸指针，直接移动 sp，只能在纯汇编环境调用。
+    pub unsafe extern "C" fn reuse_stack_for_trap() {}
+
+    /// 模拟一个 `cause` 类的陷入。
+    ///
+    /// # Safety
+    ///
+    /// 如同发生一个陷入。
+    pub fn soft_trap(cause: usize) {}
+
+    /// 陷入处理例程。
+    ///
+    /// # Safety
+    ///
+    /// 不要直接调用这个函数。暴露它仅仅是为了提供其入口的符号链接。
+    pub unsafe extern "C" fn trap_entry() {}
+
+    /// 陷入上下文。
+    ///
+    /// 保存了陷入时的寄存器状态。包括所有通用寄存器和 `pc`。
+    pub struct FlowContext {}
+
+    impl FlowContext {
+        /// 零初始化。
+        pub const ZERO: Self = Self {};
+    }
+}
+
+#[cfg(doc)]
+pub use doc::*;

fast-trap/src/hal/riscv.rs renamed to fast-trap/src/hal/riscv/mod.rs

@@ -1,5 +1,11 @@
-use crate::TrapHandler;
-use core::alloc::Layout;
+#![allow(missing_docs)]
+
+#[cfg(feature = "riscv-m")]
+#[macro_use]
+mod riscv_m;
+#[cfg(feature = "riscv-s")]
+#[macro_use]
+mod riscv_s;
 
 #[cfg(target_pointer_width = "32")]
 #[macro_use]
@@ -64,11 +70,14 @@ mod arch {
     }
 }
 
-use super::{exchange, r#return};
+use crate::TrapHandler;
+use core::alloc::Layout;
+
+#[cfg(feature = "riscv-m")]
+pub use riscv_m::*;
+#[cfg(feature = "riscv-s")]
+pub use riscv_s::*;
 
-/// 陷入上下文。
-///
-/// 保存了陷入时的寄存器状态。包括所有通用寄存器和 `pc`。
 #[repr(C)]
 #[allow(missing_docs)]
 pub struct FlowContext {
@@ -96,11 +105,9 @@ impl FlowContext {
     };
 }
 
-/// 把当前栈复用为陷入栈，预留 Handler 空间。
-///
 /// # Safety
 ///
-/// 裸指针，直接移动 sp，只能在纯汇编环境调用。
+/// See [proto](crate::hal::doc::reuse_stack_for_trap).
 #[naked]
 pub unsafe extern "C" fn reuse_stack_for_trap() {
     const LAYOUT: Layout = Layout::new::<TrapHandler>();
@@ -115,11 +122,9 @@ pub unsafe extern "C" fn reuse_stack_for_trap() {
     )
 }
 
-/// 陷入处理例程。
-///
 /// # Safety
 ///
-/// 不要直接调用这个函数。暴露它仅仅是为了提供其入口的符号链接。
+/// See [proto](crate::hal::doc::trap_entry).
 #[naked]
 pub unsafe extern "C" fn trap_entry() {
     core::arch::asm!(

fast-trap/src/hal/riscv_m.rs renamed to fast-trap/src/hal/riscv/riscv_m.rs

@@ -44,11 +44,9 @@ pub(crate) fn exchange_scratch(mut val: usize) -> usize {
     val
 }
 
-/// 模拟一个 `cause` 类的陷入。
-///
 /// # Safety
 ///
-/// 如同发生一个陷入。
+/// See [proto](crate::hal::doc::soft_trap).
 #[inline]
 pub unsafe fn soft_trap(cause: usize) {
     asm!(
@@ -64,11 +62,9 @@ pub unsafe fn soft_trap(cause: usize) {
     );
 }
 
-/// 设置全局陷入入口。
-///
 /// # Safety
 ///
-/// 这个函数操作硬件寄存器，寄存器里原本的值将丢弃。
+/// See [proto](crate::hal::doc::load_direct_trap_entry).
 #[inline]
 pub unsafe fn load_direct_trap_entry() {
     asm!("csrw mtvec, {0}", in(reg) trap_entry, options(nomem))

fast-trap/src/hal/riscv_s.rs renamed to fast-trap/src/hal/riscv/riscv_s.rs

@@ -10,7 +10,7 @@ mod hal;
 
 pub use entire::*;
 pub use fast::*;
-pub use hal::*;
+pub use hal::{load_direct_trap_entry, reuse_stack_for_trap, soft_trap, trap_entry, FlowContext};
 
 use core::{
     alloc::Layout,
@@ -58,7 +58,7 @@ impl FreeTrapStack {
     /// 将这个陷入栈加载为预备陷入栈。
     #[inline]
     pub fn load(self) -> LoadedTrapStack {
-        let scratch = exchange_scratch(self.0.as_ptr() as _);
+        let scratch = hal::exchange_scratch(self.0.as_ptr() as _);
         forget(self);
         LoadedTrapStack(scratch)
     }
@@ -96,7 +96,7 @@ impl LoadedTrapStack {
     /// 间接复制了所有权。用于 `Drop`。
     #[inline]
     unsafe fn unload_unchecked(&self) -> FreeTrapStack {
-        let ptr = exchange_scratch(self.0) as *mut TrapHandler;
+        let ptr = hal::exchange_scratch(self.0) as *mut TrapHandler;
         let handler = unsafe { NonNull::new_unchecked(ptr) };
         FreeTrapStack(handler)
     }