ax-plat 0.14.0

//! Physical memory information.

use core::{
    fmt,
    ops::{Deref, DerefMut, Range},
};

pub use ax_memory_addr::{PAGE_SIZE_4K, PhysAddr, VirtAddr, VirtAddrRange, pa, va};

bitflags::bitflags! {
    /// Attributes requested for an MMIO mapping.
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub struct IomapAttrs: usize {
        /// Device MMIO mapping with device ordering/cache attributes.
        const DEVICE        = 1 << 0;
        /// Write-combining mapping, such as framebuffers.
        const WRITE_COMBINE = 1 << 1;
        /// Cacheable mapping.
        const CACHEABLE     = 1 << 2;
        /// Non-posted device access.
        const NON_POSTED    = 1 << 3;
    }
}

/// Platform decision for an MMIO mapping request.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IomapDecision {
    /// The platform already provided a valid virtual address.
    Mapped(VirtAddr),
    /// Use the generic page-table-backed mapper with this physical address.
    UseGeneric(PhysAddr),
}

/// Platform error for an MMIO mapping request.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum IomapError {
    /// The requested address range or attributes are invalid.
    #[error("invalid I/O mapping request")]
    InvalidInput,
    /// The requested mapping attributes are not supported.
    #[error("I/O mapping attributes are not supported")]
    Unsupported,
}

/// Platform virtual-address geometry cannot be represented by this build.
#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum VirtualAddressSpaceError {
    /// A platform supplied an invalid half-open address range.
    #[error("invalid virtual-address-space range")]
    InvalidRange,
    /// The user-capable and kernel page-table ranges overlap.
    #[error("user and kernel virtual-address-space ranges overlap")]
    OverlappingRanges,
    /// The hardware address width exceeds the configured page-table contract.
    #[error("unsupported virtual-address width: VALEN={valen}")]
    UnsupportedAddressWidth {
        /// Architectural virtual-address length, including the sign bit.
        valen: usize,
    },
}

/// Immutable platform capability for page-table-backed virtual addresses.
///
/// `user` describes the lower range available to an OS user address space;
/// `kernel` describes the range available to the generic kernel virtual
/// allocator. Architecture direct-map windows are intentionally excluded.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct VirtualAddressSpaceLayout {
    user: VirtAddrRange,
    kernel: VirtAddrRange,
}

impl VirtualAddressSpaceLayout {
    /// Validates and constructs one platform layout.
    pub fn try_new(
        user: VirtAddrRange,
        kernel: VirtAddrRange,
    ) -> Result<Self, VirtualAddressSpaceError> {
        if user.overlaps(kernel) {
            return Err(VirtualAddressSpaceError::OverlappingRanges);
        }
        Ok(Self { user, kernel })
    }

    /// Returns the lower range available to user page tables.
    pub const fn user(self) -> VirtAddrRange {
        self.user
    }

    /// Returns the page-table-backed kernel allocation range.
    pub const fn kernel(self) -> VirtAddrRange {
        self.kernel
    }
}

/// Data-cache maintenance operation for a virtual address range.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DCacheOp {
    /// Clean dirty CPU cache lines to the point visible to devices.
    Clean,
    /// Invalidate CPU cache lines after device writes.
    Invalidate,
    /// Clean and invalidate CPU cache lines for bidirectional ownership changes.
    CleanInvalidate,
}

/// Platform contract for cacheable Normal memory shared by CPUs.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CpuSharedMemoryModel {
    /// All online CPUs observe a coherent view of cacheable Normal memory.
    ///
    /// Standard Acquire/Release atomics and the platform IPI ordering contract
    /// are sufficient for publishing CPU-owned queues. Per-message cache
    /// maintenance is neither required nor permitted as a substitute for
    /// synchronization.
    Coherent,
    /// The platform cannot provide the coherent memory model required by the
    /// generic SMP runtime.
    Unsupported,
}

