aarch32_cpu/

pmsav7.rs

//! Support for the PMSAv7 MPU
//!
//! See Chapter 14: Protected Memory System Architecture in [Arm
//! Architecture Reference Manual ARMv7-A and ARMv7-R edition][armv7]
//!
//! [armv7]: https://developer.arm.com/documentation/ddi0406/latest

use core::marker::PhantomData;

use crate::register;

use arbitrary_int::{u2, u3};

#[doc(inline)]
pub use register::drsr::RegionSize;

/// Ways this API can fail
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Error {
    /// Found too many regions
    TooManyRegions,
    /// Found a region with invalid alignment
    UnalignedRegion(*mut u8),
}

/// Represents our PMSAv7 MPU
///
/// This type is not [Send] because it is a per-core type and should not be moved across
/// cores on an SMP system.
pub struct Mpu {
    _phantom: PhantomData<*const u8>,
}

impl Mpu {
    /// Create an MPU handle
    ///
    /// # Safety
    ///
    /// Only create one of these at any given time, as they access shared
    /// mutable state within the processor and do read-modify-writes on that state.
    pub unsafe fn new() -> Mpu {
        Mpu {
            _phantom: PhantomData,
        }
    }

    /// How many MPU instruction regions are there?
    pub fn num_iregions(&self) -> u8 {
        register::Mpuir::read().iregions()
    }

    /// How many MPU data/unified regions are there?
    pub fn num_dregions(&self) -> u8 {
        register::Mpuir::read().dregions()
    }

    /// Do we have a unified MPU?
    pub fn is_unified(&self) -> bool {
        !register::Mpuir::read().non_unified()
    }

    /// Get an instruction region
    pub fn get_iregion(&mut self, idx: u8) -> Option<Region> {
        if idx >= self.num_iregions() {
            return None;
        }
        register::Rgnr::write(register::Rgnr(idx as u32));
        let base = register::Irbar::read().0 as *mut u8;
        let rsr = register::Irsr::read();
        let racr = register::Iracr::read();

        let mem_attr_bits = MemAttrBits {
            tex: racr.tex(),
            c: racr.c(),
            b: racr.b(),
            s: racr.s(),
        };

        let mem_attr = mem_attr_bits.decode()?;
        let access_perms = AccessPerms::from_bits(racr.ap())?;

        Some(Region {
            base,
            size: rsr.region_size(),
            subregion_mask: rsr.subregion_mask(),
            enabled: rsr.enabled(),
            no_exec: racr.nx(),
            mem_attr,
            access_perms,
        })
    }

    /// Get a data/unified region
    pub fn get_dregion(&mut self, idx: u8) -> Option<Region> {
        if idx >= self.num_dregions() {
            return None;
        }
        register::Rgnr::write(register::Rgnr(idx as u32));
        let base = register::Drbar::read().0 as *mut u8;
        let rsr = register::Drsr::read();
        let racr = register::Dracr::read();

        let mem_attr_bits = MemAttrBits {
            tex: racr.tex(),
            c: racr.c(),
            b: racr.b(),
            s: racr.s(),
        };
        let mem_attr = mem_attr_bits.decode()?;
        let access_perms = AccessPerms::from_bits(racr.ap())?;

        Some(Region {
            base,
            size: rsr.region_size(),
            subregion_mask: rsr.subregion_mask(),
            enabled: rsr.enabled(),
            no_exec: racr.nx(),
            mem_attr,
            access_perms,
        })
    }

