jit/

mmu.rs

//! The MMU separates guest addresses and permissions from unsafe host pointers used by JIT code.
//!
//! Linux mapping rules: https://man7.org/linux/man-pages/man2/mmap.2.html
//! Rust C layout rules: https://doc.rust-lang.org/reference/type-layout.html#the-c-representation

use crate::{DEFAULT_STACK_SIZE, DEFAULT_STACK_TOP, JitResult, PAGE_SIZE, ProgramImage};

use std::io;
use std::ops::{BitOr, BitOrAssign};

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Uses Linux protection bits so mapping operations need no second permission model.
pub struct PagePerms(u8);

/*

    wip - siehe notion

    todo
    ----
    - schnitstelle nach außen
    - magic values
    - größen

*/

// todo -- nochmal neu
impl PagePerms {
    // One bit represents one independent permission. These values also match Linux PROT_* values.
    // Bit 0 has value 1, bit 1 has value 2, and bit 2 has value 4.
    /// Allows guest reads from a page.
    pub const READ: Self = Self(1 << 0);
    /// Allows guest writes to a page.
    pub const WRITE: Self = Self(1 << 1);
    /// Allows guest instruction fetches from a page.
    pub const EXEC: Self = Self(1 << 2);
    // pub const RWX: Self

    /// Creates permissions that deny all guest accesses.
    pub const fn empty() -> Self {
        // Zero has no permission bits set. It represents a mapped page with no allowed access.
        Self(0)
    }

    /// Returns the three permission bits used by generated code.
    pub const fn bits(self) -> u8 {
        // Generated code needs the compact bit value because it cannot call this Rust type.
        self.0
    }

    /// Creates permissions and removes bits that this MMU does not support.
    pub const fn from_bits(bits: u8) -> Self {
        // Ignore unknown protection bits so they cannot enter the JIT ABI.
        // Binary 111 keeps only the low READ, WRITE, and EXEC bits.
        Self(bits & 0b111)
    }

    /// Tests whether all permissions in `other` are present.
    pub const fn contains(self, other: Self) -> bool {
        // AND removes all bits that are not requested. Equality means that every requested bit exists.
        (self.0 & other.0) == other.0
    }
}

impl BitOr for PagePerms {
    type Output = Self;

    fn bitor(self, rhs: Self) -> Self::Output {
        // OR combines independent permissions without changing permissions that already exist.
        // This trait lets callers write `READ | WRITE` instead of calling a helper function.
        Self(self.0 | rhs.0)
    }
}

impl BitOrAssign for PagePerms {
    fn bitor_assign(&mut self, rhs: Self) {
        // This trait gives `|=` the same bit-combine rule as `|`.
        self.0 |= rhs.0;
    }
}

// ist shared siehe emitter
#[repr(C)]
#[derive(Clone, Copy)]
/// Keeps the host and generated-code page layout identical across the C ABI.
// `repr(C)` fixes field order. The default Rust layout does not give this guarantee.
pub struct GuestPageAbi {
    /// Gives the aligned guest address of the first byte in this page.
    pub guest_base: u64,
    /// Gives the compact [`PagePerms`] bits checked by generated code.
    pub perms: u8,
    // Seven bytes fill the space after `perms`. The next pointer then starts on an 8-byte boundary.
    /// Keeps `data` at the offset that the generated ABI expects.
    pub _padding: [u8; 7],
    // Generated code uses this pointer after it has checked the guest address and permission.
    /// Points to the first host byte of this guest page.
    pub data: *mut u8,
}