bitflags::bitflags! {
    /// The flags of a physical memory region.
    #[derive(Clone, Copy)]
    pub struct MemRegionFlags: usize {
        /// Readable.
        const READ          = 1 << 0;
        /// Writable.
        const WRITE         = 1 << 1;
        /// Executable.
        const EXECUTE       = 1 << 2;
        /// Device memory. (e.g., MMIO regions)
        const DEVICE        = 1 << 4;
        /// Uncachable memory. (e.g., framebuffer)
        const UNCACHED      = 1 << 5;
        /// Reserved memory, do not use for allocation.
        const RESERVED      = 1 << 6;
        /// Free memory for allocation.
        const FREE          = 1 << 7;
    }
}

impl fmt::Debug for MemRegionFlags {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        fmt::Debug::fmt(&self.0, f)
    }
}

/// The default flags for a normal memory region (readable, writable and allocatable).
pub const DEFAULT_RAM_FLAGS: MemRegionFlags = MemRegionFlags::READ
    .union(MemRegionFlags::WRITE)
    .union(MemRegionFlags::FREE);

/// The default flags for a reserved memory region (readable, writable, and reserved).
pub const DEFAULT_RESERVED_FLAGS: MemRegionFlags = MemRegionFlags::READ
    .union(MemRegionFlags::WRITE)
    .union(MemRegionFlags::RESERVED);

/// The default flags for a MMIO region (readable, writable, device, and reserved).
pub const DEFAULT_MMIO_FLAGS: MemRegionFlags = MemRegionFlags::READ
    .union(MemRegionFlags::WRITE)
    .union(MemRegionFlags::DEVICE)
    .union(MemRegionFlags::RESERVED);

/// The raw memory range with start and size.
pub type RawRange = (usize, usize);

/// A wrapper type for aligning a value to 4K bytes.
#[repr(align(4096))]
pub struct Aligned4K<T: Sized>(T);

impl<T: Sized> Aligned4K<T> {
    /// Creates a new [`Aligned4K`] instance with the given value.
    pub const fn new(value: T) -> Self {
        Self(value)
    }
}

impl<T> Deref for Aligned4K<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl<T> DerefMut for Aligned4K<T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.0
    }
}

/// A physical memory region.
#[derive(Debug, Clone, Copy)]
pub struct PhysMemRegion {
    /// The start physical address of the region.
    pub paddr: PhysAddr,
    /// The size in bytes of the region.
    pub size: usize,
    /// The region flags, see [`MemRegionFlags`].
    pub flags: MemRegionFlags,
    /// The region name, used for identification.
    pub name: &'static str,
}

impl PhysMemRegion {
    /// Creates a RAM region with default flags (readable, writable, and allocatable).
    pub const fn new_ram(start: usize, size: usize, name: &'static str) -> Self {
        Self {
            paddr: PhysAddr::from_usize(start),
            size,
            flags: DEFAULT_RAM_FLAGS,
            name,
        }
    }

    /// Creates a MMIO region with default flags (readable, writable, and device).
    pub const fn new_mmio(start: usize, size: usize, name: &'static str) -> Self {
        Self {
            paddr: PhysAddr::from_usize(start),
            size,
            flags: DEFAULT_MMIO_FLAGS,
            name,
        }
    }

    /// Creates a reserved memory region with default flags (readable, writable, and reserved).
    pub const fn new_reserved(start: usize, size: usize, name: &'static str) -> Self {
        Self {
            paddr: PhysAddr::from_usize(start),
            size,
            flags: DEFAULT_RESERVED_FLAGS,
            name,
        }
    }
}

/// Physical memory interface.
#[def_plat_interface]
pub trait MemIf {
    /// Returns the memory model provided for cacheable RAM shared by CPUs.
    ///
    /// Platforms must establish this contract before secondary CPUs enter the
    /// generic runtime. [`CpuSharedMemoryModel::Unsupported`] restricts the
    /// runtime to a single CPU; it does not request queue-local cache flushing.
    fn cpu_shared_memory_model() -> CpuSharedMemoryModel;

    /// Returns all physical memory (RAM) ranges on the platform.
    ///
    /// All memory ranges except reserved ranges (including the kernel loaded
    /// range) are free for allocation.
    fn phys_ram_ranges() -> &'static [RawRange];

