class VmMapping

Convenience wrapper for vmo()->DecommitRange() with the necessary

offset modification and locking.

Map in pages from the underlying vm object, optionally committing pages as it goes.

|ignore_existing| controls whether existing hardware mappings in the specified range should be

ignored or treated as an error. |ignore_existing| should only be set to true for user mappings

where populating mappings may already be racy with multiple threads, and where we are already

tolerant of mappings being arbitrarily created and destroyed.

Unmap any pages that map the passed in vmo range from the arch aspace.

May not intersect with this range.

If |only_has_zero_pages| is true then the caller is asserting that it knows that any mappings

in the region will only be for the shared zero page.

Removes any writeable mappings for the passed in vmo range from the arch aspace.

May fall back to unmapping pages from the arch aspace if necessary.

Checks if this is a kernel mapping within the given VMO range, which would be an error to be

unpinning.

Accessors for VMO-mapping state

These can be read under either lock (both locks being held for writing), so we provide two

different accessors, one for each lock.

Intended to be used from VmEnumerator callbacks where the aspace_->lock() will be held.

Unlocked convenience wrapper of UnmapLocked for testing.

Unlocked convenience wrapper of ProtectLocked for testing.

|assert_object_lock| exists to satisfy clang capability analysis since there are circumstances

when the object_->lock() is actually being held, but it was not acquired by dereferencing

object_. In this scenario we need to explain to the analysis that the lock held is actually the

same as object_->lock(), and even though we otherwise have no intention of using object_, the

only way to do this is to notionally dereferencing object_ to compare the lock.

Since this is asserting that the lock is held, and not just returning a reference to the lock,

this method is logically correct since object_ itself is only modified if object_->lock() is

held.

Page fault in an address within the mapping. The requested address must be paged aligned. If

|additional_pages| is non-zero, then up to that many additional pages may be resolved using the

same |pf_flags|. It is not an error for the |additional_pages| to span beyond the mapping or

underlying VMO, although the range will get truncated internally. As such only the page

containing va is required to be resolved, and this method may return ZX_OK if any number,

including zero, of the additional pages are resolved.

|object| is required to be the value of object_ with the requirement that if the aspace lock()

is not held over the call to this function, then the caller is required to ensure that |object|

will remain alive for the duration of the call.

As the |additional_pages| are resolved with the same |pf_flags| they may trigger copy-on-write

or other allocations in the underlying VMO.

If this returns ZX_ERR_SHOULD_WAIT, then the caller should wait on |page_request|

and try again. In addition to a status this returns how many pages got mapped in.

This may return ZX_ERR_UNAVAILABLE if the aspace lock() is not held and means that the mapping

was destroyed before the page fault could be handled.

If ZX_OK is returned then the number of pages mapped in is guaranteed to be >0.

If |additional_pages| was non-zero, then the maximum number of pages that will be mapped is

|additional_pages + 1|. Otherwise the maximum number of pages that will be mapped is

kPageFaultMaxOptimisticPages.

Enumerates any different protection ranges that exist inside this mapping. The virtual range

specified by range_base and range_size must be within this mappings base_ and size_. The

provided callback is called in virtual address order for each protection type. ZX_ERR_NEXT

and ZX_ERR_STOP can be used to control iteration, with any other status becoming the return

value of this method.

WAVL tree key function

For use in WAVL tree code only.

Convenience wrapper around PageFault that can be called with the aspace lock held and will

never return ZX_ERR_UNAVAILABLE.

Marks this mapping as being a candidate for merging, and will immediately attempt to merge with

any neighboring mappings. Making a mapping mergeable essentially indicates that you will no

longer use this specific VmMapping instance to refer to the referenced region, and will access

the region via the parent vmar in the future, and so the region merely needs to remain valid

through some VmMapping.

For this the function requires you to hand in your last remaining refptr to the mapping.

TODO(https://fxbug.dev/42106188): Informs the mapping that a write is going to be performed to

the backing VMO, even if the VMO is not writable. This gives the mapping an opportunity to

create a private clone of the VMO if necessary and use that to back a new mapping instead,

providing a way to 'safely' perform the write. On success a RefPtr is returned either to the

current mapping, or to a new mapping if one was created. If a new mapping was created then this

mapping is no longer valid.