kernel: Added brief comments for new memory management related code

Signed-off-by: Ioan-Cristian CÎRSTEA <ioan.cirstea@oxidos.io>

Author: IoanCristianCirstea

kernel/src/memory_management/allocators/allocator.rs

@@ -2,10 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Memory allocators.
+
 use super::super::slices::MutablePhysicalSlice;
 
 use core::num::NonZero;
 
+/// Memory allocator trait.
 pub trait Allocator<'a, Granule> {
+    /// Allocate `count` granules of memory.
     fn allocate(&self, count: NonZero<usize>) -> Result<MutablePhysicalSlice<'a, Granule>, ()>;
 }

kernel/src/memory_management/allocators/static.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Static allocator.
+
 use super::allocator::Allocator;
 
 use super::super::slices::MutablePhysicalSlice;
@@ -10,6 +12,7 @@ use crate::utilities::cells::OptionalCell;
 
 use core::num::NonZero;
 
+/// A static allocator, i.e. an allocator that allocates memory without freeing it ever.
 pub struct StaticAllocator<'a, Granule>(OptionalCell<MutablePhysicalSlice<'a, Granule>>);
 
 impl<'a, Granule> StaticAllocator<'a, Granule> {

kernel/src/memory_management/configuration.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Memory configurations.
+
 use super::pointers::{
     KernelVirtualPointer, PhysicalPointer, UserVirtualPointer, ValidVirtualPointer,
 };
@@ -15,6 +17,7 @@ use crate::platform::mmu::Asid;
 
 use crate::utilities::alignment::AlwaysAligned;
 
+/// Memory configuration.
 #[repr(transparent)]
 pub(super) struct Configuration<'a, const IS_USER: bool, const NUMBER_REGIONS: usize, Granule> {
     regions: [DirtyMappedProtectedAllocatedRegion<'a, IS_USER, Granule>; NUMBER_REGIONS],
@@ -89,6 +92,7 @@ impl<'a, const IS_USER: bool, const NUMBER_REGIONS: usize, Granule>
     }
 }
 
+/// Process memory configuration.
 pub(crate) struct ProcessConfiguration<'a, Granule> {
     asid: Asid,
     configuration: Configuration<'a, true, 2, Granule>,
@@ -184,6 +188,8 @@ impl<'a, Granule> ProcessConfiguration<'a, Granule> {
     }
 }
 
+/// Valid process memory configuration, that is, it doesn't overlap kernel's
+/// virtual address space.
 #[repr(transparent)]
 pub struct ValidProcessConfiguration<'a, Granule>(ProcessConfiguration<'a, Granule>);
 
@@ -265,6 +271,7 @@ const KERNEL_PROG_REGION_INDEX: usize = 1;
 const KERNEL_RAM_REGION_INDEX: usize = 2;
 //const KERNEL_PERIPHERAL_REGION_INDEX: usize = 3;
 
+/// Kernel memory configuration.
 #[repr(transparent)]
 pub(crate) struct KernelConfiguration<'a, Granule>(Configuration<'a, false, 4, Granule>);
 

kernel/src/memory_management/granules.rs

@@ -2,12 +2,16 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Memory granules.
+
 use crate::utilities::alignment::Alignment;
 use crate::utilities::misc::{create_non_zero_usize, divide_non_zero_usize, modulo_non_zero_usize};
 
 use core::num::NonZero;
 
