class ArchVmAspaceInterface

The Init* methods are used to initialize the ArchVmAspace. The method that should be used

is dependent on the type of address space being created.

`Init`: This is used to create a regular address space with no special features. In

architectures that do not support unified address spaces, it is also used to create

shared and restricted address spaces. However, when unified address spaces are

supported, the shared and restricted address spaces should be created with `InitShared`

and `InitRestricted`.

`InitShared`: This is used to create a shared address space, whose contents can be

accessed from multiple unified address spaces. These address spaces have a statically

initialized top level page.

`InitRestricted`: This is used to create a restricted address space, whose contents can be

accessed from a single unified address space.

`InitUnified`: This is used to create a unified address space. This type of address space

owns no mappings of its own; rather, it is composed of a shared address space and a

restricted address space. As a result, it expects `InitShared` to have been called

on the shared address space, and expects `InitRestricted` to have been called on the

restricted address space.

This method puts the instance into read-only mode and asserts that it contains no mappings.

Note, this method may be a no-op on some architectures. See https://fxbug.dev/42159319.

It is an error to call this method on an instance that contains mappings. Once called,

subsequent operations that modify the page table will trigger a panic.

The purpose of this method is to help enforce lifecycle and state transitions of VmAspace and

ArchVmAspaceInterface.

Destroy expects the aspace to be fully unmapped, as any mapped regions indicate incomplete

cleanup at the higher layers. Note that this does not apply to unified aspaces, which may

still contain some mappings when Destroy() is called.

It is safe to call Destroy even if Init, InitShared, InitRestricted, or InitUnified failed.

Once destroy has been called it is a user error to call any of the other methods on the aspace,

unless specifically stated otherwise, and doing so may cause a panic.

main methods

Map a physically contiguous region into the virtual address space. This is allowed to use any

page size the architecture allows given the from the input parameters.

Returns whether or not an unmap might need to enlarge an operation for reasons other than being

out of memory. If this returns true, then unmapping a partial large page will fail always

require an enlarged operation.

Change the page protections on the given virtual address range

May return ZX_ERR_NO_MEMORY if the operation requires splitting

a large page and the next level page table allocation fails. In

this case, mappings in the input range may be a mix of the old and

new flags.

ArchUnmapOptions controls whether the a larger range than requested is permitted to experience

a temporary permissions change. A temporary change may be required if a break-before-make style

unmap -> remap of the large page is required.

Walks the given range of pages and for any pages that are mapped and have their access bit set

* Tells the page queues it has been accessed via PageQueues::MarkAccessed

* Potentially removes the accessed flag.

* Potentially frees unaccessed page tables.

Marks any pages in the given virtual address range as being accessed.

Returns whether or not this aspace might have additional accessed information since the last

time this method was called with clear=true. If this returns |false| then, modulo races,

HarvestAccessed is defined to not find any set bits and not call PageQueues::MarkAccessed.

This is intended for use by the harvester to avoid scanning for any accessed or dirty bits if

the aspace has not been accessed at all.

Note that restricted and shared ArchVmAspace's will report that they have been accessed if an

associated unified ArchVmAspace has been accessed. However, the reverse is not true; the

unified ArchVmAspace will not return true if the associated shared/restricted aspaces have been

accessed.

The |clear| flag controls whether the aspace having been accessed should be cleared or not. Not

clearing makes this function const and not modify any state.

Physical address of the backing data structure used for translation.

This should be treated as an opaque value outside of

architecture-specific components.

Map the given array of pages into the virtual address space starting at

|vaddr|, in the order they appear in |phys|.

If any address in the range [vaddr, vaddr + count * kPageSize) is already

mapped when this is called, |existing_action| controls the behavior used:

- |Skip| - Skip updating any existing mappings.

- |Error| - Existing mappings result in a ZX_ERR_ALREADY_EXISTS error.

- |Upgrade| - Upgrade any existing mappings, meaning a read-only mapping

can be converted to read-write, or the mapping can have its

paddr changed.

On error none of the provided pages will be mapped. In the case of |Upgrade| the state of any

previous mappings is undefined, and could either still be present or be unmapped.

Options for unmapping the given virtual address range.

ArchUnmapOptions::Enlarge controls whether the unmap region can be extended to be larger, or if

only the exact region may be unmapped. The unmap region might be extended, even if only

temporarily, if large pages need to be split.

ArchUnmapOptions::Harvest requests that the accessed bit be harvested, and the page queues

updated.

For HarvestAccessed Terminal and non-terminal get processed based on the following two

controls.