    /// Returns all reserved physical memory ranges on the platform.
    ///
    /// Reserved memory can be contained in [`phys_ram_ranges`], they are not
    /// allocatable but should be mapped to kernel's address space.
    ///
    /// Note that the ranges returned should not include the range where the
    /// kernel is loaded.
    fn reserved_phys_ram_ranges() -> &'static [RawRange];

    /// Returns all device memory (MMIO) ranges on the platform.
    fn mmio_ranges() -> &'static [RawRange];

    /// Prepares an MMIO mapping request.
    ///
    /// This hook is for architecture/platform-specific IO address handling, such
    /// as choosing an uncached hardware alias. Returning [`IomapDecision::UseGeneric`]
    /// asks the generic memory manager to create a page-table-backed mapping.
    fn prepare_iomap(
        addr: PhysAddr,
        size: usize,
        attrs: IomapAttrs,
    ) -> Result<IomapDecision, IomapError>;

    /// Translates a physical address to a virtual address.
    ///
    /// It is just an easy way to access physical memory when virtual memory
    /// is enabled. The mapping may not be unique, there can be multiple `vaddr`s
    /// mapped to that `paddr`.
    fn phys_to_virt(paddr: PhysAddr) -> VirtAddr;

    /// Translates a virtual address to a physical address.
    ///
    /// It is a reverse operation of [`phys_to_virt`]. It requires that the
    /// `vaddr` must be available through the [`phys_to_virt`] translation.
    /// It **cannot** be used to translate arbitrary virtual addresses.
    fn virt_to_phys(vaddr: VirtAddr) -> PhysAddr;

    /// Returns the immutable page-table-backed virtual-address layout.
    fn virtual_address_space() -> Result<VirtualAddressSpaceLayout, VirtualAddressSpaceError>;

    /// Returns whether a newly-created user address space must copy kernel mappings.
    fn user_aspace_needs_kernel_mappings() -> bool;

    /// Maintains a CPU data-cache range for non-coherent DMA ownership changes.
    fn dcache_range(op: DCacheOp, addr: VirtAddr, size: usize);

    /// Prepares cached pages before the kernel creates an uncached DMA alias.
    fn dma_coherent_before_map_uncached(addr: VirtAddr, size: usize);

    /// Orders accesses before the kernel removes an uncached DMA alias.
    fn dma_coherent_before_unmap_uncached(addr: VirtAddr, size: usize);

    /// Completes platform ordering after a DMA coherent alias update.
    fn dma_coherent_after_mapping_update();
}

/// Returns the total size of physical memory (RAM) on the platform.
///
/// It should be equal to the sum of sizes of all physical memory ranges (returned
/// by [`phys_ram_ranges`]).
pub fn total_ram_size() -> usize {
    phys_ram_ranges().iter().map(|range| range.1).sum()
}

/// The error type for overlapping check.
///
/// It contains the overlapping range pair.
pub type OverlapErr = (Range<usize>, Range<usize>);

/// Checks if the given ranges are overlapping.
///
/// Returns `Err` with one of the overlapping range pair if they are overlapping.
///
/// The given ranges should be sorted by the start, otherwise it always returns
/// `Err`.
///
/// # Example
///
/// ```rust
/// # use ax_plat::mem::check_sorted_ranges_overlap;
/// assert!(check_sorted_ranges_overlap([(0, 10), (10, 10)].into_iter()).is_ok());
/// assert_eq!(
///     check_sorted_ranges_overlap([(0, 10), (5, 10)].into_iter()),
///     Err((0..10, 5..15))
/// );
/// ```
pub fn check_sorted_ranges_overlap(
    ranges: impl Iterator<Item = RawRange>,
) -> Result<(), OverlapErr> {
    let mut prev = Range::default();
    for (start, size) in ranges {
        if prev.end > start {
            return Err((prev, start..start + size));
        }
        prev = start..start + size;
    }
    Ok(())
}