    /// Configure the EL1 MPU
    pub fn configure(&mut self, config: &Config) -> Result<(), Error> {
        if config.iregions.len() > self.num_iregions() as usize {
            return Err(Error::TooManyRegions);
        }
        if config.dregions.len() > self.num_dregions() as usize {
            return Err(Error::TooManyRegions);
        }
        for (idx, region) in config.iregions.iter().enumerate() {
            register::Rgnr::write(register::Rgnr(idx as u32));
            if !region.size.is_aligned(region.base) {
                return Err(Error::UnalignedRegion(region.base));
            }
            register::Irbar::write(register::Irbar(region.base as u32));
            register::Irsr::write({
                let mut out = register::Irsr::new_with_raw_value(0);
                out.set_enabled(region.enabled);
                out.set_region_size(region.size);
                out.set_subregion_mask(region.subregion_mask);
                out
            });
            register::Iracr::write({
                let mut out = register::Iracr::new_with_raw_value(0);
                let mem_attr_bits = region.mem_attr.to_bits();
                out.set_tex(mem_attr_bits.tex);
                out.set_c(mem_attr_bits.c);
                out.set_b(mem_attr_bits.b);
                out.set_s(mem_attr_bits.s);
                out.set_nx(region.no_exec);
                out.set_ap(region.access_perms.to_bits());
                out
            });
        }
        for (idx, region) in config.dregions.iter().enumerate() {
            if !region.size.is_aligned(region.base) {
                return Err(Error::UnalignedRegion(region.base));
            }
            register::Rgnr::write(register::Rgnr(idx as u32));
            register::Drbar::write(register::Drbar(region.base as u32));
            register::Drsr::write({
                let mut out = register::Drsr::new_with_raw_value(0);
                out.set_enabled(region.enabled);
                out.set_region_size(region.size);
                out.set_subregion_mask(region.subregion_mask);
                out
            });
            register::Dracr::write({
                let mut out = register::Dracr::new_with_raw_value(0);
                let mem_attr_bits = region.mem_attr.to_bits();
                out.set_tex(mem_attr_bits.tex);
                out.set_c(mem_attr_bits.c);
                out.set_b(mem_attr_bits.b);
                out.set_s(mem_attr_bits.s);
                out.set_nx(region.no_exec);
                out.set_ap(region.access_perms.to_bits());
                out
            });
        }
        register::Sctlr::modify(|r| {
            r.set_br(config.background_config);
        });
        Ok(())
    }

    /// Enable the MPU
    pub fn enable(&mut self) {
        register::Sctlr::modify(|r| {
            r.set_m(true);
        });
    }

    /// Disable the MPU
    pub fn disable(&mut self) {
        register::Sctlr::modify(|r| {
            r.set_m(false);
        });
    }
}

/// Configuration for the PMSAv7 MPU
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct Config<'a> {
    /// Background Config Enable
    ///
    /// If true, use the default MMU config if no other region matches an address
    pub background_config: bool,
    /// List of instruction regions
    pub iregions: &'a [Region],
    /// List of data/unified regions
    pub dregions: &'a [Region],
}

/// Configuration for a region in the PMSAv7 MPU
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct Region {
    /// The base address of this region.
    ///
    /// Must be aligned to the size of the region.
    pub base: *mut u8,
    /// The size of this region
    pub size: RegionSize,
    /// Sub-region bitmask
    ///
    /// The region is divided into exactly eight equal sized subregions.
    /// Subregion 0 is the subregion at the least significant address.
    ///
    /// A 1 bit means that sub-region is disabled.
    ///
    /// Only applies to regions sized 256 bytes or larger.
    pub subregion_mask: u8,
    /// Is this region enabled?
    pub enabled: bool,
    /// No-Execute in this region
    pub no_exec: bool,
    /// Attributes for this region
    pub mem_attr: MemAttr,
    /// Access permissions for this region
    pub access_perms: AccessPerms,
}

// Creating a static Region is fine - the pointers within it
// only go to the MPU and aren't accessed via Rust code
unsafe impl Sync for Region {}

