Trait Architecture

pub trait Architecture {
    type Registers: Registers;
    type PageTableLevel: Debug + Clone + Copy;
    type Interrupt: Debug + Clone + Copy;
    type SpecialRegister: Debug + Clone + Copy;
    type EventMonitor;
    type EventReason: EventReason;

    const PAGE_SIZE: u64;
    const PAGE_SHIFT: u64;
    const PAGE_MASK: u64;
    const BREAKPOINT: &'static [u8];

    // Required methods
    fn gfn_from_pa(pa: Pa) -> Gfn;
    fn pa_from_gfn(gfn: Gfn) -> Pa;
    fn pa_offset(pa: Pa) -> u64;
    fn va_align_down(va: Va) -> Va;
    fn va_align_down_for(va: Va, level: Self::PageTableLevel) -> Va;
    fn va_align_up(va: Va) -> Va;
    fn va_align_up_for(va: Va, level: Self::PageTableLevel) -> Va;
    fn va_offset(va: Va) -> u64;
    fn va_offset_for(va: Va, level: Self::PageTableLevel) -> u64;
    fn va_index(va: Va) -> u64;
    fn va_index_for(va: Va, level: Self::PageTableLevel) -> u64;
    fn translate_address<Driver>(
        vmi: &VmiCore<Driver>,
        va: Va,
        root: Pa,
    ) -> Result<Pa, VmiError>
       where Driver: VmiDriver<Architecture = Self>;
}

Defines an interface for CPU architecture-specific operations and constants.

The Architecture trait provides generic abstraction for interacting with different CPU architectures in the context of virtual machine introspection.

This trait encapsulates the key characteristics and operations that vary across different CPU architectures, allowing for the implementation of architecture-agnostic tools and libraries.

Required Associated Constants

const PAGE_SIZE: u64

The size of a memory page in bytes for the given architecture.

Architecture-specific

• AMD64: 0x1000 (4096 bytes)

const PAGE_SHIFT: u64

The number of bits to shift when converting between page numbers and physical addresses.

Architecture-specific

• AMD64: 12 (2^12 = 4096)

const PAGE_MASK: u64

A bitmask used to isolate the page number from a full address.

Architecture-specific

• AMD64: 0xFFFFFFFFFFFFF000

const BREAKPOINT: &'static [u8]

The machine code for a breakpoint instruction in the given architecture.

Architecture-specific

• AMD64: &[0xcc] (INT3 instruction)

Required Associated Types

type Registers: Registers

The complete set of CPU registers for the architecture.

This type should include general-purpose registers, and all control and special registers.

type PageTableLevel: Debug + Clone + Copy

An enumeration representing the levels of page tables in the architecture’s paging structure.

Architecture-specific

• AMD64: PML5, PML4, PDPT, PD, PT

type Interrupt: Debug + Clone + Copy

Various types of interrupts that can occur in the architecture.

type SpecialRegister: Debug + Clone + Copy

Represents special-purpose registers in the architecture.

Architecture-specific

• AMD64: May represent control registers like CR0, CR2, CR3, CR4

type EventMonitor

Options for monitoring.

type EventReason: EventReason

Architecture-specific event details.

Required Methods

fn gfn_from_pa(pa: Pa) -> Gfn

Converts a guest physical address (GPA) to a guest frame number (GFN).

Architecture-specific

• AMD64: gfn = pa >> 12

fn pa_from_gfn(gfn: Gfn) -> Pa

Converts a guest frame number (GFN) to a guest physical address (GPA).

Architecture-specific

• AMD64: pa = gfn << 12

fn pa_offset(pa: Pa) -> u64

Extracts the offset within a page from a physical address.

Architecture-specific

• AMD64: offset = pa & 0xfff

fn va_align_down(va: Va) -> Va

Aligns a virtual address down to the nearest page boundary.

Architecture-specific

• AMD64: va & ~0xfff

fn va_align_down_for(va: Va, level: Self::PageTableLevel) -> Va

Aligns a virtual address down to the nearest page boundary for a given page table level.

fn va_align_up(va: Va) -> Va

Aligns a virtual address up to the nearest page boundary.

Architecture-specific

• AMD64: (va + 0xfff) & ~0xfff

fn va_align_up_for(va: Va, level: Self::PageTableLevel) -> Va

Aligns a virtual address up to the nearest page boundary for a given page table level.

fn va_offset(va: Va) -> u64

Extracts the offset within a page from a virtual address.

Architecture-specific

• AMD64: offset = va & 0xfff

fn va_offset_for(va: Va, level: Self::PageTableLevel) -> u64

Calculates the offset within a page for a given virtual address and page table level.

fn va_index(va: Va) -> u64

Calculates the index into the lowest level page table for a given virtual address.

Architecture-specific

• AMD64: index = va & 0x1ff

fn va_index_for(va: Va, level: Self::PageTableLevel) -> u64

Calculates the index into the specified level of the page table hierarchy for a given virtual address.

fn translate_address<Driver>( vmi: &VmiCore<Driver>, va: Va, root: Pa, ) -> Result<Pa, VmiError>

where Driver: VmiDriver<Architecture = Self>,

Performs a full page table walk to translate a virtual address to a physical address.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors