class VmObject
Defined at line 250 of file ../../zircon/kernel/vm/include/vm/vm_object.h
The base vm object that holds a range of bytes of data
Can be created without mapping and used as a container of data, or mappable
into an address space via VmAddressRegion::CreateVmMapping
Protected Members
Canary canary_const uint32_t options_uint32_t cache_policy_WAVLTree mapping_list_DoublyLinkedList children_list_RelaxedAtomic user_id_uint32_t mapping_list_len_uint32_t children_list_len_Name name_Public Methods
Lock<CriticalMutex> * lock ()Lock<CriticalMutex> & lock_ref ()uint64_t size_locked ()zx_status_t PrefetchRange (uint64_t offset, uint64_t len)Fetches content in the given range of the object. This should operate logically equivalent to
reading such that future reads are quicker.
May block on user pager requests and must be called without locks held.
zx_status_t CommitRangePinned (uint64_t offset, uint64_t len, bool write)find physical pages to back the range of the object and pin them.
|len| must be non-zero. |write| indicates whether the range is being pinned for a write or a
read.
May block on user pager requests and must be called without locks held.
void Unpin (uint64_t offset, uint64_t len)Unpin the given range of the vmo. This asserts if it tries to unpin a
page that is already not pinned (do not expose this function to
usermode).
bool DebugIsRangePinned (uint64_t offset, uint64_t len)Checks if all pages in the provided range are pinned.
This is only intended to be used for debugging checks.
void SetUserStreamSize (fbl::RefPtr<StreamSizeManager> ssm)Provides the VMO with a user defined queryable byte aligned size. This provided size can then
be referenced in other operations, but otherwise has no effect. The VMO will never read or act
on this value unless instructed by user operations, and it is therefore the responsibility of
the user to ensure any synchronization of the reported value with the operation being
requested.
void SetChildObserver (VmObjectChildObserver * child_observer)The associated VmObjectDispatcher will set an observer to notify user mode.
Defined at line 155 of file ../../zircon/kernel/vm/vm_object.cc
void get_name (char * out_name, size_t len)Returns a null-terminated name, or the empty string if set_name() has not
been called.
Defined at line 62 of file ../../zircon/kernel/vm/vm_object.cc
zx_status_t set_name (const char * name, size_t len)Sets the name of the object. May truncate internally. |len| is the size
of the buffer pointed to by |name|.
Defined at line 67 of file ../../zircon/kernel/vm/vm_object.cc
uint64_t user_id ()Returns a user ID associated with this VMO, or zero.
Used to hold a zircon koid for Dispatcher-wrapped VMOs.
Defined at line 78 of file ../../zircon/kernel/vm/vm_object.cc
uint64_t parent_user_id ()Returns the parent's user_id() if this VMO has a parent,
otherwise returns zero.
void set_user_id (uint64_t user_id)Sets the value returned by |user_id()|. May only be called once.
Defined at line 72 of file ../../zircon/kernel/vm/vm_object.cc
void Dump (uint depth, bool verbose)zx_status_t SetMappingCachePolicy (uint32_t cache_policy)ChildType child_type ()zx_status_t GetPage (uint64_t offset, uint pf_flags, list_node * alloc_list, MultiPageRequest * page_request, vm_page_t ** page, paddr_t * pa)Get a pointer to the page structure and/or physical address at the specified offset.
valid flags are VMM_PF_FLAG_*.
|page_request| must be non-null if any flags in VMM_PF_FLAG_FAULT_MASK are set, unless
the caller knows that the vm object is not paged.
Returns ZX_ERR_SHOULD_WAIT if the caller should try again after waiting on the
PageRequest.
Returns ZX_ERR_NEXT if |page_request| supports batching and the current request
can be batched. The caller should continue to make successive GetPage requests
until this returns ZX_ERR_SHOULD_WAIT. If the caller runs out of requests, it
should finalize the request with PageSource::FinalizeRequest.
zx_status_t GetPageBlocking (uint64_t offset, uint pf_flags, list_node * alloc_list, vm_page_t ** page, paddr_t * pa)Helper variant of GetPage that will retry the operation after waiting on a PageRequest if
required.
Must not be called with any locks held.
Defined at line 237 of file ../../zircon/kernel/vm/vm_object.cc
void AddMappingLocked (VmMapping * r)Defined at line 83 of file ../../zircon/kernel/vm/vm_object.cc
void RemoveMappingLocked (VmMapping * r)Defined at line 89 of file ../../zircon/kernel/vm/vm_object.cc
uint32_t num_mappings ()Defined at line 96 of file ../../zircon/kernel/vm/vm_object.cc
bool IsMappedByUser ()Returns true if this VMO is mapped into any VmAspace whose is_user()
returns true.
Defined at line 102 of file ../../zircon/kernel/vm/vm_object.cc
uint32_t share_count ()Returns an estimate of the number of unique VmAspaces that this object
is mapped into.
Defined at line 109 of file ../../zircon/kernel/vm/vm_object.cc
bool AddChildLocked (VmObject * child)Adds a child to this VMO and returns true if the dispatcher which matches
user_id should be notified about the first child being added.
Defined at line 160 of file ../../zircon/kernel/vm/vm_object.cc
bool AddChild (VmObject * child)Defined at line 168 of file ../../zircon/kernel/vm/vm_object.cc
void RemoveChild (VmObject * child, Guard<CriticalMutex>::Adoptable adopt)Removes the child |child| from this VMO and notifies the child observer if the new child count
is zero. The |guard| must be this VMO's lock.
Defined at line 180 of file ../../zircon/kernel/vm/vm_object.cc
void DropChildLocked (VmObject * c)Drops |c| from the child list without going through the full removal
process. ::RemoveChild is probably what you want here.
Defined at line 173 of file ../../zircon/kernel/vm/vm_object.cc
uint32_t num_children ()Defined at line 207 of file ../../zircon/kernel/vm/vm_object.cc
ktl::optional<ktl::pair<uint64_t, uint64_t>> GetMaximalMappedRange ()If this VMO has any mappings, return the maximal range spanning all the mappings.
Defined at line 256 of file ../../zircon/kernel/vm/vm_object.cc
void RangeChangeUpdateMappingsLocked (uint64_t offset, uint64_t len, RangeChangeOp op)Apply the specified operation to all mappings in the given range. The provided offset and len
must both be page aligned.
Defined at line 278 of file ../../zircon/kernel/vm/vm_object.cc
zx_status_t Resize (uint64_t size)public API
Defined at line 256 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint64_t size ()Defined at line 262 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint32_t create_options ()Defined at line 266 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_paged ()Returns true if the object is backed by RAM and this object can be cast to a VmObjectPaged, if
false this is a VmObjectPhysical.
Defined at line 270 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_contiguous ()Returns true if the object is backed by a contiguous range of physical
memory.
Defined at line 273 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_resizable ()Returns true if the object size can be changed.
Defined at line 275 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_discardable ()Returns true if the object's pages are discardable by the kernel.
Defined at line 277 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_user_pager_backed ()Returns true if the VMO was created via CreatePagerVmo().
Defined at line 279 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_dirty_tracked ()Returns true if the VMO's pages require dirty bit tracking.
Defined at line 281 of file ../../zircon/kernel/vm/include/vm/vm_object.h
void mark_modified_locked ()Marks the VMO as modified if the VMO tracks modified state (only supported for pager-backed
VMOs).
Defined at line 284 of file ../../zircon/kernel/vm/include/vm/vm_object.h
AttributionCounts GetAttributedMemoryInRange (uint64_t offset_bytes, uint64_t len_bytes)Returns the number of physical bytes currently attributed to a range of this VMO.
The range is `[offset_bytes, offset_bytes+len_bytes)`.
Defined at line 290 of file ../../zircon/kernel/vm/include/vm/vm_object.h
AttributionCounts GetAttributedMemoryInReferenceOwner ()Returns the number of physical bytes currently attributed to this VMO's parent when this VMO
is a reference.
Defined at line 297 of file ../../zircon/kernel/vm/include/vm/vm_object.h
AttributionCounts GetAttributedMemory ()Returns the number of physical bytes currently attributed to this VMO.
Defined at line 302 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t CommitRange (uint64_t offset, uint64_t len)find physical pages to back the range of the object
May block on user pager requests and must be called without locks held.
Defined at line 306 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t DecommitRange (uint64_t offset, uint64_t len)free a range of the vmo back to the default state
Defined at line 320 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t ZeroRange (uint64_t offset, uint64_t len)Zero a range of the VMO. May release physical pages in the process.
May block on user pager requests and must be called without locks held.
Defined at line 324 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t ZeroRangeUntracked (uint64_t offset, uint64_t len)Zero a range of the VMO and also untrack it from any kind of dirty tracking. For committed
pages, this means that they are released. And any kind of zero markers or intervals that are
inserted will not subscribe to dirty tracking.
Defined at line 329 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t TryLockRange (uint64_t offset, uint64_t len)Lock a range from being discarded by the kernel. Can fail if the range was already discarded.
Defined at line 343 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t LockRange (uint64_t offset, uint64_t len, zx_vmo_lock_state_t * lock_state_out)Lock a range from being discarded by the kernel. Guaranteed to succeed. |lock_state_out| is
populated with relevant information about the locked and discarded ranges.
Defined at line 347 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t UnlockRange (uint64_t offset, uint64_t len)Unlock a range, making it available for the kernel to discard. The range could have been locked
either by |TryLockRange| or |LockRange|.
Defined at line 354 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t Read (void * ptr, uint64_t offset, size_t len)read/write operators against kernel pointers only
May block on user pager requests and must be called without locks held.
Defined at line 359 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t Write (const void * ptr, uint64_t offset, size_t len)Defined at line 360 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t Lookup (uint64_t offset, uint64_t len, LookupFunction lookup_fn)Defined at line 374 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t LookupContiguous (uint64_t offset, uint64_t len, paddr_t * out_paddr)Attempts to lookup the given range in the VMO. If it exists and is physically contiguous
returns the paddr of the start of the range. The offset must be page aligned.
Ranges of length zero are considered invalid and will return ZX_ERR_INVALID_ARGS.
A null |paddr| may be passed to just check for contiguity.
Defined at line 382 of file ../../zircon/kernel/vm/include/vm/vm_object.h
ktl::pair<zx_status_t, size_t> ReadUser (user_out_ptr<char> ptr, uint64_t offset, size_t len, VmObjectReadWriteOptions options)read/write operators against user space pointers only
The number of bytes successfully processed is always returned, even upon error. This allows for
callers to still pass on this bytes transferred if a particular error was expected.
May block on user pager requests and must be called without locks held.
Bytes are guaranteed to be transferred in order from low to high offset.
Defined at line 394 of file ../../zircon/kernel/vm/include/vm/vm_object.h
ktl::pair<zx_status_t, size_t> WriteUser (user_in_ptr<const char> ptr, uint64_t offset, size_t len, VmObjectReadWriteOptions options, const OnWriteBytesTransferredCallback & on_bytes_transferred)Defined at line 404 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t TakePages (uint64_t offset, uint64_t len, VmPageSpliceList * pages)Removes the pages from this vmo in the range [offset, offset + len) and returns
them in pages. This vmo must be a paged vmo with no parent, and it cannot have any
pinned pages in the source range. |offset| and |len| must be page aligned.
Defined at line 413 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t SupplyPages (uint64_t offset, uint64_t len, VmPageSpliceList * pages, SupplyOptions options)Supplies this vmo with pages for the range [offset, offset + len). If this vmo
already has pages in the target range, the |options| field will dictate what happens:
If options is SupplyOptions::TransferData, the pages in the target range will be overwritten,
Otherwise, the corresponding pages in |pages| will be freed.
|offset| and |len| must be page aligned.
Defined at line 422 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t FailPageRequests (uint64_t offset, uint64_t len, zx_status_t error_status)Indicates that page requests in the range [offset, offset + len) could not be fulfilled.
|error_status| specifies the error encountered. |offset| and |len| must be page aligned.
Defined at line 429 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t DirtyPages (uint64_t offset, uint64_t len)Dirties pages in the vmo in the range [offset, offset + len).
Defined at line 434 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t EnumerateDirtyRanges (uint64_t offset, uint64_t len, DirtyRangeEnumerateFunction && dirty_range_fn)Enumerates dirty ranges in the range [offset, offset + len) in ascending order, updating any
relevant VMO internal state required to perform the enumeration, and calls |dirty_range_fn| on
each dirty range (spanning [range_offset, range_offset + range_len) where |range_is_zero|
indicates whether the range is all zeros). |dirty_range_fn| can return ZX_ERR_NEXT to continue
with the enumeration, ZX_ERR_STOP to terminate the enumeration successfully, and any other
error code to terminate the enumeration early with that error code.
Defined at line 444 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t QueryPagerVmoStats (bool reset, zx_pager_vmo_stats_t * stats)Query pager relevant VMO stats, e.g. whether the VMO has been modified. If |reset| is set to
true, the queried stats are reset as well, potentially affecting the queried state returned by
future calls to this function.
Defined at line 452 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t WritebackBegin (uint64_t offset, uint64_t len, bool is_zero_range)Indicates start of writeback for the range [offset, offset + len). Any Dirty pages in the range
are transitioned to AwaitingClean, in preparation for transition to Clean when the writeback is
done (See VmCowPages::DirtyState for details of these states). |offset| and |len| must be page
aligned. |is_zero_range| specifies whether the caller intends to write back the specified range
as zeros.
Defined at line 461 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t WritebackEnd (uint64_t offset, uint64_t len)Indicates end of writeback for the range [offset, offset + len). Any AwaitingClean pages in the
range are transitioned to Clean (See VmCowPages::DirtyState for details of these states).
|offset| and |len| must be page aligned.
Defined at line 468 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t HintRange (uint64_t offset, uint64_t len, EvictionHint hint)Hint how the specified range is intended to be used, so that the hint can be taken into
consideration when reclaiming pages under memory pressure (if applicable).
May block on user pager requests and must be called without locks held.
Defined at line 477 of file ../../zircon/kernel/vm/include/vm/vm_object.h
void CommitHighPriorityPages (uint64_t offset, uint64_t len)Performs any page commits necessary for a VMO with high memory priority over the given range.
This method is always safe to call as it will internally check the memory priority status and
skip if necessary, so the caller does not need to worry about races with the VMO no longer
being high priority.
As this may need to acquire the lock even to check the memory priority, if the caller knows
they have not caused this VMO to become high priority (i.e. they have not called
ChangeHighPriorityCountLocked with a positive value), then calling this should be skipped for
performance.
This method has no return value as it is entirely best effort and no part of its operation is
needed for correctness.
Defined at line 492 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool is_child_observer_valid ()Defined at line 506 of file ../../zircon/kernel/vm/include/vm/vm_object.h
size_t max_size ()Returns the maximum possible size of a VMO.
Defined at line 531 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint32_t DebugLookupDepth ()Returns the number of lookup steps that might be done by operations on this VMO. This would
typically be the depth of a parent chain and represent how many parents might need to be
traversed to find a page.
What this returns is imprecise and not well defined, and so is for debug / diagnostic usage
only.
Defined at line 540 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t CacheOp (uint64_t offset, uint64_t len, CacheOpType type)Defined at line 544 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint32_t GetMappingCachePolicyLocked ()Defined at line 548 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint32_t GetMappingCachePolicy ()Defined at line 549 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t CreateClone (Resizability resizable, SnapshotType type, uint64_t offset, uint64_t size, bool copy_name, fbl::RefPtr<VmObject> * child_vmo)create a copy-on-write clone vmo at the page-aligned offset and length
note: it's okay to start or extend past the size of the parent
Defined at line 557 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t CreateChildSlice (uint64_t offset, uint64_t size, bool copy_name, fbl::RefPtr<VmObject> * child_vmo)Defined at line 562 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t CreateChildReference (Resizability resizable, uint64_t offset, uint64_t size, bool copy_name, bool * first_child, fbl::RefPtr<VmObject> * child_vmo)TODO: use a zx::result return instead of multiple out parameters and be consistent with the
other Create* methods.
Defined at line 569 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint64_t HeapAllocationBytes ()Defined at line 581 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint64_t ReclamationEventCount ()Number of times pages have been evicted over the lifetime of this VMO. Evicted counts for any
decommit style event such as user pager eviction or zero page merging. One eviction event
could count for multiple pages being evicted, if those pages were evicted as a group.
Defined at line 586 of file ../../zircon/kernel/vm/include/vm/vm_object.h
uint32_t num_mappings_locked ()Defined at line 613 of file ../../zircon/kernel/vm/include/vm/vm_object.h
zx_status_t RoundSize (uint64_t size, uint64_t * out_size)Helper to round to the VMO size multiple (which is kPageSize) without overflowing.
Defined at line 639 of file ../../zircon/kernel/vm/include/vm/vm_object.h
template <typename T>zx_status_t ForEach (T func)Calls the provided |func(const VmObject
&
)| on every VMO in the system,
from oldest to newest. Stops if |func| returns an error, returning the
error value.
Defined at line 651 of file ../../zircon/kernel/vm/include/vm/vm_object.h
template <typename T>zx_status_t ForEachRef (T func)Same as ForEach but works with VmObject*.
Defined at line 664 of file ../../zircon/kernel/vm/include/vm/vm_object.h
void DetachSource ()Detaches the underlying page source, if present. Can be called multiple times.
Defined at line 679 of file ../../zircon/kernel/vm/include/vm/vm_object.h
ktl::optional<zx_koid_t> GetPageSourceKoid ()If this VMO has a backing page source, and that page source has a koid, then it is returned.
Otherwise returns a nullopt.
Defined at line 683 of file ../../zircon/kernel/vm/include/vm/vm_object.h
Protected Methods
void VmObject (uint32_t options)Defined at line 39 of file ../../zircon/kernel/vm/vm_object.cc
void ~VmObject ()private destructor, only called from refptr
Defined at line 41 of file ../../zircon/kernel/vm/vm_object.cc
void AddToGlobalList ()Defined at line 51 of file ../../zircon/kernel/vm/vm_object.cc
void RemoveFromGlobalList ()Defined at line 56 of file ../../zircon/kernel/vm/vm_object.cc
void CacheOpPhys (paddr_t pa, uint64_t length, CacheOpType op, ArchVmICacheConsistencyManager & cm)Performs the requested cache op against a physical address range. The requested physical range
must be accessible via the physmap.
Defined at line 214 of file ../../zircon/kernel/vm/vm_object.cc
void VmObject (const VmObject & )Defined at line 744 of file ../../zircon/kernel/vm/include/vm/vm_object.h
void VmObject (VmObject && )Defined at line 744 of file ../../zircon/kernel/vm/include/vm/vm_object.h
VmObject & operator= (const VmObject & )Defined at line 744 of file ../../zircon/kernel/vm/include/vm/vm_object.h
VmObject & operator= (VmObject && )Defined at line 744 of file ../../zircon/kernel/vm/include/vm/vm_object.h
bool InGlobalList ()Defined at line 748 of file ../../zircon/kernel/vm/include/vm/vm_object.h
Enumerations
enum EvictionHint| Name | Value |
|---|---|
| DontNeed | 0 |
| AlwaysNeed | 1 |
Defined at line 470 of file ../../zircon/kernel/vm/include/vm/vm_object.h
enum CacheOpType| Name | Value |
|---|---|
| Invalidate | 0 |
| Clean | 1 |
| CleanInvalidate | 2 |
| Sync | 3 |
perform a cache maintenance operation against the vmo.
Defined at line 543 of file ../../zircon/kernel/vm/include/vm/vm_object.h
enum ChildType| Name | Value |
|---|---|
| kNotChild | 0 |
| kCowClone | 1 |
| kSlice | 2 |
| kReference | 3 |
Extend this enum when new child types are supported with zx_vmo_create_child().
All SNAPSHOT* types are reported as kCowClone, because they all implement CoW semantics, albeit
in different ways to provide different guarantees.
Defined at line 578 of file ../../zircon/kernel/vm/include/vm/vm_object.h
enum RangeChangeOp| Name | Value |
|---|---|
| Unmap | 0 |
| UnmapZeroPage | 1 |
| UnmapAndHarvest | 2 |
| RemoveWrite | 3 |
| DebugUnpin | 4 |
Different operations that RangeChangeUpdate* can perform against any VmMappings that are found.
Defined at line 686 of file ../../zircon/kernel/vm/include/vm/vm_object.h
Records
Friends
class RefPtr