ax-memory-set 0.8.0

Data structures and operations for managing memory mappings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

use ax_memory_addr::MemoryAddr;

/// Underlying operations to do when manipulating mappings within the specific
/// [`MemoryArea`](crate::MemoryArea).
///
/// The backend can be different for different memory areas. e.g., for linear
/// mappings, the target physical address is known when it is added to the page
/// table. For lazy mappings, an empty mapping needs to be added to the page
/// table to trigger a page fault.
pub trait MappingBackend: Clone {
    /// The address type used in the memory area.
    type Addr: MemoryAddr;
    /// The flags type used in the memory area.
    type Flags: Copy;
    /// Per-mutation state that must be shared by all page-table operations in
    /// one logical mapping transaction.
    type MutationContext;
    /// The page table type used in the memory area.
    type PageTable;

    /// What to do when mapping a region within the area with the given flags.
    fn map(
        &self,
        start: Self::Addr,
        size: usize,
        flags: Self::Flags,
        context: &mut Self::MutationContext,
        page_table: &mut Self::PageTable,
    ) -> bool;

    /// Read-only validation for a mapping operation.  Backends that can
    /// inspect conflicts or allocation requirements should override this
    /// hook.  `MemorySet` invokes it before an overlapping `MAP_FIXED`
    /// operation removes the old mapping, so a rejected request has no
    /// externally visible side effect.
    fn validate_map(
        &self,
        _start: Self::Addr,
        _size: usize,
        _flags: Self::Flags,
        _page_table: &Self::PageTable,
    ) -> bool {
        true
    }

    /// What to do when unmaping a memory region within the area.
    fn unmap(
        &self,
        start: Self::Addr,
        size: usize,
        context: &mut Self::MutationContext,
        page_table: &mut Self::PageTable,
    ) -> bool;

    /// Preflights mapping shape and resource ownership for [`Self::unmap`].
    ///
    /// The page table is not mutated between this preflight and commit. A
    /// backend that can predict rejection from mapping shape or owned
    /// resources must override this method. The commit can still fail because
    /// of concurrent external state or resource pressure; in that case earlier
    /// disjoint subranges may already be unmapped, while `MemorySet` retains
    /// all area metadata and backend owners so the caller can quarantine and
    /// retry the published mutation.
    fn validate_unmap(
        &self,
        _start: Self::Addr,
        _size: usize,
        _page_table: &Self::PageTable,
    ) -> bool {
        true
    }

    /// Validate a protection update before applying it.  This mirrors
    /// [`Self::validate_unmap`] and is optional for legacy backends.
    fn validate_protect(
        &self,
        _start: Self::Addr,
        _size: usize,
        _new_flags: Self::Flags,
        _page_table: &Self::PageTable,
    ) -> bool {
        true
    }

    /// What to do when changing access flags.
    fn protect(
        &self,
        start: Self::Addr,
        size: usize,
        new_flags: Self::Flags,
        context: &mut Self::MutationContext,
        page_table: &mut Self::PageTable,
    ) -> bool;

    /// Splits the backend into two backends at the given alignment difference.
    fn split(&mut self, align_diff: usize) -> Option<Self>;

    /// Shrinks the backend from the left by the given size.
    ///
    /// The backend start address is increased by `shrink_size`.
    fn shrink_left(&mut self, _shrink_size: usize) -> bool {
        true
    }

    /// Shrinks the backend from the right by the given size.
    ///
    /// The backend end address is decreased by `shrink_size`.
    fn shrink_right(&mut self, _shrink_size: usize) -> bool {
        true
    }
}