#[repr(C)]
#[derive(Clone, Copy)]
/// Caches one guest-to-host translation to avoid a page search on common accesses.
pub struct GuestTranslationAbi {
    /// Identifies the guest page held in this cache entry.
    pub guest_base: u64,
    // A write uses this index to record the owning page in the dirty-page list.
    /// Identifies the page in the ABI page array for dirty tracking.
    pub page_index: usize,
    /// Copies the page permissions so a cache hit still checks access rights.
    pub perms: u8,
    // Explicit padding gives this host type the same layout as the type in generated Rust code.
    /// Keeps `data` at the offset that the generated ABI expects.
    pub _padding: [u8; 7],
    // This pointer is null until the cache contains a valid translation.
    /// Points to the first host byte, or is null when this entry is empty.
    pub data: *mut u8,
}

impl Default for GuestTranslationAbi {
    fn default() -> Self {
        // A null data pointer marks an empty cache entry. Guest address zero can then be cached safely.
        Self {
            guest_base: 0,
            page_index: 0,
            perms: 0,
            _padding: [0; 7],
            data: std::ptr::null_mut(),
        }
    }
}

#[repr(C)]
/// Exposes only stable pointers and lengths because generated code cannot use Rust containers.
pub struct GuestMemoryAbi {
    // This raw pointer refers to a contiguous `abi_pages` vector owned by `GuestMemory`.
    /// Points to the sorted page descriptions used by generated binary search.
    pub pages: *const GuestPageAbi,
    // Generated binary search uses the count to stay inside the raw page array.
    /// Limits generated searches to valid entries in `pages`.
    pub page_count: usize,
    // Publish the selected page size in the mirrored ABI. The current template embeds the same constant.
    /// Gives the page size that defines guest page offsets.
    pub page_size: usize,
    // Sixteen entries give a small power-of-two cache. Generated code can select a slot with `& 15`.
    /// Keeps recent translations so common accesses do not need binary search.
    pub translations: [GuestTranslationAbi; 16],
    // todo -- von gamozo
    // The list lets restore visit only changed pages. The bitmap records each page once.
    /// Points to page indices changed since the current snapshot baseline.
    pub dirty_pages: *mut usize,
    // Only this prefix of `dirty_pages` contains page indices for the current snapshot interval.
    /// Gives the valid prefix length of `dirty_pages`.
    pub dirty_count: usize,
    /// Points to one bit per page so each dirty page enters the list once.
    pub dirty_bitmap: *mut u64,
}

#[derive(Clone)]
// A boxed page keeps its data address stable when the sorted page vector moves its entries.
struct OwnedPage {
    // The base has page alignment. An offset in this page is always smaller than `PAGE_SIZE`.
    base: u64,
    perms: PagePerms,
    data: Box<[u8; PAGE_SIZE]>,
}

/// Owns guest pages and maintains the pointer-based view used by compiled regions.
pub struct GuestMemory {
    // Pages stay in guest-address order because all lookup paths use binary search.
    pages: Vec<OwnedPage>,
    // This second vector has the simple C layout that generated code can read.
    abi_pages: Vec<GuestPageAbi>,
    // Restore visits only these changed page indices instead of copying all guest memory.
    dirty_pages: Vec<usize>,
    // One bit records each page at most once, even when generated code writes it many times.
    dirty_bitmap: Vec<u64>,
    abi: GuestMemoryAbi,
    // A true value requires fresh raw pointers before generated code enters the MMU ABI.
    abi_dirty: bool, // gamozo siehe
    // A revision change means that snapshot page indices can no longer be trusted.
    mapping_revision: u64,
    /// Gives the first address after the current guest heap.
    // `brk` is the first address after the current guest heap.
    pub brk: u64,
    /// Gives the fixed exclusive stack top used to build the initial process stack.
    // The fixed top is exclusive. Stack data grows toward lower guest addresses.
    pub stack_top: u64,
}

// fast reset -- tofo optimze?
impl Clone for GuestMemory {

