Struct CursorMut 

pub struct CursorMut<'a> { /* private fields */ }

The cursor for modifying the mappings in guest physical memory space.

It exclusively owns a sub-tree of the page table, preventing others from reading or modifying the same sub-tree.

Implementations

impl<'a> CursorMut<'a>

pub fn query(&mut self) -> Result<(Range<Gpaddr>, Option<QueriedItem<'_>>)>

Queries the mapping at the current guest physical address.

This is the same as Cursor::query.

If the cursor is pointing to a valid guest physical address that is locked, it will return the guest physical address range, the borrowed backing frame, and its page properties.

pub fn find_next(&mut self, len: usize) -> Option<Gpaddr>

Moves the cursor forward to the next mapped guest physical address.

This is the same as Cursor::find_next.

pub fn jump(&mut self, gpa: Gpaddr) -> Result<()>

Jumps to the guest physical address.

This is the same as Cursor::jump.

Panics

This method panics if the address has bad alignment.

pub fn gpa(&self) -> Gpaddr

Gets the guest physical address of the current slot.

pub fn map(&mut self, frame: UFrame, prop: PageProperty)

Maps a frame into the current slot.

This method will bring the cursor to the next slot after the modification.

Panics

Panics if:

• the current guest physical address is already mapped;
• the current guest physical address is outside the cursor’s range.

pub fn protect_next( &mut self, len: usize, op: &mut impl FnMut(&mut PageFlags), ) -> Option<Range<Gpaddr>>

Applies the operation to the next slot of mapping within the range.

The range to be found in is the current guest physical address with the provided length.

The function stops and yields the actually protected range if it has actually protected a page, no matter if the following pages are also required to be protected.

It also makes the cursor moves forward to the next page after the protected one. If no mapped pages exist in the following range, the cursor will stop at the end of the range and return [None].

Cached translations are invalidated on the current CPU before returning, and asynchronously on remote CPUs. Use Self::sync_tlb_flush to wait for remote invalidations to complete.

Panics

Panics if:

• the length is longer than the remaining range of the cursor;
• the length is not page-aligned.

pub fn unmap(&mut self, len: usize) -> usize

Clears the mapping starting from the current slot, and returns the number of unmapped pages.

This method brings the cursor forward by at least len bytes in the guest physical address space, but not past the end of the cursor’s range.

Already-absent mappings encountered by the cursor will be skipped. It is valid to unmap a range that is not mapped.

This method issues and dispatches EPT invalidation for removed mappings. Cached translations are invalidated on the current CPU before returning, and asynchronously on remote CPUs. Removed frames are retained until invalidation completes on all CPUs. Use Self::sync_tlb_flush to wait for remote invalidations to complete. Using a large len avoids the overhead of multiple invalidations.

Panics

Panics if:

• the length is longer than the remaining range of the cursor;
• the length is not page-aligned.

pub fn sync_tlb_flush(&mut self)

Waits for this cursor’s previous EPT invalidations to complete on all CPUs.

This synchronizes invalidations issued by Self::unmap and Self::protect_next. Dropping the cursor does not wait for completion; removed frames are retained until invalidation completes regardless.

Panics

Panics if local IRQs are disabled.