+/// A memory granule.
 pub trait Granule: Alignment {
+    /// The size of the granule, in bytes.
     const SIZE_U8: NonZero<usize>;
 
     fn ceil_from_byte_count(byte_count: NonZero<usize>) -> NonZero<usize> {

kernel/src/memory_management/memory_managers.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Memory managers.
+
 use super::allocators::Allocator as AllocatorTrait;
 use super::configuration::{KernelConfiguration, ProcessConfiguration, ValidProcessConfiguration};
 use super::granules::Granule as GranuleTrait;
@@ -17,6 +19,9 @@ use crate::utilities::alignment::AlwaysAligned;
 use core::marker::PhantomData;
 use core::num::NonZero;
 
+/// A memory manager.
+///
+/// A memory manager currently handles only memory allocation.
 struct MemoryManager<'a, Granule, Allocator: AllocatorTrait<'a, Granule>> {
     allocator: Allocator,
     phantom_data: PhantomData<&'a Granule>,
@@ -40,6 +45,7 @@ impl<'a, Granule, Allocator: AllocatorTrait<'a, Granule>> MemoryManager<'a, Gran
     }
 }
 
+/// Errors on process memory mapping.
 #[derive(Debug)]
 pub enum ProcessMemoryMappingError {
     /// The PROG memory is not a valid user virtual memory.
@@ -48,6 +54,9 @@ pub enum ProcessMemoryMappingError {
     InvalidRamVirtualMemory,
 }
 
+/// Process memory manager.
+///
+/// Handles process memory allocations and process memory configurations.
 pub struct ProcessMemoryManager<'a, Granule, Allocator: AllocatorTrait<'a, Granule>> {
     memory_manager: MemoryManager<'a, Granule, Allocator>,
 }
@@ -79,6 +88,10 @@ impl<'a, Granule: 'a + GranuleTrait, Allocator: AllocatorTrait<'a, Granule>>
     }
 }
 
+/// Kernel memory manager.
+///
+/// Validates process memory configurations and performs offline user -> kernel
+/// address translation.
 pub(crate) struct KernelMemoryManager<'a, Granule, const USING_MPU: bool> {
     configuration: KernelConfiguration<'a, Granule>,
 }

kernel/src/memory_management/pages.rs

@@ -2,12 +2,15 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Pages supported by Tock.
+
 use super::granules::Granule;
 
 use crate::utilities::misc::create_non_zero_usize;
 
 use core::num::NonZero;
 
+/// A standard 4KiB page.
 #[repr(align(4096))]
 #[derive(Clone)]
 #[allow(dead_code)]

kernel/src/memory_management/permissions.rs

