class PageMap

Defined at line 58 of file ../../zircon/kernel/lib/page-map/include/lib/page-map.h

PageMap provides safe and efficient kernel access to objects within VMOs that are logically owned

by usermode. PageMap automatically handles the mapping, committing, and pinning of the

underlying pages.

There are limitations on the kinds of objects that may be accessed via PageMap. They:

- must be trivially copyable, have standard layout, no implicit padding, etc.

- must not span page boundaries

- must have an alignment requirement of less than or equal to one page

- must be naturally aligned within the VMO

An object, or a field of an object, may be read/written using an Accessor instance (see

|MakeAccessor|). An Accessor provides access to a single object, at a given offset within a VMO.

The offset, together with the VMO's address in memory identify a page, allowing PageMap to

internally ref-count mappings so that all Accessor instances for the same VMO and offset will

reference a single mapping. See also |Entry::Key|.

Accessor is designed to avoid TOCTOU hazards by providing Read/Write methods for access rather

than a pointer.

Instances of PageMap are safe for concurrent use (thread-safe).

TODO(maniscalco): To save memory, explore using the existing physmap mapping instead of creating

a new one for each Entry.

TODO(maniscalco): Once it's available, use the btree instead of a WAVL tree for storing Entry's

Public Methods

void PageMap ()

Defined at line 60 of file ../../zircon/kernel/lib/page-map/include/lib/page-map.h

PageMap & Get ()

Returns a reference to the global PageMap.

Defined at line 91 of file ../../zircon/kernel/lib/page-map/include/lib/page-map.h

template <typename Object>

zx::result<Accessor<Object>> MakeAccessor (fbl::RefPtr<VmObjectPaged> vmo, size_t object_offset_in_vmo)

Constructs an Accessor for the object at |object_offset_in_vmo| in |vmo|.

Maps, commits, pins as necessary.

Accessors act as ref-counted pointers for the underlying VMO and mapping. Two Accessors for

the same offset in the same VMO will result in only one mapping. When the last Accessor for a

given page is destroyed, the underlying mapping, and possibly its VMO, will be destroyed. To

avoid unnecessary lock coupling, do not allow an Accessor to be destroyed while holding another

lock.

For the purposes of mapping reuse, VMO "sameness" is determined by the VMO's address in

memory (i.e. |vmo.get()|).

The object must have an alignment requirements of one page or less, and must be naturally

aligned within the VMO.

The object may not straddle a page boundary.

On success, returns a valid Accessor.

Returns ZX_ERR_INVALID_ARGS if the object straddles a page boundary or the object is not

properly aligned.

Returns ZX_ERR_OUT_OF_RANGE if the provided offset triggers arithmetic overflow.

Defined at line 128 of file ../../zircon/kernel/lib/page-map/include/lib/page-map.h

class Entry