    fn clone(&self) -> Self {
        // Rebuild all ABI pointers because pointers in the source memory refer to its allocations.
        // A derived `Clone` would copy stale raw pointers and could make generated code use old memory.
        let mut memory = Self {
            pages: self.pages.clone(),
            abi_pages: Vec::new(),
            dirty_pages: Vec::new(),
            dirty_bitmap: Vec::new(),
            abi: GuestMemoryAbi {
                pages: std::ptr::null(),
                page_count: 0,
                page_size: PAGE_SIZE,
                translations: [GuestTranslationAbi::default(); 16],
                dirty_pages: std::ptr::null_mut(),
                dirty_count: 0,
                dirty_bitmap: std::ptr::null_mut(),
            },
            abi_dirty: true,
            mapping_revision: self.mapping_revision,
            brk: self.brk,
            stack_top: self.stack_top,
        };
        memory.sync_abi();
        memory
    }
}

impl Default for GuestMemory {
    fn default() -> Self {
        // Keep one construction path so `new` and `default` cannot get different ABI state.
        Self::new()
    }
}

// todo - 4096 passt?
impl GuestMemory {
    /// Starts with no mappings so ELF loading can define all initial permissions.
    pub fn new() -> Self {
        Self {
            pages: Vec::new(),
            abi_pages: Vec::new(),
            dirty_pages: Vec::new(),
            dirty_bitmap: Vec::new(),
            abi: GuestMemoryAbi {
                pages: std::ptr::null(),
                page_count: 0,
                page_size: PAGE_SIZE,
                translations: [GuestTranslationAbi::default(); 16],
                dirty_pages: std::ptr::null_mut(),
                dirty_count: 0,
                dirty_bitmap: std::ptr::null_mut(),
            },
            abi_dirty: true,
            mapping_revision: 0,
            brk: 0, // heap
            stack_top: 0,
        }
    }

    /// Maps one program image and creates its fixed high guest stack.
    pub fn from_program(program: &ProgramImage) -> JitResult<Self> {
        // Create all initial process mappings in one place so the runtime gets a complete ABI view.
        let mut memory = Self::new();

        memory.map_program(program)?;

        // A fixed high stack keeps it separate from the image, heap, and mmap area.
        memory.map_zeroed(
            DEFAULT_STACK_TOP - DEFAULT_STACK_SIZE,
            DEFAULT_STACK_SIZE,
            PagePerms::READ | PagePerms::WRITE,
        )?;

        memory.stack_top = DEFAULT_STACK_TOP;
        memory.sync_abi();

        // dbg!(memory);

        Ok(memory)
    }

    // todo -- wichtig. anders machen
    /// Refreshes raw pointers only when mappings changed, which keeps normal dispatch inexpensive.
    pub fn as_abi_mut(&mut self) -> *mut GuestMemoryAbi {
        if self.abi_dirty {
            self.sync_abi();
        }
        // Rust converts this mutable reference to a raw pointer for the generated C ABI.
        // The `GuestMemory` box must stay alive while generated code uses this pointer.
        &mut self.abi
    }

    /// Maps the main image at its linked addresses and sets the initial heap end.
    pub fn map_program(&mut self, program: &ProgramImage) -> JitResult<()> {
        // A zero bias keeps the linked virtual addresses of the main executable unchanged.
        self.map_program_at(program, 0)?;
        // Linux starts `brk` after the last load segment.
        self.brk = program.brk_base;

        Ok(())
    }

    /// Maps an image with an address bias so a position-independent loader can coexist with it.
    pub fn map_program_at(&mut self, program: &ProgramImage, bias: u64) -> JitResult<()> {
        // The bias relocates a position-independent interpreter without changing the stored
        // ELF segment metadata.
        for segment in &program.segments {
            // `?` stops this function and forwards the error if checked addition fails.
            let base = bias
                .checked_add(segment.vaddr)
                .ok_or_else(|| io::Error::other("segment address overflow"))?;

            self.map_bytes(base, &segment.bytes, segment.perms)?;

            // ELF memory beyond the file payload is BSS and must start as zero.
            if segment.mem_size > segment.file_size {
                self.map_zeroed(
                    base + segment.file_size,
                    segment.mem_size - segment.file_size,
                    segment.perms,
                )?;
            }
        }

        Ok(())
    }

