class RemoteDynamicLinker

ld::RemoteDynamicLinker represents a single remote dynamic linking session.

It may or may not be the first or only dynamic linking session performed on

the same process. Each dynamic linking session defines its own symbolic

dynamic linking domain and has its own passive ABI (stub dynamic linker).

The second optional template parameter can select the "zygote mode"

implementation. This is used by the

<lib

/ld/remote-zygote.h> API, which

provides the ld::RemoteZygote::Linker alias. The zygote-mode linker is used

in the same ways as the plain ld::RemoteDynamicLinker described here.

Before creating an ld::RemoteDynamicLinker, the ld::RemoteAbiStub must be

provided (see

<lib

/ld/remote-abi-stub.h>). Only a single ld::RemoteAbiStub

is needed to reuse the same stub dynamic linker binary across many dynamic

linking sessions. The ld::RemoteAbiStub can be provided in a constructor

argument, or injected with the set_abi_stub method after default

construction; it must be set before Init is called.

The dynamic linking session proceeds in these phases, with one method each:

* `Init()` starts the session by finding and decoding all the modules. This

starts with root modules (such as a main executable), and acquires their

transitive DT_NEEDED dependencies via a callback function. Additional

"implicit" modules may be specified to Init, such as a vDSO: these are

linked in even if they are not referenced by any DT_NEEDED dependency;

they always appear in the passive ABI, and if unreferenced will be last in

the list and have `.symbols_visible = false`.

Implicit modules serve multiple purposes. One is just to satisfy any

DT_NEEDED dependencies for them--but that could just as well be handled by

giving the callback function special-case logic for certain names. What's

unique about implicit modules is that they will be there even if they are

not referenced by any DT_NEEDED entry. The use cases are things that are

going to be in the address space anyway for some reason other than use of

their symbolic ABI via dynamic linking.

One kind reason something is in the address space without its symbolic ABI

being used is that its code and/or data addresses are part of a direct ABI

used in some other way. An example of this is the stub dynamic linker

(and likewise, the traditional in-process startup dynamic linker

implementing similar logic case): it contains runtime entry points used

implicitly by certain kinds of TLS accesses, so dynamic linking may

resolve certain relocations using addresses in this implicit shared

library, even though nothing refers to its DT_SONAME, nor to any symbol it

defines. Another example is a vDSO: the process startup ABI includes

passing pointers into the vDSO image in various ways, so programs that

don't have a DT_NEEDED dependency on the vDSO anywhere might still have

code that follows those pointers and needs its code or data to be intact.

Another reason something is preemptively put into the address space is to

make sure its symbolic ABI will be available at runtime to things that use

it opportunistically or in special ways rather than via normal dynamic

linking dependencies. When a module with `.symbols_visible = false` on

the list is also what it looks like when a module was added via `dlopen`

without using the `RTLD_GLOBAL` flag: a later attempt to `dlopen` that

name (or something else that transitively reaches a DT_NEEDED for that

same name) will find the module already loaded, and not try to load it

afresh. Finally, it's important that every module that is present in the

address space for whatever reason be represented in the passive ABI of any

dynamic linking domain that might interact with it. For example, unwinder

implemnentations will consult this module list (via the `dl_iterate_phdr`

API) to map any PC they come across to a module and find its unwinding

metadata. Things go awry if a PC does not lie in a known module.

* `Allocate()` sets the load address for each module using zx_vmar_allocate.

Each module gets a VMAR to reserve its part of the address space, and the

system call chooses a random available address for it (ASLR). This is the

step that binds the dynamic linking session to a particular address layout

and set of relocation results, which depend on all the addresses. The

session is now appropriate only for a single particular process, or a

single zygote that will spawn identical processes. This is the first

point at which there is any need for a Zircon process to actually exist.

Creating the process and ultimately launching it are outside the scope of

this API. The call to Allocate() must supply a zx::unowned_vmar where

zx::vmar::allocate() calls will be made to place each module. That can be

the root VMAR of a process, or a smaller VMAR. It must be large enough to

fit all the module images (including their .bss space beyond the size of

each ELF file image), and must permit the necessary mapping operations

(read, write, and execute, usually). The absolute addresses for any

`Preplaced()` (`InitModule::WithLoadBias`) uses and their image sizes must

lie within this VMAR.

* `Relocate()` fills in all the segment data that will need to be mapped in.

That is, it performs relocation on all modules and completes the passive

ABI data in the stub dynamic linker module. When the Diagnostics object

passed to `Init()` used a policy of reporting multiple errors before

bailing out, then `Init()` returned "successfully" even if there were

errors reported such as an invalid ELF file or a `get_dep` callback that

couldn't find the file. It may be appropriate to check the Diagnostics

object's error count and bail out before attempting relocation. It's also

safe to have the policy of attempting relocation despite past errors in

the Init phase. Any modules not decoded with sufficient success to safely

attempt relocation will be skipped. Relocating the remaining modules may

produce many additional errors due to partially-decoded or corrupt

metadata or undefined symbols that would have come from missing or

corrupted files. Such additional logging of e.g. undefined symbols may be

deemed useful, or not. It is highly discouraged to proceed past the

Relocate phase on to additional calls if there were any errors reported

during or before the Relocate phase. There is likely little benefit in

doing the address space layout or loading work to report additional error

details, and actually launching the process could be disastrous.

* `Load()` loads all the segments finalized by `Relocate()` into the VMARs

created by `Allocate()`. Since the VMARs have already been created and

the VMOs of segment contents already completed, nothing can usually go

wrong here except for resource exhaustion in creating mappings new VMOs

(either zero-fill or copy-on-write copies of relocated segments). If

anything does go wrong, the process address space may be left in an

indeterminate state until the ld::RemoteDynamicLinker object is destroyed.

* `Commit()` finally ensures that the VMARs created and mappings made can't

be changed or destroyed. If Commit() is not called, then all the VMARs

will be destroyed when the ld::RuntimeDynamicLinker object is destroyed.

After Commit() the object is only available for examining what was done.

The VMAR handles are no longer available and the VmarLoader objects would

need to be reinitialized to be used again. The segment VMO handles are

still available, but when not in zygote mode they are in use by process

mappings and must not be touched. In zygote mode, the relocated segment

VMOs will be made read-only and then reused (directly for RELRO mappings or

via copy-on-write copies) to load additional as-relocated process images.

Various other methods are provided for interrogating the list of modules and

accessing the dynamic linker stub module and the ld::RemoteAbi object.