/// Removes a portion of ranges from the given ranges.
///
/// `from` is a list of ranges to be operated on, and `exclude` is a list of
/// ranges to be removed. `exclude` should have been sorted by the start, and
/// have non-overlapping ranges. If not, an error will be returned.
///
/// The result is also a list of ranges with each range contained in `from` but
/// not in `exclude`. `result_op` is a closure that will be called for each range
/// in the result.
///
/// # Example
///
/// ```rust
/// # use ax_plat::mem::ranges_difference;
/// let mut res = Vec::new();
/// // 0..10, 20..30 - 5..15, 15..25 = 0..5, 25..30
/// ranges_difference(&[(0, 10), (20, 10)], &[(5, 10), (15, 10)], |r| res.push(r)).unwrap();
/// assert_eq!(res, &[(0, 5), (25, 5)]);
/// ```
pub fn ranges_difference<F>(
    from: &[RawRange],
    exclude: &[RawRange],
    mut result_op: F,
) -> Result<(), OverlapErr>
where
    F: FnMut(RawRange),
{
    check_sorted_ranges_overlap(exclude.iter().cloned())?;

    for &(start, size) in from {
        let mut start = start;
        let end = start + size;

        for &(exclude_start, exclude_size) in exclude {
            let exclude_end = exclude_start + exclude_size;
            if exclude_end <= start {
                continue;
            } else if exclude_start >= end {
                break;
            } else if exclude_start > start {
                result_op((start, exclude_start - start));
            }
            start = exclude_end;
        }
        if start < end {
            result_op((start, end - start));
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    #[test]
    fn check_sorted_ranges_overlap() {
        use super::check_sorted_ranges_overlap as f;

        assert!(f([(0, 10), (10, 10), (20, 10)].into_iter()).is_ok());
        assert!(f([(0, 10), (20, 10), (40, 10)].into_iter()).is_ok());
        assert_eq!(f([(0, 1), (0, 2)].into_iter()), Err((0..1, 0..2)));
        assert_eq!(
            f([(0, 11), (10, 10), (20, 10)].into_iter()),
            Err((0..11, 10..20)),
        );
        assert_eq!(
            f([(0, 10), (20, 10), (10, 10)].into_iter()),
            Err((20..30, 10..20)), // not sorted
        );
    }

    #[test]
    fn ranges_difference() {
        let f = |from, exclude| {
            let mut res = Vec::new();
            super::ranges_difference(from, exclude, |r| res.push(r)).unwrap();
            res
        };

        // 0..10, 20..30
        assert_eq!(
            f(&[(0, 10), (20, 10)], &[(5, 5), (25, 5)]), // - 5..10, 25..30
            &[(0, 5), (20, 5)]                           // = 0..5, 20..25
        );
        assert_eq!(
            f(&[(0, 10), (20, 10)], &[(5, 10), (15, 5)]), // - 5..15, 15..20
            &[(0, 5), (20, 10)]                           // = 0..5, 20..30
        );
        assert_eq!(
            f(&[(0, 10), (20, 10)], &[(5, 1), (25, 1), (30, 1)]), // - 5..6, 25..26, 30..31
            &[(0, 5), (6, 4), (20, 5), (26, 4)]                   // = 0..5, 6..10, 20..25, 26..30
        );

        // 0..10, 20..30
        assert_eq!(f(&[(0, 10), (20, 10)], &[(5, 20)]), &[(0, 5), (25, 5)]); // - 5..25 = 0..5, 25..30
        assert_eq!(f(&[(0, 10), (20, 10)], &[(0, 30)]), &[]); // - 0..30 = []

        // 0..30
        assert_eq!(
            f(&[(0, 30)], &[(0, 5), (10, 5), (20, 5)]), // - 0..5, 10..15, 20..25
            &[(5, 5), (15, 5), (25, 5)]                 // = 5..10, 15..20, 25..30
        );
        assert_eq!(
            f(
                &[(0, 30)],
                &[(0, 5), (5, 5), (10, 5), (15, 5), (20, 5), (25, 5)] /* - 0..5, 5..10, 10..15, 15..20, 20..25, 25..30 */
            ),
            &[] // = []
        );

        // 10..20
        assert_eq!(f(&[(10, 10)], &[(0, 30)]), &[]); // - 0..30 = []
    }
}