    /// Ensures that all pages in a byte range exist, start with zero, and include `perms`.
    pub fn map_zeroed(&mut self, base: u64, size: u64, perms: PagePerms) -> JitResult<()> {
        if size == 0 {
            // A zero-length ELF BSS or mapping has no pages and is a successful no-op.
            return Ok(());
        }

        // Guest addresses are untrusted. Checked addition prevents an address wrap to zero.
        let end = base
            .checked_add(size)
            .ok_or_else(|| io::Error::other("overflow"))?;

        let mut page_base = align_down(base, PAGE_SIZE as u64);
        // Subtract one because an end on a page boundary does not include the next page.
        let last_page = align_down(end.saturating_sub(1), PAGE_SIZE as u64);

        // Include partial edge pages because guest mappings do not have to start at page boundaries.
        while page_base <= last_page {
            let page = self.ensure_page(page_base, perms);
            // A segment can share an edge page with another segment. Keep permissions from both.
            page.perms |= perms;
            // Saturation prevents wraparound from turning the loop back to address zero.
            page_base = page_base.saturating_add(PAGE_SIZE as u64);
        }

        Ok(())
    }

    /// Copies image bytes into mapped pages without requiring guest write permission.
    pub fn map_bytes(&mut self, base: u64, bytes: &[u8], perms: PagePerms) -> JitResult<()> {
        // let mut page_base = align_down(base, PAGE_SIZE as u64);

        // Write through the loader path because ELF segments can start or end inside a shared page.
        for (offset, byte) in bytes.iter().enumerate() {
            let addr = base
                .checked_add(offset as u64)
                .ok_or_else(|| io::Error::other("overflow"))?;

            // Loading must initialize read-only and executable pages without a guest write.
            self.write_mapped_byte(addr, *byte, perms)?;
        }
        Ok(())
    }

    /// Replaces complete pages so fixed mappings cannot retain old bytes or permissions.
    pub fn replace_mapping(
        &mut self,
        base: u64,
        size: u64,
        perms: PagePerms,
        bytes: &[u8],
    ) -> JitResult<()> {
        // Linux MAP_FIXED and munmap require a page-aligned start address.
        if size == 0 || !base.is_multiple_of(PAGE_SIZE as u64) {
            return Err(io::Error::other("invalid mapping").into());
        }

        // Remove old bytes and permissions so a fixed mmap cannot expose stale contents.
        self.unmap(base, size)?;
        self.map_zeroed(base, size, perms)?;

        // Ignore file bytes after the mapping size so they cannot enter the next guest page.
        for (offset, byte) in bytes.iter().take(size as usize).enumerate() {
            self.write_mapped_byte(base + offset as u64, *byte, perms)?;
        }

        Ok(())
    }

    /// Replaces permissions on each mapped page in an aligned range.
    ///
    /// The function returns `false` for an invalid range or a missing page. It can change an
    /// earlier page before it finds a missing later page.
    pub fn protect(&mut self, base: u64, size: u64, perms: PagePerms) -> bool {
        // An invalid range changes nothing. A missing later page can leave earlier pages changed.
        let Some((start, end)) = page_range(base, size) else {
            return false;
        };

        let mut page_base = start;
        
        // perf binary search
        while page_base < end {
            let Some(idx) = self
                .pages
                .binary_search_by_key(&page_base, |page| page.base)
                .ok()
            else {
                return false;
            };

            if self.pages[idx].perms != perms {
                self.pages[idx].perms = perms;
                // Generated translation entries include permissions and must be invalidated.
                self.mapping_changed();
            }
            // Each iteration changes exactly one page in the requested range.
            page_base += PAGE_SIZE as u64;
        }

        true
    }

