Struct CachedPhysicalMemoryBuilder 

pub struct CachedPhysicalMemoryBuilder<T, Q> { /* private fields */ }

The builder interface for constructing a CachedPhysicalMemory object.

Implementations

impl<T> CachedPhysicalMemoryBuilder<T, TimedCacheValidator>

where T: PhysicalMemory,

pub fn new(mem: T) -> CachedPhysicalMemoryBuilder<T, TimedCacheValidator>

Creates a new CachedPhysicalMemory builder. The memory object is mandatory as the CachedPhysicalMemory struct wraps around it.

This type of cache also is required to know the exact page size of the target system. This can either be set directly via the page_size() method or via the arch() method. If no page size has been set this builder will fail to build the CachedPhysicalMemory.

Without further adjustments this function creates a cache that is 2 megabytes in size and caches pages that contain pagetable entries as well as read-only pages.

It is also possible to either let the [CachedPhysicalMemory] object own or just borrow the underlying memory object.

Examples

Moves ownership of a mem object and retrieves it back:

use memflow::architecture::x86::x64;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory, MemoryView};

fn build<T: PhysicalMemory>(mem: T) {
    let mut cache = CachedPhysicalMemory::builder(mem)
        .arch(x64::ARCH)
        .cache_size(size::mb(1))
        .build()
        .unwrap();

    cache.phys_write(0.into(), &MAGIC_VALUE);

    let mut mem = cache.into_inner();

    let value: u64 = mem.phys_view().read(0.into()).unwrap();
    assert_eq!(value, MAGIC_VALUE);
}

Borrowing a mem object:

use memflow::architecture::x86::x64;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory, MemoryView};
use memflow::cglue::{Fwd, ForwardMut};

fn build<T: PhysicalMemory>(mem: Fwd<&mut T>)
    -> impl PhysicalMemory + '_ {
    CachedPhysicalMemory::builder(mem)
        .arch(x64::ARCH)
        .build()
        .unwrap()
}

let mut cache = build(mem.forward_mut());

let value: u64 = cache.phys_view().read(0.into()).unwrap();
assert_eq!(value, MAGIC_VALUE);

cache.phys_write(0.into(), &0u64).unwrap();

// We drop the cache and are able to use mem again
std::mem::drop(cache);

let value: u64 = mem.phys_view().read(0.into()).unwrap();
assert_ne!(value, MAGIC_VALUE);

impl<T, Q> CachedPhysicalMemoryBuilder<T, Q>

where T: PhysicalMemory, Q: CacheValidator,

pub fn build<'a>(self) -> Result<CachedPhysicalMemory<'a, T, Q>, Error>

Builds the CachedPhysicalMemory object or returns an error if the page size is not set.

pub fn validator<QN>(self, validator: QN) -> CachedPhysicalMemoryBuilder<T, QN>

where QN: CacheValidator,

Sets a custom validator for the cache.

If this function is not called it will default to a DefaultCacheValidator. The default validator for std builds is the [TimedCacheValidator]. The default validator for no_std builds is the [CountCacheValidator].

The default setting is DefaultCacheValidator::default().

Examples:

use std::time::Duration;

use memflow::architecture::x86::x64;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory};
use memflow::types::DefaultCacheValidator;

fn build<T: PhysicalMemory>(mem: T) {
    let cache = CachedPhysicalMemory::builder(mem)
        .arch(x64::ARCH)
        .validator(DefaultCacheValidator::new(Duration::from_millis(2000).into()))
        .build()
        .unwrap();
}

pub fn page_size(self, page_size: usize) -> CachedPhysicalMemoryBuilder<T, Q>

Changes the page size of the cache.

The cache has to know the exact page size of the target system internally to give reasonable performance. The page size can be either set directly via this function or it can be fetched from the Architecture via the arch() method of the builder.

If the page size is not set the builder will fail.

Examples

use memflow::types::size;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory};

fn build<T: PhysicalMemory>(mem: T) {
    let cache = CachedPhysicalMemory::builder(mem)
        .page_size(size::kb(4))
        .build()
        .unwrap();
}

pub fn arch( self, arch: impl Into<&'static dyn Architecture>, ) -> CachedPhysicalMemoryBuilder<T, Q>

Retrieves the page size for this cache from the given [Architecture].

The cache has to know the exact page size of the target system internally to give reasonable performance. The page size can be either fetched from the [Architecture] via this method or it can be set directly via the page_size() method of the builder.

If the page size is not set the builder will fail.

Examples

use memflow::architecture::x86::x64;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory};

fn build<T: PhysicalMemory>(mem: T) {
    let cache = CachedPhysicalMemory::builder(mem)
        .arch(x64::ARCH)
        .build()
        .unwrap();
}

pub fn cache_size(self, cache_size: usize) -> CachedPhysicalMemoryBuilder<T, Q>

Sets the total amount of cache to be used.

This is the total amount of cache (in bytes) this page cache will allocate. Ideally you’d want to keep this value low enough so that most of the cache stays in the lower level caches of your cpu.

The default setting is 2 megabytes.

This setting can drastically impact the performance of the cache.

Examples:

use memflow::types::size;
use memflow::architecture::x86::x64;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory};

fn build<T: PhysicalMemory>(mem: T) {
    let cache = CachedPhysicalMemory::builder(mem)
        .arch(x64::ARCH)
        .cache_size(size::mb(2))
        .build()
        .unwrap();
}

pub fn page_type_mask( self, page_type_mask: PageType, ) -> CachedPhysicalMemoryBuilder<T, Q>

Adjusts the type of pages that the cache will hold in it’s cache.

The page type can be a bitmask that contains one or multiple page types. All page types matching this bitmask will be kept in the cache. All pages that are not matching the bitmask will be re-read/re-written on every request.

The default setting is PageType::PAGE_TABLE | PageType::READ_ONLY.

This setting can drastically impact the performance of the cache.

Examples:

use memflow::types::PageType;
use memflow::architecture::x86::x32;
use memflow::mem::{PhysicalMemory, CachedPhysicalMemory};

fn build<T: PhysicalMemory>(mem: T) {
    let cache = CachedPhysicalMemory::builder(mem)
        .arch(x32::ARCH)
        .page_type_mask(PageType::PAGE_TABLE | PageType::READ_ONLY)
        .build()
        .unwrap();
}