From a919d2626b9d176a08b9fa7a0c899a54d9fa02b5 Mon Sep 17 00:00:00 2001 From: Pascal Reich Date: Sat, 10 Jan 2026 23:19:34 +0000 Subject: [PATCH] Inline Documentation Fixes --- ARM-AARCH64-PORT-OUTLINE.md | 76 ++++++++++++++-------------- src/arch/x86_64/interrupt/syscall.rs | 2 +- src/arch/x86_shared/device/mod.rs | 2 +- src/arch/x86_shared/interrupt/mod.rs | 2 +- src/context/memory.rs | 4 +- src/cpu_stats.rs | 2 +- src/event.rs | 2 +- src/main.rs | 12 ++--- src/scheme/user.rs | 4 +- src/sync/ordered.rs | 18 +++---- 10 files changed, 62 insertions(+), 62 deletions(-) diff --git a/ARM-AARCH64-PORT-OUTLINE.md b/ARM-AARCH64-PORT-OUTLINE.md index 8ae61e1967..22925209b9 100644 --- a/ARM-AARCH64-PORT-OUTLINE.md +++ b/ARM-AARCH64-PORT-OUTLINE.md @@ -26,54 +26,54 @@ Once the core kernel port is complete a similar follow on document will be creat ## Boot protocol elements -Item | Notes ------|------- -[Linux kernel boot protocol for AArch64](https://www.kernel.org/doc/Documentation/arm64/booting.txt) | The linked document describes assumptions made from the bootloader which are field tested and worthwhile to have for Redox an AArch64.
The intent is to consider most of the document except anything tied to the Linux kernel itself. -[Flattened Device Tree](https://elinux.org/Device_Tree_Reference) | FDT binary blobs supplied by the bootloader shall provide the Redox kernel with misc platform \{memory, interrupt, devicemem} maps. Qemu's virt machine platform synthetically creates an FDT blob at a specific address which is very handy. +| Item | Notes | +|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Linux kernel boot protocol for AArch64](https://www.kernel.org/doc/Documentation/arm64/booting.txt) | The linked document describes assumptions made from the bootloader which are field tested and worthwhile to have for Redox an AArch64.
The intent is to consider most of the document except anything tied to the Linux kernel itself. | +| [Flattened Device Tree](https://elinux.org/Device_Tree_Reference) | FDT binary blobs supplied by the bootloader shall provide the Redox kernel with misc platform \{memory, interrupt, devicemem} maps. Qemu's virt machine platform synthetically creates an FDT blob at a specific address which is very handy. | ## Boot flow elements The following table lists the boot flow in order. -Item | Notes ------|------- -[ARM Trusted Firmware (TF-A)](https://github.com/ARM-software/arm-trusted-firmware) | TF-A is a de-facto standard reference firmware implementation and proven in the field.
TF-A runs post power-on on Armv8-A implementations and eventually hands off to further stages of the boot flow.
For qemu's virt machine platform, it is essentially absent but I mean to rely on it heavily for silicon bring up hence mentioning it here. -[u-boot](https://www.denx.de/wiki/U-Boot) | u-boot will handle early console access, media access for fetching redox kernel images from non-volatile storage/misc disk subsystems/off the network.
u-boot supports loading EFI applications. If EFI support to AArch64 Redox is added in the future that should essentially work out of the box.
u-boot will load redox and FDT binary blobs into RAM and jump to the redox kernel. -Redox early-init stub | For AArch64, the redox kernel will contain an A64 assembly stub that will setup the MMU from scratch. This is akin to the [x86_64 redox bootloader](https://github.com/redox-os/bootloader/blob/master/x86_64/startup-x86_64.asm).
This stub sets up identity maps for MMU initialization, maps the kernel image itself as well as the device memory for the UART console. At present this stub shall be a part of the kernel itself for simplicity. -Redox kstart entry | The early init stub hands off here. kstart will then re-init the MMU more comprehensively. +| Item | Notes | +|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [ARM Trusted Firmware (TF-A)](https://github.com/ARM-software/arm-trusted-firmware) | TF-A is a de-facto standard reference firmware implementation and proven in the field.
TF-A runs post power-on on Armv8-A implementations and eventually hands off to further stages of the boot flow.
For qemu's virt machine platform, it is essentially absent but I mean to rely on it heavily for silicon bring up hence mentioning it here. | +| [u-boot](https://www.denx.de/wiki/U-Boot) | u-boot will handle early console access, media access for fetching redox kernel images from non-volatile storage/misc disk subsystems/off the network.
u-boot supports loading EFI applications. If EFI support to AArch64 Redox is added in the future that should essentially work out of the box.
u-boot will load redox and FDT binary blobs into RAM and jump to the redox kernel. | +| Redox early-init stub | For AArch64, the redox kernel will contain an A64 assembly stub that will setup the MMU from scratch. This is akin to the [x86_64 redox bootloader](https://github.com/redox-os/bootloader/blob/master/x86_64/startup-x86_64.asm).
This stub sets up identity maps for MMU initialization, maps the kernel image itself as well as the device memory for the UART console. At present this stub shall be a part of the kernel itself for simplicity. | +| Redox kstart entry | The early init stub hands off here. kstart will then re-init the MMU more comprehensively. | ## Supported devices The following devices shall be supported. All necessary information specific to these devices will be provided to the redox kernel by the platform specific FDT binary blob. -Device | Notes --------|------- -[Generic Interrupt Controller v2](https://developer.arm.com/products/architecture/a-profile/docs/ihi0048/b/arm-generic-interrupt-controller-architecture-version-20-architecture-specification) | The GIC is an Arm-v8A architectural element and is supported by all architecturally compliant processor implementations. GICv2 is supported by qemu's virt machine emulation and most subsequent GIC implementations are backward compatible to GICv2. -[Generic Timer](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0500d/BGBBIJCB.html) | The Generic Timer Architecture is an Arm-v8A architectural element and is implemented by all compliant processor implementations. It is supported by qemu. -[PrimeCell UART PL011](http://infocenter.arm.com/help/topic/com.arm.doc.ddi0183f/DDI0183.pdf) | The PL011 UART is supported by qemu and most ARM systems. +| Device | Notes | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Generic Interrupt Controller v2](https://developer.arm.com/products/architecture/a-profile/docs/ihi0048/b/arm-generic-interrupt-controller-architecture-version-20-architecture-specification) | The GIC is an Arm-v8A architectural element and is supported by all architecturally compliant processor implementations. GICv2 is supported by qemu's virt machine emulation and most subsequent GIC implementations are backward compatible to GICv2. | +| [Generic Timer](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0500d/BGBBIJCB.html) | The Generic Timer Architecture is an Arm-v8A architectural element and is implemented by all compliant processor implementations. It is supported by qemu. | +| [PrimeCell UART PL011](http://infocenter.arm.com/help/topic/com.arm.doc.ddi0183f/DDI0183.pdf) | The PL011 UART is supported by qemu and most ARM systems. | ## Intended development sequence and status -Item | Description | Status | Notes ------|-------|-----|----- -Redox AArch64 toolchain | Create an usable redox AArch64 toolchain specification | Done | Using this JSON spec in isolated tests produces valid AArch64 soft float code -Stubbed kernel image | Stub out AArch64 kernel support using the existing x86_64 arch code as a template
Modify redox kernel build glue and work iteratively to get a linkable (non-functional) image | Not done yet | -Boot flow | Create a self hosted u-boot -> redox kernel workflow
Should obtain the stubbed image from a local TFTP server, load it into RAM and jump to it | Not done yet | -GDB Debug flow | Create a debug workflow centered around qemu's GDB stub
This should allow connecting to qemu's GDB stub and debug u-boot/redox stub via a GDB client and single stepping through code | Not done yet | -Verify Redox entry | Verify that control reaches the redox kernel from u-boot | Not done yet | -AArch64 early init stub | Add support for raw asm code for early AArch64 init in the redox kernel
Verify that this code is located appropriately in the link map and that control reaches this code from u-boot | Not done yet | -Basic DTB support | Integrate the [device_tree crate](https://mbr.github.io/device_tree-rs/device_tree/)
Use the crate to access the qemu supplied DTB image and extract the memory map | Not done yet | -Basic UART support | Use the device_tree crate to get the UART address from the DTB image and set up the initial console
This is a polling mode only setup | Not done yet | -Initial MMU support | Implement initial MMU support in the early init stub
This forces the MMU into a clean state overriding any bootloader specific setup
Create an identity map for MMU init
Create a mapping for the kernel image
Create a mapping for any devices needed at this stage (UART)| Not done yet | -kmain entry | Verify that kmain entry works post early MMU init | Not done yet | -Basic Redox MMU support | Get Redox to create a final set of mappings for everything
Verify that this works as expected| Not done yet | -Basic libc support | Flesh out a basic set of libc calls as required for simple user-land apps | Not done yet | -userspace_init entry | Verify user-space entry and /sbin/init invocation | Not done yet | -Basic Interrupt controller support | Add a GIC driver
Verify functionality | Not done yet | -Basic Timer support | Add a Generic Timer driver
Verify functionality | Not done yet | -UART interrupt support | Add support for UART interrupts | Not done yet | -Task context switch support | Add context switching support
Verify functionality | Not done yet | -Login shell | Iteratively add and verify multi-user login shell support | Not done yet | -Publish development branch on github | Work with the community to post work done after employer approval | Not done yet | -Break out the Bubbly | Drink copious quantities of alcohol to celebrate | Not done yet | -Silicon bring-up | Plan silicon bring-up | Not done yet | +| Item | Description | Status | Notes | +|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|-------------------------------------------------------------------------------| +| Redox AArch64 toolchain | Create an usable redox AArch64 toolchain specification | Done | Using this JSON spec in isolated tests produces valid AArch64 soft float code | +| Stubbed kernel image | Stub out AArch64 kernel support using the existing x86_64 arch code as a template
Modify redox kernel build glue and work iteratively to get a linkable (non-functional) image | Not done yet | | +| Boot flow | Create a self hosted u-boot -> redox kernel workflow
Should obtain the stubbed image from a local TFTP server, load it into RAM and jump to it | Not done yet | | +| GDB Debug flow | Create a debug workflow centered around qemu's GDB stub
This should allow connecting to qemu's GDB stub and debug u-boot/redox stub via a GDB client and single stepping through code | Not done yet | | +| Verify Redox entry | Verify that control reaches the redox kernel from u-boot | Not done yet | | +| AArch64 early init stub | Add support for raw asm code for early AArch64 init in the redox kernel
Verify that this code is located appropriately in the link map and that control reaches this code from u-boot | Not done yet | | +| Basic DTB support | Integrate the [device_tree crate](https://mbr.github.io/device_tree-rs/device_tree/)
Use the crate to access the qemu supplied DTB image and extract the memory map | Not done yet | | +| Basic UART support | Use the device_tree crate to get the UART address from the DTB image and set up the initial console
This is a polling mode only setup | Not done yet | | +| Initial MMU support | Implement initial MMU support in the early init stub
This forces the MMU into a clean state overriding any bootloader specific setup
Create an identity map for MMU init
Create a mapping for the kernel image
Create a mapping for any devices needed at this stage (UART) | Not done yet | | +| kmain entry | Verify that kmain entry works post early MMU init | Not done yet | | +| Basic Redox MMU support | Get Redox to create a final set of mappings for everything
Verify that this works as expected | Not done yet | | +| Basic libc support | Flesh out a basic set of libc calls as required for simple user-land apps | Not done yet | | +| userspace_init entry | Verify user-space entry and /sbin/init invocation | Not done yet | | +| Basic Interrupt controller support | Add a GIC driver
Verify functionality | Not done yet | | +| Basic Timer support | Add a Generic Timer driver
Verify functionality | Not done yet | | +| UART interrupt support | Add support for UART interrupts | Not done yet | | +| Task context switch support | Add context switching support
Verify functionality | Not done yet | | +| Login shell | Iteratively add and verify multi-user login shell support | Not done yet | | +| Publish development branch on github | Work with the community to post work done after employer approval | Not done yet | | +| Break out the Bubbly | Drink copious quantities of alcohol to celebrate | Not done yet | | +| Silicon bring-up | Plan silicon bring-up | Not done yet | | diff --git a/src/arch/x86_64/interrupt/syscall.rs b/src/arch/x86_64/interrupt/syscall.rs index 483914b8dc..ca6d1f7a45 100644 --- a/src/arch/x86_64/interrupt/syscall.rs +++ b/src/arch/x86_64/interrupt/syscall.rs @@ -17,7 +17,7 @@ pub unsafe fn init() { // IA32_STAR[31:0] are reserved. // The base selector of the two consecutive segments for kernel code and the immediately - // suceeding stack (data). + // succeeding stack (data). let syscall_cs_ss_base = (gdt::GDT_KERNEL_CODE as u16) << 3; // The base selector of the three consecutive segments (of which two are used) for user code // and user data. It points to a 32-bit code segment, which must be followed by a data segment diff --git a/src/arch/x86_shared/device/mod.rs b/src/arch/x86_shared/device/mod.rs index a99f513a88..92f538da14 100644 --- a/src/arch/x86_shared/device/mod.rs +++ b/src/arch/x86_shared/device/mod.rs @@ -20,7 +20,7 @@ pub unsafe fn init() { pic::init(); local_apic::init(&mut KernelMapper::lock()); - // Run here for the side-effect of printing if KVM was used to avoid interleaved logs. + // Run here for the side effect of printing if KVM was used to avoid interleaved logs. tsc::get_kvm_support(); } } diff --git a/src/arch/x86_shared/interrupt/mod.rs b/src/arch/x86_shared/interrupt/mod.rs index 5502cc01f6..172bad3ba9 100644 --- a/src/arch/x86_shared/interrupt/mod.rs +++ b/src/arch/x86_shared/interrupt/mod.rs @@ -27,7 +27,7 @@ pub unsafe fn enable_and_halt() { /// Set interrupts and nop /// This will enable interrupts and allow the IF flag to be processed -/// Simply enabling interrupts does not gurantee that they will trigger, use this instead! +/// Simply enabling interrupts does not guarantee that they will trigger, use this instead! #[inline(always)] pub unsafe fn enable_and_nop() { unsafe { diff --git a/src/context/memory.rs b/src/context/memory.rs index f8ff1bfeea..45eb69fc4e 100644 --- a/src/context/memory.rs +++ b/src/context/memory.rs @@ -721,9 +721,9 @@ impl AddrSpace { #[derive(Debug)] pub struct UserGrants { - // Using a BTreeMap for it's range method. + // Using a BTreeMap for its range method. inner: BTreeMap, - // Using a BTreeMap for it's range method. + // Using a BTreeMap for its range method. holes: BTreeMap, // TODO: Would an additional map ordered by (size,start) to allow for O(log n) allocations be // beneficial? diff --git a/src/cpu_stats.rs b/src/cpu_stats.rs index 33c2b840e4..7a4dc4738d 100644 --- a/src/cpu_stats.rs +++ b/src/cpu_stats.rs @@ -18,7 +18,7 @@ pub enum CpuState { /// Waiting for runnable context #[default] Idle = 0, - /// Runnnig a kernel context + /// Running a kernel context Kernel = 1, /// Running a context in the userspace User = 2, diff --git a/src/event.rs b/src/event.rs index 0baed63fc2..e202a1e06f 100644 --- a/src/event.rs +++ b/src/event.rs @@ -222,7 +222,7 @@ fn trigger_inner( } pub fn trigger(scheme: SchemeId, number: usize, flags: EventFlags) { - //TODO: propogate this lock token + //TODO: propagate this lock token let mut token = unsafe { CleanLockToken::new() }; // First trigger with the original file diff --git a/src/main.rs b/src/main.rs index 6c3fa2b01d..78fdfa2ac5 100644 --- a/src/main.rs +++ b/src/main.rs @@ -19,27 +19,27 @@ #![allow(clippy::too_many_arguments)] // Used to allow stuff like 1 << 0 and 1 * 1024 * 1024 #![allow(clippy::identity_op)] -// TODO: address ocurrances and then deny +// TODO: address occurrences and then deny #![warn(clippy::not_unsafe_ptr_arg_deref)] -// TODO: address ocurrances and then deny +// TODO: address occurrences and then deny #![warn(clippy::cast_ptr_alignment)] // Indexing a slice can cause panics and that is something we always want to avoid // in kernel code. Use .get and return an error instead -// TODO: address ocurrances and then deny +// TODO: address occurrences and then deny #![warn(clippy::indexing_slicing)] // Overflows are very, very bad in kernel code as it may provide an attack vector for // userspace applications, and it is only checked in debug builds -// TODO: address ocurrances and then deny +// TODO: address occurrences and then deny #![warn(clippy::arithmetic_side_effects)] // Avoid panicking in the kernel without information about the panic. Use expect -// TODO: address ocurrances and then deny +// TODO: address occurrences and then deny #![warn(clippy::unwrap_used)] // This is usually a serious issue - a missing import of a define where it is interpreted // as a catch-all variable in a match, for example #![deny(unreachable_patterns)] // Ensure that all must_use results are used #![deny(unused_must_use)] -#![warn(static_mut_refs)] // FIXME deny once all occurences are fixed +#![warn(static_mut_refs)] // FIXME deny once all occurrences are fixed #![feature(if_let_guard)] #![feature(int_roundings)] #![feature(iter_next_chunk)] diff --git a/src/scheme/user.rs b/src/scheme/user.rs index b63ac29f8c..a9e8a8521f 100644 --- a/src/scheme/user.rs +++ b/src/scheme/user.rs @@ -486,11 +486,11 @@ impl UserInner { map_flags.set(MapFlags::PROT_WRITE, WRITE); if user_buf.is_empty() { - // NOTE: Rather than returning NULL, we return a dummy dangling address, that is + // NOTE: Rather than returning NULL, we return a dummy dangling address, which // happens to be non-canonical on x86. This relieves scheme handlers from having to // check the length before e.g. creating nonnull Rust references (when an empty length // still requires a nonnull but possibly dangling pointer, and this has in practice - // made nulld errorneously confuse an empty Some("") with None (invalid UTF-8), due to + // made nulld erroneously confuse an empty Some("") with None (invalid UTF-8), due to // enum layout optimization, as the pointer was null and not dangling). A good choice // is thus to simply set the most-significant bit to be compatible with all alignments. return Ok(CaptureGuard { diff --git a/src/sync/ordered.rs b/src/sync/ordered.rs index 1d4c113a5e..4dc50fb36b 100644 --- a/src/sync/ordered.rs +++ b/src/sync/ordered.rs @@ -3,13 +3,13 @@ #![allow(dead_code)] -//! This create implement compiletime ordering of locks into levels, [`L1`], [`L2`], [`L3`], [`L4`] and [`L5`]. +//! This crate implements compiletime ordering of locks into levels, [`L1`], [`L2`], [`L3`], [`L4`] and [`L5`]. //! In order to acquire a lock at level `i` only locks at level `i-1` or below may be held. //! -//! If locks are alwayes acquired in level order on all threads, then one cannot have a deadlock -//! involving only acquireng locks. +//! If locks are always acquired in level order on all threads, then one cannot have a deadlock +//! involving only acquired locks. //! -//! In the following example we create two [muteces](Mutex) at level [`L1`] and [`L2`] and lock them +//! In the following example we create two [mutexes](Mutex) at level [`L1`] and [`L2`] and lock them //! in the propper order. //! ``` //! use ordered_locks::{L1, L2, Mutex, CleanLockToken}; @@ -21,7 +21,7 @@ //! let mut token = unsafe {CleanLockToken::new()}; //! //! { -//! // We can aquire the locks for v1 and v2 at the same time +//! // We can acquire the locks for v1 and v2 at the same time //! let mut g1 = v1.lock(token.token()); //! let (g1, token) = g1.token_split(); //! let mut g2 = v2.lock(token); @@ -32,7 +32,7 @@ //! *v2.lock(token.token()) = 13; //! ``` //! -//! In the following example we create two [muteces](Mutex) at level [`L1`] and [`L2`] and try to lock +//! In the following example we create two [mutexes](Mutex) at level [`L1`] and [`L2`] and try to lock //! the mutex at [`L1`] while already holding a [`Mutex`] at [`L2`] which failes to compile. //! ```compile_fail //! use ordered_locks::{L1, L2, Mutex, CleanLockToken}; @@ -57,7 +57,7 @@ use core::marker::PhantomData; /// Lock level of a mutex /// /// While a mutex of L1 is locked on a thread, only mutexes of L2 or higher may be locked. -/// This lock hierarchy prevents deadlocks from occurring. For a dead lock to occour +/// This lock hierarchy prevents deadlocks from occurring. For a deadlock to occur /// We need some thread TA to hold a resource RA, and request a resource RB, while /// another thread TB holds RB, and requests RA. This is not possible with a lock /// hierarchy either RA or RB must be on a level that the other. @@ -121,7 +121,7 @@ pub trait Higher: Level {} impl Higher for L1 where L2: Lower {} /// While this exists only locks with a level higher than L, may be locked. -/// These tokens are carried around the call stack to indicate tho current locking level. +/// These tokens are carried around the call stack to indicate the current locking level. /// They have no size and should disappear at runtime. pub struct LockToken<'a, L: Level>(PhantomData<&'a mut L>); @@ -293,7 +293,7 @@ impl Default for RwLock { /// The type parameter T represents the data that this lock protects. It is required that T satisfies /// Send to be shared across threads and Sync to allow concurrent access through readers. /// The RAII guards returned from the locking methods implement Deref (and DerefMut for the write methods) -/// to allow access to the contained of the lock. +/// to allow access to the container of the lock. impl RwLock { /// Creates a new instance of an RwLock which is unlocked. pub const fn new(val: T) -> Self {