    /// Removes all pages in an aligned, half-open range.
    pub fn unmap(&mut self, base: u64, size: u64) -> JitResult<()> {
        // Use one half-open page range so removal follows the same boundary rules as protection.
        let Some((start, end)) = page_range(base, size) else {
            return Err(io::Error::other("keine valid mapping ").into());
        };

        let old_len = self.pages.len();
        // `retain` keeps pages outside the range and drops pages inside the range.
        self.pages
            .retain(|page| page.base < start || page.base >= end);
        if self.pages.len() != old_len {
            self.mapping_changed();
        }

        // dbg!(self.pages);
        Ok(())
    }

    /// Finds the first page-aligned free range at or after `start`.
    pub fn find_free_range(&self, start: u64, size: u64) -> Option<u64> {
        // Both values need page alignment because Linux creates complete-page mappings.
        let size = align_up(size, PAGE_SIZE as u64);
        let mut base = align_up(start, PAGE_SIZE as u64);

        // Sorted pages make the first sufficient gap a deterministic mmap result.
        for page in &self.pages {
            if page.base < base {
                continue;
            }
            if base.checked_add(size)? <= page.base {
                return Some(base);
            }
            // Continue after this occupied page. Checked addition rejects address-space overflow.
            base = page.base.checked_add(PAGE_SIZE as u64)?;
        }

        Some(base)
    }

    /// Tests whether an aligned, nonempty range has no mapped page.
    pub fn range_is_free(&self, base: u64, size: u64) -> bool {
        let Some((start, end)) = page_range(base, size) else {
            return false;
        };
        // `all` returns true only when no page overlaps the requested half-open range.
        self.pages
            .iter()
            .all(|page| page.base < start || page.base >= end)
    }

    // todo -- code dup
    /// Loads at most eight little-endian bytes when the full range is readable.
    pub fn load_le(&self, addr: u64, size: usize) -> Option<u64> {
        let mut value = 0u64;

        // Callers must request at most eight bytes because the result container is u64.
        for idx in 0..size {
            // Here, `?` changes any invalid address or denied read into `None` for the full load.
            let byte = self.read_byte(addr.checked_add(idx as u64)?, PagePerms::READ)?;
            // One byte has 8 bits. Little endian puts the byte at the lowest address in bits 0..7.
            value |= (byte as u64) << (idx * 8);
        }

        Some(value)
    }

    /// Copies a readable guest range and returns `None` if any byte is unavailable.
    pub fn load_bytes(&self, addr: u64, size: usize) -> Option<Vec<u8>> {
        let mut result = Vec::with_capacity(size);
        let mut current = addr;

        // Copy one page span at a time to reduce repeated searches for large buffers.
        while result.len() < size {
            let page = self.find_page(current)?;
            if !page.perms.contains(PagePerms::READ) {
                return None;
            }

            let offset = (current - page.base) as usize;
            // Stop at this page end or the requested buffer end, whichever comes first.
            let count = (PAGE_SIZE - offset).min(size - result.len());
            result.extend_from_slice(&page.data[offset..offset + count]);
            current = current.checked_add(count as u64)?;
        }

        Some(result)
    }

    /// Fetches one little-endian 16-bit instruction parcel with execute permission.
    pub fn fetch_u16(&self, addr: u64) -> Option<u16> {
        // Instruction fetch needs execute permission even when the page is not readable.
        let bytes = [
            self.read_byte(addr, PagePerms::EXEC)?,
            self.read_byte(addr.checked_add(1)?, PagePerms::EXEC)?,
        ];
        // RISC-V code in this runtime is little endian, so array byte 0 is the low byte.
        Some(u16::from_le_bytes(bytes))
    }