/// Describes the memory ordering and cacheability of a region
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum MemAttr {
    /// Strongly-ordered memory
    StronglyOrdered,
    /// Device (shareable or non-shareable)
    Device {
        /// Is device shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Normal Memory, Outer and Inner Cache are Write-Through, no Write-Allocate
    WriteThroughNoWriteAlloc {
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Normal Memory, Outer and Inner Cache are Write-Back, no Write-Allocate
    WriteBackNoWriteAlloc {
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Normal Memory, Non-cacheable in Outer and Inner Caches
    NonCacheable {
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Implementation Defined
    ImplementationDefined {
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Outer and Inner Write-Back, Write-Allocate
    WriteBackWriteAlloc {
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
    /// Normal Memory, where Inner and Outer cache have different settings
    Cacheable {
        /// Settings for the Outer Cache
        outer: CachePolicy,
        /// Settings for the Inner Cache
        inner: CachePolicy,
        /// Is memory shareable (across multiple CPUs)
        shareable: bool,
    },
}

impl MemAttr {
    /// Convert this memory attribute to an 8-bit value we can write to RACR
    pub const fn to_bits(&self) -> MemAttrBits {
        match self {
            MemAttr::StronglyOrdered => MemAttrBits {
                tex: u3::from_u8(0b000),
                c: false,
                b: false,
                s: true,
            },
            MemAttr::Device { shareable: true } => MemAttrBits {
                tex: u3::from_u8(0b000),
                c: false,
                b: true,
                s: true,
            },
            MemAttr::Device { shareable: false } => MemAttrBits {
                tex: u3::from_u8(0b010),
                c: false,
                b: false,
                s: false,
            },
            MemAttr::WriteThroughNoWriteAlloc { shareable } => MemAttrBits {
                tex: u3::from_u8(0b000),
                c: true,
                b: false,
                s: *shareable,
            },
            MemAttr::WriteBackNoWriteAlloc { shareable } => MemAttrBits {
                tex: u3::from_u8(0b000),
                c: true,
                b: true,
                s: *shareable,
            },
            MemAttr::NonCacheable { shareable } => MemAttrBits {
                tex: u3::from_u8(0b001),
                c: false,
                b: false,
                s: *shareable,
            },
            MemAttr::ImplementationDefined { shareable } => MemAttrBits {
                tex: u3::from_u8(0b001),
                c: true,
                b: false,
                s: *shareable,
            },
            MemAttr::WriteBackWriteAlloc { shareable } => MemAttrBits {
                tex: u3::from_u8(0b001),
                c: true,
                b: true,
                s: *shareable,
            },
            MemAttr::Cacheable {
                outer,
                inner,
                shareable,
            } => {
                let outer = *outer as u8;
                let inner = *inner as u8;
                MemAttrBits {
                    tex: u3::from_u8(0b100 | outer),
                    c: (inner & 0b10) != 0,
                    b: (inner & 0b01) != 0,
                    s: *shareable,
                }
            }
        }
    }
}

/// A representation of Memory Attributes suitable for sticking into the RACR register
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct MemAttrBits {
    /// TEX attribute, defining the outer cache attribute
    pub tex: u3,
    /// C bit, defining the inner cache attribute
    pub c: bool,
    /// B bit, defining the inner cache attribute
    pub b: bool,
    /// S bit, shareable bit for normal memory regions
    pub s: bool,
}

impl MemAttrBits {
    const fn decode(&self) -> Option<MemAttr> {
        match (self.tex.value(), self.c, self.b) {
            (0b000, false, false) => Some(MemAttr::StronglyOrdered),
            (0b000, false, true) => Some(MemAttr::Device { shareable: true }),
            (0b000, true, false) => Some(MemAttr::WriteThroughNoWriteAlloc { shareable: self.s }),
            (0b000, true, true) => Some(MemAttr::WriteBackNoWriteAlloc { shareable: self.s }),
            (0b001, false, false) => Some(MemAttr::NonCacheable { shareable: self.s }),
            (0b001, true, false) => Some(MemAttr::ImplementationDefined { shareable: self.s }),
            (0b001, true, true) => Some(MemAttr::WriteBackWriteAlloc { shareable: self.s }),
            (0b010, false, false) => Some(MemAttr::Device { shareable: false }),
            (tex, c, b) if tex >= 0b100 => {
                let outer = tex & 0b11;
                let inner = ((c as u8) << 1) | (b as u8);
                Some(MemAttr::Cacheable {
                    outer: CachePolicy::new_with_raw_value(u2::from_u8(outer)),
                    inner: CachePolicy::new_with_raw_value(u2::from_u8(inner)),
                    shareable: self.s,
                })
            }
            _ => {
                // failed to decode
                None
            }
        }
    }
}

/// Whether/how a region is cacheable
#[bitbybit::bitenum(u2, exhaustive = true)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Debug, PartialEq, Eq)]
pub enum CachePolicy {
    /// Non-cacheable
    NonCacheable = 0b00,
    /// Write-Back Cacheable, Write-Allocate
    WriteBackWriteAlloc = 0b01,
    /// Write-Through Cacheable
    WriteThroughNoWriteAlloc = 0b10,
    /// Write-Back Cacheable, no Write-Allocate
    WriteBackNoWriteAlloc = 0b11,
}

/// Describes the access permissions of a memory region
///
/// Access permission bits control read and write access to the corresponding memory region.
/// Permissions are specified for priviledged accesses (PL1) and for user accesses (PL0).
/// Accesses to a memory region without the required permissions generate a Permission fault.
///
/// Note that the execute-never (XN) attribute provides an additional permission check on memory
/// regions, see [Region::no_exec].
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum AccessPerms {
    /// All accesses generate a Permission fault
    /// - PL1: No access
    /// - PL0: No access
    NoAccess,
    /// All write accesses generate Permission faults
    /// - PL1: Read-only
    /// - PL0: Read-only
    ReadOnly,
    /// Full access
    /// - PL1: Read/Write
    /// - PL0: Read/Write
    ReadWrite,
    /// PL1 read-only, all other accesses generate Permission faults
    /// - PL1: Read-only
    /// - PL0: No access
    PrivReadOnly,
    /// All unprivileged accesses generate Permission faults
    /// - PL1: Read/Write
    /// - PL0: No access
    PrivReadWrite,
    /// User mode write accesses generate Permission faults
    /// - PL1: Read/Write
    /// - PL0: Read-only
    PrivReadWriteUserReadOnly,
}
impl AccessPerms {
    /// Convert these access permissions to a 3-bit value we can write to RACR
    pub const fn to_bits(&self) -> u3 {
        u3::new(match self {
            Self::NoAccess => 0b000,
            Self::PrivReadWrite => 0b001,
            Self::PrivReadWriteUserReadOnly => 0b010,
            Self::ReadWrite => 0b011,
            Self::PrivReadOnly => 0b101,
            Self::ReadOnly => 0b110,
        })
    }
    const fn from_bits(ap: u3) -> Option<Self> {
        match ap.value() {
            0b000 => Some(Self::NoAccess),
            0b001 => Some(Self::PrivReadWrite),
            0b010 => Some(Self::PrivReadWriteUserReadOnly),
            0b011 => Some(Self::ReadWrite),
            0b101 => Some(Self::PrivReadOnly),
            0b110 => Some(Self::ReadOnly),
            _ => None,
        }
    }
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn mem_attr_strong() {
        let mem_attr = MemAttr::StronglyOrdered;
        let mem_attr_bits = mem_attr.to_bits();
        assert_eq!(
            mem_attr_bits,
            MemAttrBits {
                tex: u3::from_u8(0),
                c: false,
                b: false,
                s: true
            }
        );
        let mem_attr2 = mem_attr_bits.decode();
        assert_eq!(Some(mem_attr), mem_attr2);
    }

    #[test]
    fn mem_attr_complex() {
        let mem_attr = MemAttr::Cacheable {
            // 0b01
            outer: CachePolicy::WriteBackWriteAlloc,
            // 0b10
            inner: CachePolicy::WriteThroughNoWriteAlloc,
            shareable: true,
        };
        let mem_attr_bits = mem_attr.to_bits();
        assert_eq!(
            mem_attr_bits,
            MemAttrBits {
                tex: u3::from_u8(0b101),
                c: true,
                b: false,
                s: true
            }
        );
        let mem_attr2 = mem_attr_bits.decode();
        assert_eq!(Some(mem_attr), mem_attr2);
    }
}