[wip] enable doctests (without running)

berkus · berkus · commit 87cd7358b413 · 2026-02-21T23:12:45.000+02:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Justfile b/Justfile
@@ -222,9 +222,13 @@ test: test-device test-chainboot test-host
 [group("emu")]
 test-device:
     RUSTFLAGS="{{ fixed_rustflags }} {{ board_rpi3_flags }} -C link-arg=--script={{ test_link }}" \
-    cargo test {{ target_json }} --features=qemu {{ rust_std }} \
+    cargo test --tests {{ target_json }} --features=qemu {{ rust_std }} \
       --workspace --exclude=chainofcommand --exclude=chainboot
 
+    RUSTFLAGS="{{ fixed_rustflags }} {{ board_rpi3_flags }} -C link-arg=--script={{ test_link }}" \
+    cargo test --doc {{ target_json }} --features=qemu {{ rust_std }} \
+    --workspace --exclude=chainofcommand --exclude=chainboot
+
 # Run chainboot tests in QEMU (rpi3) with its own linker script
 [group("emu")]
 test-chainboot:
diff --git a/kernel/nucleus/Cargo.toml b/kernel/nucleus/Cargo.toml
@@ -32,29 +32,18 @@ qemu = [
 
 [dependencies]
 aarch64-cpu = { workspace = true }
-# bit_field = { workspace = true }
 bitflags = { workspace = true }
 cfg-if = { workspace = true }
 libaddress = { workspace = true }
-# libconsole = { workspace = true }
 libcpu = { workspace = true }
 libexception = { workspace = true }
-# libkernel-state = { workspace = true }
 liblocking = { workspace = true }
 liblog = { workspace = true }
 libmachine = { workspace = true }
 libmapping = { workspace = true }
 libobject = { workspace = true }
-# libplatform = { workspace = true }
 libprint = { workspace = true }
 libqemu = { workspace = true, optional = true }
-# libsyscall = { workspace = true }
-# libtime = { workspace = true }
-# snafu = { workspace = true }
-# static_assertions = { workspace = true }
-# tock-registers = { workspace = true }
-# usize_conversions = { workspace = true }
-# ux = { workspace = true }
 
 [dev-dependencies]
 libexception = { workspace = true, features = ["test_build"] }
diff --git a/kernel/nucleus/src/main.rs b/kernel/nucleus/src/main.rs
@@ -120,9 +120,11 @@ extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {
 #[unsafe(no_mangle)]
 extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {
     {
+        use aarch64_cpu::registers::{ESR_EL1, Readable};
+
         const TEST_SVC_ID: u64 = 0x1337;
 
-        let esr_el1 = esr_el1::EsrEL1(LocalRegisterCopy::new(ESR_EL1.get()));
+        let esr_el1 = libexception::arch::esr_el1::EsrEL1(LocalRegisterCopy::new(ESR_EL1.get()));
 
         if let Some(ESR_EL1::EC::Value::SVC64) = esr_el1.exception_class()
             && esr_el1.iss() == TEST_SVC_ID
@@ -132,7 +134,7 @@ extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {
         }
     }
 
-    if debug::exception_dump(e) {
+    if libdebug::exception_dump(e) {
         return;
     }
 
diff --git a/libs/address/src/lib.rs b/libs/address/src/lib.rs
@@ -75,7 +75,11 @@ impl const PageSize for u64 {
         *self
     }
     fn mask(&self) -> u64 {
-        !(self - 1)
+        assert!(
+            self.is_power_of_two(),
+            "PageSize must be a power of two to use as mask"
+        );
+        self - 1
     }
 }
 
@@ -84,7 +88,11 @@ impl const PageSize for usize {
         *self as u64
     }
     fn mask(&self) -> u64 {
-        !(self - 1) as u64
+        assert!(
+            self.is_power_of_two(),
+            "PageSize must be a power of two to use as mask"
+        );
+        (self - 1) as u64
     }
 }
 
diff --git a/libs/address/tests/address.rs b/libs/address/tests/address.rs
@@ -28,6 +28,8 @@ fn address_type_method_sanity() {
 
     let addr = Address::<Virtual>::new(SIZE + 100);
 
+    assert_eq!(addr.as_u64(), SIZE + 100);
+
     assert_eq!(addr.align_down_page(&SIZE), SIZE.into());
 
     assert_eq!(addr.align_up_page(&SIZE), (SIZE * 2).into());
diff --git a/libs/alloc/Cargo.toml b/libs/alloc/Cargo.toml
@@ -25,6 +25,7 @@ liblog = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/boot/Cargo.toml b/libs/boot/Cargo.toml
@@ -27,6 +27,7 @@ tock-registers = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/console/Cargo.toml b/libs/console/Cargo.toml
@@ -35,6 +35,7 @@ libqemu = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/cpu/Cargo.toml b/libs/cpu/Cargo.toml
@@ -28,6 +28,7 @@ aarch64-cpu = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 # For proper testing in libcpu, we build it as a test_runner binary!
 
diff --git a/libs/driver/Cargo.toml b/libs/driver/Cargo.toml
@@ -31,6 +31,7 @@ liblog = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/exception/Cargo.toml b/libs/exception/Cargo.toml
@@ -32,6 +32,7 @@ tock-registers = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/exception/src/arch/aarch64/esr_el1.rs b/libs/exception/src/arch/aarch64/esr_el1.rs
@@ -12,7 +12,7 @@ impl EsrEL1 {
 
     #[cfg(any(test, feature = "test_build"))]
     #[inline(always)]
-    #[expect(dead_code)]
+    #[allow(dead_code)]
     pub fn iss(&self) -> u64 {
         self.0.read(ESR_EL1::ISS)
     }
diff --git a/libs/exception/src/arch/aarch64/mod.rs b/libs/exception/src/arch/aarch64/mod.rs
@@ -54,7 +54,7 @@ use {
 };
 
 mod debug;
-mod esr_el1;
+pub mod esr_el1;
 mod exception_context;
 mod spsr_el1;
 
diff --git a/libs/kernel-state/Cargo.toml b/libs/kernel-state/Cargo.toml
@@ -23,6 +23,7 @@ maintenance = { status = "experimental" }
 
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/local-irq/Cargo.toml b/libs/local-irq/Cargo.toml
@@ -28,6 +28,7 @@ tock-registers = { workspace = true }
 
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/locking/Cargo.toml b/libs/locking/Cargo.toml
@@ -27,6 +27,7 @@ liblocal-irq = { workspace = true }
 
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/log/Cargo.toml b/libs/log/Cargo.toml
@@ -24,6 +24,7 @@ maintenance = { status = "experimental" }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/log/src/lib.rs b/libs/log/src/lib.rs
@@ -11,9 +11,9 @@
 #![no_std]
 #![no_main]
 #![feature(format_args_nl)]
-// #![feature(custom_test_frameworks)]
-// #![test_runner(libtest::test_runner)]
-// #![reexport_test_harness_main = "test_main"]
+#![feature(custom_test_frameworks)]
+#![test_runner(libtest::test_runner)]
+#![reexport_test_harness_main = "test_main"]
 
 use core::{
     error::Error,
@@ -52,7 +52,7 @@ static LEVEL_PARSE_ERROR: &str =
 /// An enum representing the available verbosity levels of the logger.
 ///
 #[repr(isize)]
-#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Level {
     Print = -2,
     PrintLn = -1,
@@ -95,13 +95,21 @@ impl Level {
     ///
     /// # Examples
     ///
-    /// ```
-    /// use log::Level;
+    /// ```no_run
+    /// # #![no_std]
+    /// # #![no_main]
+    /// # #[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
+    /// # #[unsafe(no_mangle)] pub extern "C" fn main() {
+    /// # use core::assert_eq;
+    /// # use core::iter::Iterator;
+    /// # use core::option::Option::Some;
+    /// use liblog::Level;
     ///
     /// let mut levels = Level::iter();
     ///
     /// assert_eq!(Some(Level::Error), levels.next());
     /// assert_eq!(Some(Level::Trace), levels.last());
+    /// # }
     /// ```
     pub fn iter() -> impl Iterator<Item = Self> {
         (1..6).map(|i| Self::from_usize(i).unwrap())
@@ -114,14 +122,20 @@ impl Level {
     ///
     /// # Examples
     ///
-    /// ```
-    /// use log::Level;
+    /// ```no_run
+    /// # #![no_std]
+    /// # #![no_main]
+    /// # #[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
+    /// # #[unsafe(no_mangle)] pub extern "C" fn main() {
+    /// # use core::assert_eq;
+    /// use liblog::Level;
     ///
     /// let level = Level::Info;
     ///
     /// assert_eq!(Level::Debug, level.increment_severity());
     /// assert_eq!(Level::Trace, level.increment_severity().increment_severity());
     /// assert_eq!(Level::Trace, level.increment_severity().increment_severity().increment_severity()); // max level
+    /// # }
     /// ```
     #[must_use]
     pub fn increment_severity(&self) -> Self {
@@ -136,14 +150,20 @@ impl Level {
     ///
     /// # Examples
     ///
-    /// ```
-    /// use log::Level;
+    /// ```no_run
+    /// # #![no_std]
+    /// # #![no_main]
+    /// # #[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
+    /// # #[unsafe(no_mangle)] pub extern "C" fn main() {
+    /// # use core::assert_eq;
+    /// use liblog::Level;
     ///
     /// let level = Level::Info;
     ///
     /// assert_eq!(Level::Warn, level.decrement_severity());
     /// assert_eq!(Level::Error, level.decrement_severity().decrement_severity());
     /// assert_eq!(Level::Error, level.decrement_severity().decrement_severity().decrement_severity()); // min level
+    /// # }
     /// ```
     #[must_use]
     pub fn decrement_severity(&self) -> Self {
@@ -152,7 +172,7 @@ impl Level {
     }
 }
 
-#[derive(Clone, Debug)]
+#[derive(Clone)]
 pub struct Record<'a> {
     level: Level,
     args: fmt::Arguments<'a>,
@@ -178,7 +198,6 @@ impl<'a> Record<'a> {
     }
 }
 
-#[derive(Debug)]
 pub struct RecordBuilder<'a> {
     record: Record<'a>,
 }
@@ -375,29 +394,28 @@ pub fn max_level() -> Level {
 ///
 /// # Examples
 ///
-/// ```
-/// use liblog::{error, info, warn, Record, Level, Metadata, LevelFilter};
+/// ```no_run
+/// # #![no_std]
+/// # #![no_main]
+/// # #![feature(format_args_nl)]
+/// # #[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
+/// use liblog::{error, info, warn, Record, Level};
 ///
 /// static MY_LOGGER: MyLogger = MyLogger;
 ///
 /// struct MyLogger;
 ///
-/// impl log::Log for MyLogger {
-///     fn enabled(&self, metadata: &Metadata) -> bool {
-///         metadata.level() <= Level::Info
-///     }
-///
+/// impl liblog::Log for MyLogger {
+///     fn enabled(&self, level: Level) -> bool { true }
 ///     fn log(&self, record: &Record) {
-///         if self.enabled(record.metadata()) {
-///             println!("{} - {}", record.level(), record.args());
-///         }
+///         liblog::println!("{:?} - {}", record.level(), record.args());
 ///     }
 ///     fn flush(&self) {}
 /// }
 ///
-/// # fn main(){
+/// # #[unsafe(no_mangle)] fn main(){
 /// liblog::set_logger(&MY_LOGGER).unwrap();
-/// liblog::set_max_level(LevelFilter::Info);
+/// liblog::set_max_level(Level::Info);
 ///
 /// info!("hello log");
 /// warn!("warning");
diff --git a/libs/machine/Cargo.toml b/libs/machine/Cargo.toml
@@ -34,6 +34,7 @@ libqemu = { workspace = true }
 
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/mapping/Cargo.toml b/libs/mapping/Cargo.toml
@@ -24,6 +24,7 @@ libmmio = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/memory/Cargo.toml b/libs/memory/Cargo.toml
@@ -28,6 +28,7 @@ tock-registers = { workspace = true }
 
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/mmio/Cargo.toml b/libs/mmio/Cargo.toml
@@ -22,6 +22,7 @@ libaddress = { workspace = true }
 # Tests are offloaded to kernel integration tests binary.
 [lib]
 test = false
+harness = false
 
 [lints]
 workspace = true
diff --git a/libs/object/Cargo.toml b/libs/object/Cargo.toml
diff --git a/libs/platform/Cargo.toml b/libs/platform/Cargo.toml
diff --git a/libs/platform/src/lib.rs b/libs/platform/src/lib.rs
diff --git a/libs/platform/src/raspberrypi/device_driver/arm/gicv2/mod.rs b/libs/platform/src/raspberrypi/device_driver/arm/gicv2/mod.rs
diff --git a/libs/primitives/Cargo.toml b/libs/primitives/Cargo.toml
diff --git a/libs/print/Cargo.toml b/libs/print/Cargo.toml
diff --git a/libs/qemu/Cargo.toml b/libs/qemu/Cargo.toml
diff --git a/libs/syscall/Cargo.toml b/libs/syscall/Cargo.toml
diff --git a/libs/test/Cargo.toml b/libs/test/Cargo.toml
diff --git a/libs/time/Cargo.toml b/libs/time/Cargo.toml

Original file line number	Diff line number	Diff line change
`@@ -120,9 +120,11 @@ extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {`
`120`	`120`	`#[unsafe(no_mangle)]`
`121`	`121`	`extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {`
`122`	`122`	`{`
	`123`	`+ use aarch64_cpu::registers::{ESR_EL1, Readable};`
	`124`	`+`
`123`	`125`	`const TEST_SVC_ID: u64 = 0x1337;`
`124`	`126`
`125`		`- let esr_el1 = esr_el1::EsrEL1(LocalRegisterCopy::new(ESR_EL1.get()));`
	`127`	`+ let esr_el1 = libexception::arch::esr_el1::EsrEL1(LocalRegisterCopy::new(ESR_EL1.get()));`
`126`	`128`
`127`	`129`	`if let Some(ESR_EL1::EC::Value::SVC64) = esr_el1.exception_class()`
`128`	`130`	`&& esr_el1.iss() == TEST_SVC_ID`
`@@ -132,7 +134,7 @@ extern "C" fn current_elx_synchronous(e: &mut ExceptionContext) {`
`132`	`134`	`}`
`133`	`135`	`}`
`134`	`136`
`135`		`- if debug::exception_dump(e) {`
	`137`	`+ if libdebug::exception_dump(e) {`
`136`	`138`	`return;`
`137`	`139`	`}`
`138`	`140`
Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,11 @@ impl const PageSize for u64 {`
`75`	`75`	`*self`
`76`	`76`	`}`
`77`	`77`	`fn mask(&self) -> u64 {`
`78`		`- !(self - 1)`
	`78`	`+ assert!(`
	`79`	`+ self.is_power_of_two(),`
	`80`	`+ "PageSize must be a power of two to use as mask"`
	`81`	`+ );`
	`82`	`+ self - 1`
`79`	`83`	`}`
`80`	`84`	`}`
`81`	`85`
`@@ -84,7 +88,11 @@ impl const PageSize for usize {`
`84`	`88`	`*self as u64`
`85`	`89`	`}`
`86`	`90`	`fn mask(&self) -> u64 {`
`87`		`- !(self - 1) as u64`
	`91`	`+ assert!(`
	`92`	`+ self.is_power_of_two(),`
	`93`	`+ "PageSize must be a power of two to use as mask"`
	`94`	`+ );`
	`95`	`+ (self - 1) as u64`
`88`	`96`	`}`
`89`	`97`	`}`
`90`	`98`