    /// Fetches one little-endian 32-bit instruction word with execute permission.
    pub fn fetch_u32(&self, addr: u64) -> Option<u32> {
        // Fetch each byte separately because a four-byte instruction can cross a page boundary.
        let bytes = [
            self.read_byte(addr, PagePerms::EXEC)?,
            self.read_byte(addr.checked_add(1)?, PagePerms::EXEC)?,
            self.read_byte(addr.checked_add(2)?, PagePerms::EXEC)?,
            self.read_byte(addr.checked_add(3)?, PagePerms::EXEC)?,
        ];
        // `from_le_bytes` gives the same instruction word on little- and big-endian hosts.
        Some(u32::from_le_bytes(bytes))
    }

    /// Finds the exclusive end of consecutive executable pages that contain `addr`.
    pub fn executable_end(&self, addr: u64) -> Option<u64> {
        let mut page = self.find_page(addr)?;
        if !page.perms.contains(PagePerms::EXEC) {
            return None;
        }

        let mut end = page.base + PAGE_SIZE as u64;
        // Stop at the first gap or non-executable page so AOT lifting stays in valid code.
        while let Some(next) = self.find_page(end) {
            page = next;
            if !page.perms.contains(PagePerms::EXEC) {
                break;
            }
            end += PAGE_SIZE as u64;
        }
        Some(end)
    }

    /// Stores at most eight little-endian bytes and records each changed page.
    ///
    /// The store is not atomic. It can change initial bytes before a later byte fails.
    pub fn store_le(&mut self, addr: u64, size: usize, value: u64) -> bool {
        // This byte loop is not atomic. A later fault does not undo bytes already written.
        // Callers must request at most eight bytes because the source container is u64.
        for idx in 0..size {
            // Move the selected byte to bits 0..7, then mask off all higher bits with 0xff.
            let byte = ((value >> (idx * 8)) & 0xff) as u8;

            let Some(byte_addr) = addr.checked_add(idx as u64) else {
                return false;
            };

            if self.write_byte(byte_addr, byte, PagePerms::WRITE).is_none() {
                return false;
            }
        }
        true
    }

    /// Copies bytes to writable guest pages and records each changed page.
    ///
    /// The store is not atomic. It can change an initial page span before a later span fails.
    pub fn store_bytes(&mut self, addr: u64, bytes: &[u8]) -> bool {
        let mut written = 0;
        let mut current = addr;

        // This operation can write an initial page span before a later span fails.
        // Copy contiguous page spans because syscall buffers can be much larger than one value.
        while written < bytes.len() {
            let page_base = align_down(current, PAGE_SIZE as u64);
            let Ok(index) = self
                .pages
                .binary_search_by_key(&page_base, |page| page.base)
            else {
                return false;
            };

            if !self.pages[index].perms.contains(PagePerms::WRITE) {
                return false;
            }
            let offset = (current - page_base) as usize;
            // One copy ends at a page boundary or at the input end.
            let count = (PAGE_SIZE - offset).min(bytes.len() - written);
            self.pages[index].data[offset..offset + count]
                .copy_from_slice(&bytes[written..written + count]);

            self.mark_dirty(index);
            written += count;
            let Some(next) = current.checked_add(count as u64) else {
                return false;
            };
            current = next;
        }
        true
    }

    // todo -- refactor quatsch
    pub(crate) fn clear_dirty(&mut self) {
        // Start a new dirty interval and force the next memory access to revalidate its translation.
        self.abi.dirty_count = 0;
        self.dirty_bitmap.fill(0);
        self.clear_translations();
    }

    pub(crate) fn restore_dirty_from(&mut self, snapshot: &GuestMemory) -> bool {
        // Dirty-page restore is safe only when page indices still identify the same mappings.
        if self.mapping_revision != snapshot.mapping_revision
            || self.pages.len() != snapshot.pages.len()
            // `zip` compares page pairs at the same sorted index in both memories.
            || self
                .pages
                .iter()
                .zip(&snapshot.pages)
                .any(|(page, saved)| page.base != saved.base || page.perms != saved.perms)
        {
            return false;
        }

        for slot in 0..self.abi.dirty_count {
            // Each list entry names one page that changed after the snapshot.
            let index = self.dirty_pages[slot];
            self.pages[index]
                .data
                .copy_from_slice(&snapshot.pages[index].data[..]);
        }
        self.brk = snapshot.brk;
        self.stack_top = snapshot.stack_top;
        self.clear_dirty();
        true
    }