@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Memory permissions.
+
+/// Permissions that might be associated with a region of memory.
 #[derive(Clone, Copy, PartialEq, Eq)]
 pub enum Permissions {
     ReadOnly,

kernel/src/memory_management/pointers.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 // Copyright OxidOS Automotive SRL 2025.
 
+//! Physical and virtual pointers.
+
 use crate::utilities::alignment::{Alignment, AlwaysAligned};
 use crate::utilities::ordering::SmallerPair;
 use crate::utilities::pointers::{
@@ -14,70 +16,105 @@ use core::num::NonZero;
 use core::ops::Sub;
 use core::ptr::NonNull;
 
+/// A pointer from the perspective of the memory management system.
 #[repr(transparent)]
 pub struct Pointer<const IS_VIRTUAL: bool, const IS_MUTABLE: bool, T: Alignment>(
     Ptr<IS_MUTABLE, T>,
 );
 
+/// An immutable pointer from the perspective of the memory management system.
 pub type ImmutablePointer<const IS_VIRTUAL: bool, T> = Pointer<IS_VIRTUAL, false, T>;
+/// A mutable pointer from the perspective of the memory management system.
 pub type MutablePointer<const IS_VIRTUAL: bool, T> = Pointer<IS_VIRTUAL, true, T>;
 
+/// A physical pointer.
 pub type PhysicalPointer<const IS_MUTABLE: bool, T> = Pointer<false, IS_MUTABLE, T>;
+/// An immutable physical pointer.
 pub type ImmutablePhysicalPointer<T> = PhysicalPointer<false, T>;
+/// A mutable physical pointer.
 pub type MutablePhysicalPointer<T> = PhysicalPointer<true, T>;
 
+/// A virtual pointer.
 pub type VirtualPointer<const IS_MUTABLE: bool, T> = Pointer<true, IS_MUTABLE, T>;
+/// An immutable virtual pointer.
 pub type ImmutableVirtualPointer<T> = VirtualPointer<false, T>;
+/// A mutable virtual pointer.
 pub type MutableVirtualPointer<T> = VirtualPointer<true, T>;
 
+/// A valid virtual pointer, that is, a virtual pointer that belongs to the kernel or to a process.
 #[repr(transparent)]
 pub struct ValidVirtualPointer<const IS_USER: bool, const IS_MUTABLE: bool, T: Alignment>(
     Pointer<true, IS_MUTABLE, T>,
 );
 
+/// A valid immutable virtual pointer.
 pub type ValidImmutableVirtualPointer<const IS_USER: bool, T> =
     ValidVirtualPointer<IS_USER, false, T>;
+/// A valid mutable virtual pointer.
 pub type ValidMutableVirtualPointer<const IS_USER: bool, T> = ValidVirtualPointer<IS_USER, true, T>;
 
+/// A user virtual pointer.
 pub type UserVirtualPointer<const IS_MUTABLE: bool, T> = ValidVirtualPointer<true, IS_MUTABLE, T>;
+/// An immutable user virtual pointer.
 pub type ImmutableUserVirtualPointer<T> = UserVirtualPointer<false, T>;
+/// A mutable user virtual pointer.
 pub type MutableUserVirtualPointer<T> = UserVirtualPointer<true, T>;
 
+/// A kernel virtual pointer.
 pub type KernelVirtualPointer<const IS_MUTABLE: bool, T> =
     ValidVirtualPointer<false, IS_MUTABLE, T>;
+/// An immutable kernel virtual pointer.
 pub type ImmutableKernelVirtualPointer<T> = KernelVirtualPointer<false, T>;
+/// A mutable kernel virtual pointer.
 pub type MutableKernelVirtualPointer<T> = KernelVirtualPointer<true, T>;
 
+/// A nullable pointer from the perspective of the memory management system.
 pub enum NullablePointer<const IS_VIRTUAL: bool, const IS_MUTABLE: bool, T: Alignment> {
     Null,
     NonNull(Pointer<IS_VIRTUAL, IS_MUTABLE, T>),
 }
 
+/// An immutable nullable pointer from the perspective of the memory management system.
 pub type ImmutableNullablePointer<const IS_VIRTUAL: bool, T> =
     NullablePointer<IS_VIRTUAL, false, T>;
+/// A mutable nullable pointer from the memory management system pe
 pub type MutableNullablePointer<const IS_VIRTUAL: bool, T> = NullablePointer<IS_VIRTUAL, true, T>;
 
+/// A nullable physical pointer.
 pub type NullablePhysicalPointer<const IS_MUTABLE: bool, T> = NullablePointer<false, IS_MUTABLE, T>;
+/// An immutable nullable physical pointer.
 pub type ImmutableNullablePhysicalPointer<T> = NullablePhysicalPointer<false, T>;
+/// A mutable nullable physical pointer.
 pub type MutableNullablePhysicalPointer<T> = NullablePhysicalPointer<true, T>;
 
+/// A nullable virtual pointer.
 pub type NullableVirtualPointer<const IS_MUTABLE: bool, T> = NullablePointer<true, IS_MUTABLE, T>;
+/// An immutable nullable virtual pointer.
 pub type ImmutableNullableVirtualPointer<T> = NullableVirtualPointer<false, T>;
+/// A mutable nullable virtual pointer.
 pub type MutableNullableVirtualPointer<T> = NullableVirtualPointer<true, T>;
 
+/// A valid nullable virtual pointer, that is, a virtual pointer that belongs to the kernel or to a
+/// process.
 pub enum ValidNullableVirtualPointer<const IS_USER: bool, const IS_MUTABLE: bool, T: Alignment> {
     Null,
     NonNull(ValidVirtualPointer<IS_USER, IS_MUTABLE, T>),
 }
 
+/// A user nullable virtual pointer.
 pub type UserNullableVirtualPointer<const IS_MUTABLE: bool, T> =
     ValidNullableVirtualPointer<true, IS_MUTABLE, T>;
+/// An immutable user nullable virtual pointer.
 pub type ImmutableUserNullableVirtualPointer<T> = UserNullableVirtualPointer<false, T>;
+/// A mutable user nullable virtual pointer.
 pub type MutableUserNullableVirtualPointer<T> = UserNullableVirtualPointer<true, T>;
 
+/// A kernel nullable virtual pointer.
 pub type KernelNullableVirtualPointer<const IS_MUTABLE: bool, T> =
     ValidNullableVirtualPointer<false, IS_MUTABLE, T>;
+/// An immutable kernel virtual pointer.
 pub type ImmutableKernelNullableVirtualPointer<T> = KernelNullableVirtualPointer<false, T>;
+/// A mutable kernel virtual pointer.
 pub type MutableKernelNullableVirtualPointer<T> = KernelNullableVirtualPointer<true, T>;
 
 impl<const IS_VIRTUAL: bool, const IS_MUTABLE: bool, T: Alignment>