Struct VmaNew

pub struct VmaNew { /* private fields */ }

A configuration object for setting up a VMA in an f_ops->mmap() hook.

The f_ops->mmap() hook is called when a new VMA is being created, and the hook is able to configure the VMA in various ways to fit the driver that owns it. Using VmaNew indicates that you are allowed to perform operations on the VMA that can only be performed before the VMA is fully initialized.

Invariants

For the duration of ’a, the referenced vma must be undergoing initialization in an f_ops->mmap() hook.

Implementations

impl VmaNew

pub unsafe fn from_raw<'a>(vma: *mut vm_area_struct) -> &'a Self

Access a virtual memory area given a raw pointer.

Safety

Callers must ensure that vma is undergoing initial vma setup for the duration of ’a.

pub fn set_mixedmap(&self) -> &VmaMixedMap

Set the VM_MIXEDMAP flag on this vma.

This enables the vma to contain both struct page and pure PFN pages. Returns a reference that can be used to call vm_insert_page on the vma.

pub fn set_io(&self)

Set the VM_IO flag on this vma.

This is used for memory mapped IO and similar. The flag tells other parts of the kernel to avoid looking at the pages. For memory mapped IO this is useful as accesses to the pages could have side effects.

pub fn set_dontexpand(&self)

Set the VM_DONTEXPAND flag on this vma.

This prevents the vma from being expanded with mremap().

pub fn set_dontcopy(&self)

Set the VM_DONTCOPY flag on this vma.

This prevents the vma from being copied on fork. This option is only permanent if VM_IO is set.

pub fn set_dontdump(&self)

Set the VM_DONTDUMP flag on this vma.

This prevents the vma from being included in core dumps. This option is only permanent if VM_IO is set.

pub fn readable(&self) -> bool

Returns whether VM_READ is set.

This flag indicates whether userspace is mapping this vma as readable.

pub fn try_clear_mayread(&self) -> Result

Try to clear the VM_MAYREAD flag, failing if VM_READ is set.

This flag indicates whether userspace is allowed to make this vma readable with mprotect().

Note that this operation is irreversible. Once VM_MAYREAD has been cleared, it can never be set again.

pub fn writable(&self) -> bool

Returns whether VM_WRITE is set.

This flag indicates whether userspace is mapping this vma as writable.

pub fn try_clear_maywrite(&self) -> Result

Try to clear the VM_MAYWRITE flag, failing if VM_WRITE is set.

This flag indicates whether userspace is allowed to make this vma writable with mprotect().

Note that this operation is irreversible. Once VM_MAYWRITE has been cleared, it can never be set again.

pub fn executable(&self) -> bool

Returns whether VM_EXEC is set.

This flag indicates whether userspace is mapping this vma as executable.

pub fn try_clear_mayexec(&self) -> Result

Try to clear the VM_MAYEXEC flag, failing if VM_EXEC is set.

This flag indicates whether userspace is allowed to make this vma executable with mprotect().

Note that this operation is irreversible. Once VM_MAYEXEC has been cleared, it can never be set again.

Methods from Deref<Target = VmaRef>

pub fn as_ptr(&self) -> *mut vm_area_struct

Returns a raw pointer to this area.

pub fn mm(&self) -> &MmWithUser

Access the underlying mm_struct.

pub fn flags(&self) -> vm_flags_t

Returns the flags associated with the virtual memory area.

The possible flags are a combination of the constants in flags.

pub fn start(&self) -> usize

Returns the (inclusive) start address of the virtual memory area.

pub fn end(&self) -> usize

Returns the (exclusive) end address of the virtual memory area.

pub fn zap_page_range_single(&self, address: usize, size: usize)

Zap pages in the given page range.

This clears page table mappings for the range at the leaf level, leaving all other page tables intact, and freeing any memory referenced by the VMA in this range. That is, anonymous memory is completely freed, file-backed memory has its reference count on page cache folio’s dropped, any dirty data will still be written back to disk as usual.

It may seem odd that we clear at the leaf level, this is however a product of the page table structure used to map physical memory into a virtual address space - each virtual address actually consists of a bitmap of array indices into page tables, which form a hierarchical page table level structure.

As a result, each page table level maps a multiple of page table levels below, and thus span ever increasing ranges of pages. At the leaf or PTE level, we map the actual physical memory.

It is here where a zap operates, as it the only place we can be certain of clearing without impacting any other virtual mappings. It is an implementation detail as to whether the kernel goes further in freeing unused page tables, but for the purposes of this operation we must only assume that the leaf level is cleared.

pub fn as_mixedmap_vma(&self) -> Option<&VmaMixedMap>

If the VM_MIXEDMAP flag is set, returns a VmaMixedMap to this VMA, otherwise returns None.

This can be used to access methods that require VM_MIXEDMAP to be set.

Trait Implementations

impl Deref for VmaNew

type Target = VmaRef

The resulting type after dereferencing.

fn deref(&self) -> &VmaRef

Dereferences the value.