    /// Tests execute permission for the page that contains `addr`.
    pub fn can_execute(&self, addr: u64) -> bool {
        self.find_page(addr)
            .map(|page| page.perms.contains(PagePerms::EXEC))
            .unwrap_or(false)
    }

    /// Returns adjacent pages with equal permissions as half-open mapping ranges.
    pub fn mappings(&self) -> Vec<(u64, u64, PagePerms)> {
        // Each returned tuple uses a half-open range: `start` is included and `end` is not.
        let mut mappings = Vec::new();
        for page in &self.pages {
            // Merge adjacent pages with equal permissions to give process-style mapping ranges.
            if let Some((_, end, perms)) = mappings.last_mut()
                && *end == page.base
                && *perms == page.perms
            {
                *end += PAGE_SIZE as u64;
            } else {
                mappings.push((page.base, page.base + PAGE_SIZE as u64, page.perms));
            }
        }
        mappings
    }

    fn ensure_page(&mut self, base: u64, perms: PagePerms) -> &mut OwnedPage {
        // Keep pages sorted because runtime and generated lookups both use binary search.
        match self.pages.binary_search_by_key(&base, |page| page.base) {
            Ok(idx) => {
                if !self.pages[idx].perms.contains(perms) {
                    self.pages[idx].perms |= perms;
                    self.mapping_changed();
                }
                &mut self.pages[idx]
            }

            Err(idx) => {
                // Binary search returns the insertion index in `Err`, so insertion keeps sort order.
                self.mapping_changed();
                self.pages.insert(
                    idx,
                    OwnedPage {
                        base,
                        perms,
                        // Anonymous mappings and ELF BSS require zero-filled initial bytes.
                        data: Box::new([0; PAGE_SIZE]),
                    },
                );
                &mut self.pages[idx]
            }
        }
    }

    fn find_page(&self, addr: u64) -> Option<&OwnedPage> {
        // Remove the offset bits so every address in one page has the same search key.
        let page_base = align_down(addr, PAGE_SIZE as u64);

        self.pages
            .binary_search_by_key(&page_base, |page| page.base)
            .ok()
            .map(|idx| &self.pages[idx])
    }

    fn read_byte(&self, addr: u64, perms: PagePerms) -> Option<u8> {
        let page = self.find_page(addr)?;

        if !page.perms.contains(perms) {
            return None;
        }

        // Subtraction changes a guest address into an index in the page allocation.
        let offset = (addr - page.base) as usize;
        Some(page.data[offset])
    }

    fn write_byte(&mut self, addr: u64, byte: u8, perms: PagePerms) -> Option<()> {
        // Page alignment removes the low 12 address bits when pages have 4096 bytes.
        let page_base = align_down(addr, PAGE_SIZE as u64);


        let index = self
            .pages
            .binary_search_by_key(&page_base, |page| page.base)
            .ok()?;
        let page = &mut self.pages[index];

        if !page.perms.contains(perms) {
            return None;
        }

        let offset = (addr - page.base) as usize;
        page.data[offset] = byte;

        self.mark_dirty(index);
        Some(())
    }

    fn write_mapped_byte(&mut self, addr: u64, byte: u8, perms: PagePerms) -> JitResult<()> {
        let page_base = align_down(addr, PAGE_SIZE as u64);
        let page = self.ensure_page(page_base, perms);
        page.perms |= perms;

        let offset = (addr - page.base) as usize;
        // Image loading does not mark pages dirty. A later snapshot records these bytes as baseline.
        page.data[offset] = byte;

        Ok(())
    }

