Add README and function documentation
Signed-off-by: Imre Kis <imre.kis@arm.com>
Change-Id: Idda9f54712a309c30a8684a073769973eb6fef03
diff --git a/src/lib.rs b/src/lib.rs
index a294d14..c939335 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -3,6 +3,7 @@
#![allow(dead_code)]
#![cfg_attr(not(test), no_std)]
+#![doc = include_str!("../README.md")]
extern crate alloc;
@@ -62,19 +63,30 @@
}
bitflags! {
+ /// Memory access rights
#[derive(Debug, Clone, Copy)]
pub struct MemoryAccessRights : u32 {
+ /// Read
const R = 0b00000001;
+ /// Write
const W = 0b00000010;
+ /// Execute
const X = 0b00000100;
+ /// Non-secure
const NS = 0b00001000;
+ /// Read-write
const RW = Self::R.bits() | Self::W.bits();
+ /// Read-execute
const RX = Self::R.bits() | Self::X.bits();
+ /// Read-write-execute
const RWX = Self::R.bits() | Self::W.bits() | Self::X.bits();
+ /// User accessible
const USER = 0b00010000;
+ /// Device region
const DEVICE = 0b00100000;
+ /// Global (not tied to ASID)
const GLOBAL = 0b01000000;
}
}
@@ -113,22 +125,31 @@
}
}
+/// Virtual Address range, selects x in `TTBRx_EL*`
#[derive(Debug, Clone, Copy)]
pub enum RegimeVaRange {
+ /// Lower virtual address range, select `TTBR0_EL*`
Lower,
+ /// Upper virtual address range, select `TTBR1_EL*`
Upper,
}
+/// Translation regime
#[derive(Debug, Clone, Copy)]
pub enum TranslationRegime {
- EL1_0(RegimeVaRange, u8), // EL1 and EL0 stage 1, TTBRx_EL1
+ /// EL1 and EL0 stage 1, TTBRx_EL1
+ EL1_0(RegimeVaRange, u8),
#[cfg(target_feature = "vh")]
- EL2_0(RegimeVaRange, u8), // EL2 and EL0 with VHE
- EL2, // EL2
- EL3, // EL3, TTBR0_EL3
+ /// EL2 and EL0 with VHE
+ EL2_0(RegimeVaRange, u8),
+ /// EL2
+ EL2,
+ /// EL3, TTBR0_EL3
+ EL3,
}
impl TranslationRegime {
+ /// Checks if the translation regime uses the upper virtual address range.
fn is_upper_va_range(&self) -> bool {
match self {
TranslationRegime::EL1_0(RegimeVaRange::Upper, _) => true,
@@ -139,12 +160,15 @@
}
}
+/// Translation granule
pub type TranslationGranule<const VA_BITS: usize> = granule::TranslationGranule<VA_BITS>;
/// Trait for converting between virtual address space of the running kernel environment and
/// the physical address space.
pub trait KernelAddressTranslator {
+ /// Convert virtual address of the running kernel environment into a physical address.
fn kernel_to_pa(va: VirtualAddress) -> PhysicalAddress;
+ /// Convert physical address into a virtual address of the running kernel environment.
fn pa_to_kernel(pa: PhysicalAddress) -> VirtualAddress;
}
@@ -158,6 +182,7 @@
}
/// Memory translation table handling
+///
/// # High level interface
/// * allocate and map zero initialized region (with or without VA)
/// * allocate and map memory region and load contents (with or without VA)
@@ -176,13 +201,20 @@
/// * find a mapped region which contains
/// * find empty area for region
/// * set access rights for a region
-/// * create blocks by region
///
/// # Block level interface
/// * map block
/// * unmap block
/// * set access rights of block
impl<K: KernelAddressTranslator, const VA_BITS: usize> Xlat<K, VA_BITS> {
+ /// Create new Xlat instance
+ /// # Arguments
+ /// * page_pool: Page pool to allocate translation tables
+ /// * address: Virtual address range
+ /// * regime: Translation regime
+ /// * granule: Translation granule
+ /// # Return value
+ /// * Xlat instance
pub fn new(
page_pool: PagePool,
address: VirtualAddressRange,
@@ -519,6 +551,7 @@
/// * level: Level of the translation table
/// * va: Base virtual address of the table
/// * table: Table entries
+ /// * granule: Translation granule
fn dump_table(
f: &mut fmt::Formatter<'_>,
level: isize,
@@ -566,6 +599,7 @@
/// uses the block level functions to do the mapping.
/// # Arguments
/// * region: Memory region object
+ /// * attributes: Memory attributes
/// # Return value
/// * Virtual address of the mapped memory
fn map_region(
@@ -606,7 +640,8 @@
/// Find mapped region that contains the whole region
/// # Arguments
- /// * region: Virtual address to look for
+ /// * va: Virtual address to look for
+ /// * length: Length of the region
/// # Return value
/// * Reference to virtual region if found
fn find_containing_region(&self, va: VirtualAddress, length: usize) -> Option<&VirtualRegion> {