class VmarLoader
Defined at line 33 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
This is the base class for LocalVmarLoader and RemoteVmarLoader, below.
All versions have mostly the same API. The protected Load method here has
the same signature as the public Load methods in the derived classes, so
the one API comment on Load here applies to those public methods.
This object encapsulates the work needed to load an object into a VMAR
based on an elfldltl::LoadInfo struct (see load.h) previously populated
from program headers. The Load method does the loading and initializes
the VmarLoader object's state. If Load fails, then the object should be
destroyed without calling other methods.
Public Methods
void VmarLoader ()When default-constructed, only the zx::vmar signature of Load can be used.
The default-constructed object can be assigned to another that has a
parent VMAR handle.
Defined at line 123 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
void VmarLoader (const zx::vmar & vmar)Defined at line 125 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
void VmarLoader (VmarLoader && other)Defined at line 127 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
VmarLoader & operator= (VmarLoader && other)Defined at line 129 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
void ~VmarLoader ()Defined at line 131 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
size_t page_size ()Defined at line 137 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
template <class Diagnostics, class LoadInfo>bool Allocate (Diagnostics & diag, const LoadInfo & load_info, std::optional<size_t> vmar_offset)This is called implicitly by Load if not explicitly called before Load.
Allocate a child VMAR from the containing VMAR for the whole load image.
Only the vaddr_size() and vaddr_start() from the LoadInfo are used here.
The kernel places it using ASLR within the parent VMAR provided at
construction, unless the optional argument sets the offset from the base
of that parent VMAR.
Defined at line 146 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
template <class LoadInfo>size_t VmarOffsetForLoadBias (zx_vaddr_t vmar_base, const LoadInfo & load_info, zx_vaddr_t load_bias)Given the base address of some parent VMAR, LoadInfo of an image to be
passed to Allocate, and the desired exact load bias, this yields the
value to pass for Allocate's optional argument. For example, if another
VmarLoader object has been used to load this image before, then passing
this the .load_bias() value will give the Allocate argument to ensure
that Load replicates the previous load layout exactly in a new process.
Defined at line 163 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
void Place (zx::vmar load_image_vmar, zx_vaddr_t load_bias)This installs a pre-allocated VMAR for the image that will be passed to
Load(). The VMAR must be large enough for the .vaddr_size() of the
LoadInfo passed to Load(). This takes ownership of the VMAR handle and
of the VMAR itself--the VMAR will be destroyed if this object is
destroyed before Commit() is called. The load bias must match the
difference between the base of the VMAR and .vaddr_start().
Defined at line 174 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
zx_vaddr_t load_bias ()After Allocate() or Place() and/or Load(), this is the bias added to the
given LoadInfo::vaddr_start() to find the runtime load address.
Defined at line 183 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
template <class Region>Relro Commit (const Region & relro_bounds)Commit is used to keep the mapping created by Load around even after the
VmarLoader object is destroyed. This method must be the last thing
called on the object if it is used, hence it can only be called with
`auto relro = std::move(loader).Commit(relro_bounds);`. If Commit() is
not called, then loading is aborted by destroying the VMAR when the
VmarLoader object is destroyed. Commit() returns the Relro object (see
above) that holds the VMAR handle allowing it to change page protections
of the load image.
Defined at line 194 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
Protected Methods
template <PartialPagePolicy PartialPage, class Diagnostics, class LoadInfo>bool Load (Diagnostics & diag, const LoadInfo & load_info, zx::unowned_vmo vmo)This loads the segments according to the elfldltl::LoadInfo
<
...>
instructions, mapping contents from the given VMO handle. It's the real
initializer for the object, and other methods can only be used after it
returns success (true). If it fails (returns false), the Diagnostics
object gets calls with the error details, and the VmarLoader object should
be destroyed promptly.
After Load() returns, the caller must assume that the containing VMAR
passed to the constructor may have new mappings whether the call succeeded
or not. Any mappings made are cleared out by destruction of the VmarLoader
object unless Commit() is called, see below.
Defined at line 222 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h
Enumerations
enum PartialPagePolicy| Name | Value |
|---|---|
| kProhibited | 0 |
| kCopyInProcess | 1 |
| kZeroInVmo | 2 |
This encapsulates the main differences between the Load methods of the
derived classes. Each derived class's Load method just calls a different
VmarLoader::Load
<Policy
> instantiaton. The PartialPagePolicy applies
specifically to LoadInfo::DataWithZeroFillSegment segments where the
segment's memsz > filesz and its vaddr + filesz is not page-aligned.
Defined at line 204 of file ../../src/lib/elfldltl/include/lib/elfldltl/vmar-loader.h