    // todo wichtig
    fn sync_abi(&mut self) {
        // Build pointer arrays only after page storage is in its final position for this revision.
        self.abi_pages = self
            .pages
            // Mutable iteration is needed because `as_mut_ptr` creates pointers to page bytes.
            .iter_mut()
            .map(|page| GuestPageAbi {
                guest_base: page.base,
                perms: page.perms.bits(),
                _padding: [0; 7],
                data: page.data.as_mut_ptr(),
            })
            .collect();

        // The list needs at most one entry for each page.
        self.dirty_pages.resize(self.pages.len(), 0);
        // One u64 bitmap word has 64 bits, so it tracks 64 pages. Round up for a partial word.
        self.dirty_bitmap.resize(self.pages.len().div_ceil(64), 0);
        // A rebuilt ABI starts a new dirty interval, so no old page index can remain set.
        self.dirty_bitmap.fill(0);

        self.abi.pages = self.abi_pages.as_ptr();
        self.abi.page_count = self.abi_pages.len();
        self.abi.page_size = PAGE_SIZE;
        // These pointers stay valid until a mapping change can resize their owner vectors.
        self.abi.dirty_pages = self.dirty_pages.as_mut_ptr();
        self.abi.dirty_count = 0;
        self.abi.dirty_bitmap = self.dirty_bitmap.as_mut_ptr();
        self.clear_translations();
        self.abi_dirty = false;
    }

    fn mark_dirty(&mut self, index: usize) {
        if self.abi_dirty {
            self.sync_abi();
        }
        // Integer division selects the group of 64 pages.
        let word = index / 64;
        // The remainder selects one bit in that group. Shifting 1 creates its mask.
        let bit = 1u64 << (index % 64);
        // Record each page once so restore cost depends on changed pages, not write count.
        if self.dirty_bitmap[word] & bit == 0 {
            self.dirty_bitmap[word] |= bit;
            self.dirty_pages[self.abi.dirty_count] = index;
            self.abi.dirty_count += 1;
        }

        //dbg!(self.dirty_pages);
    }

    fn mapping_changed(&mut self) {
        // A mapping change can invalidate pointers. A permission change makes the ABI page view stale.
        // Both changes also invalidate cached translations.
        self.abi_dirty = true;
        // Only revision equality matters. Wrapping avoids a panic after an extreme number of changes.
        self.mapping_revision = self.mapping_revision.wrapping_add(1);
        self.clear_translations();
    }

    fn clear_translations(&mut self) {
        // Array repeat syntax copies the empty entry into all sixteen direct-cache slots.
        self.abi.translations = [GuestTranslationAbi::default(); 16];
    }
}

pub(crate) fn align_down(value: u64, align: u64) -> u64 {
    // Page and stack alignments are powers of two, so a mask avoids division.
    // For a power-of-two alignment, `align - 1` has all offset bits set.
    // NOT changes it to a mask that keeps only the aligned address bits.
    value & !(align - 1)
}

pub(crate) fn align_up(value: u64, align: u64) -> u64 {
    if value == 0 {
        // Handle zero first because the general formula subtracts one.
        0
    } else {
        // Set all low offset bits with OR, then add one to reach the next aligned value.
        // Subtract one first so an already aligned value stays unchanged.
        // The caller must ensure that the rounded result fits in `u64`.
        ((value - 1) | (align - 1)) + 1
    }
}

fn page_range(base: u64, size: u64) -> Option<(u64, u64)> {
    // The start must have page alignment. The end rounds up because a partial last page is included.
    if size == 0 || !base.is_multiple_of(PAGE_SIZE as u64) {
        return None;
    }

    // `?` rejects overflow in `base + size`. The rounded end must also fit in `u64`.
    // `align_up` has an unchecked final addition, so callers must keep the range below that limit.
    let end = align_up(base.checked_add(size)?, PAGE_SIZE as u64);
    Some((base, end))
}