class Machine

Defined at line 37 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

A Machine represents a single instance of a restricted mode execution

environment. It is responsible for managing the thread, its stack, and the

Public Members

static const uint64_t kDefaultStackBytes

Public Methods

bool Initialize (uint64_t reserved_stack_size, zx_exception_report_t * exception_report)

Instantiates a new restricted mode machine in the supplied environment.

|reserved_stack_size| will be allocated for the stack along with a small

amount of memory for TLS usage.

|exception_report| when null, the exception report will be returned in the

mode state vmo. When non-null, an exception report generated while

executing in restricted mode will be copied here.

Defined at line 38 of file ../../src/bringup/lib/restricted-machine/machine.cc

void Machine (fbl::RefPtr<Environment> environment)

Defined at line 39 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

void ~Machine ()

Defined at line 40 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

void enable_fpu_registers (bool enable_fpu_registers)

Enables or disables the loading and saving of FPU registers on entry to

and exit from restricted mode.

Defined at line 80 of file ../../src/bringup/lib/restricted-machine/machine.cc

template <typename... Args>

zx::result<uint64_t> Call (const std::string_view & symbol, Args... vargs)

Calls the |symbol| in the machine's environment.

The function is identified by its symbol name. Up to 4 pointer arguments

can be passed.

If addressable memory differs between the caller and the restricted

machine environment, use Environment::MakeArgument

> to allocate

and construct arguments which may be passed safely into Call().

On success, a 64-bit value will be returned. For 32-bit environments, this

normally is the span of two registers.

If an error entering restricted mode occurs, it will be returned verbatim.

If the restricted mode call returns through an unexpected path, such as an

unexpected system call or exception, ZX_ERR_OUT_OF_RANGE is returned and

the reason code can be read with |last_reason()|.

Defined at line 84 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

std::vector<uint8_t> * FpuRegisters ()

Returns a pointer to the FPU register state.

The vector will be valid after a call to `enable_fpu_registers(true)`.

The vector must be exactly sized to RegisterState::kFpuBufferSize or

Enter() will not set or save the FPU registers.

Defined at line 88 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx::result<> LoadState ()

Loads the machine state from the restricted machine, including registers

and exception state.

This function is only useful when using the Enter*() calls.

Defined at line 147 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx::result<> CommitState ()

Commits the machine state to the restricted machine, which will determine

its register values on the next entry into restricted mode.

This function is only necessary when using the Enter() or Continue().

Defined at line 167 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx_status_t Continue ()

A wrapper around the restricted_enter() system call that uses the

arch-specific assembly.

This "continues" execution without loading or committing state, but it does

update the last_reason().

Defined at line 242 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx_status_t Kick (uint32_t options, std::optional<zx_handle_t> thread)

A wrapper around zx_restricted_kick() which kicks the current thread unless

another is provided.

Defined at line 252 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx::result<uint64_t> Enter ()

Enters restricted mode using the current register state.

Defined at line 228 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx::result<uint64_t> Thunk (uint64_t fn_address, uint64_t arg0, uint64_t arg1, uint64_t arg2, uint64_t arg3)

Attempts to execute code at |fn_address| with the given parameters packed

into an array for the Environment's thunk function to extract.

Defined at line 219 of file ../../src/bringup/lib/restricted-machine/machine.cc

zx::result<Environment::Allocation> ThunkPrepare (uint64_t fn_address, uint64_t arg0, uint64_t arg1, uint64_t arg2, uint64_t arg3)

Prepares the machine to execute at the thunk callsite on the next call to

Enter().

This allows users to perform sensitive register changes with minimal code

before restricted mode entry.

The result will contain the (unique_ptr) allocation which holds the

arguments for the call. When it goes out of scope, the memory will be

released.

Defined at line 173 of file ../../src/bringup/lib/restricted-machine/machine.cc

void LogState (std::optional<zx_restricted_reason_t> if_not_reason)

Logs the current register state.

If |if_not_reason| is provided, the state will only be logged if the last

exit reason is different.

Defined at line 93 of file ../../src/bringup/lib/restricted-machine/machine.cc

RegisterState * registers ()

Provides access to the register state without taking ownership.

Defined at line 180 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

zx_restricted_reason_t last_reason ()

Returns the reason for the last exit from restricted mode.

Defined at line 183 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

fbl::RefPtr<Environment> environment ()

Returns a ref-counted pointer to the Environment object.

Defined at line 192 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

Protected Methods

template <typename T>

zx::result<uint64_t> CollectArgPtr (const T target_obj)

Validates and extracts a pointer to a restricted mode accessible

allocation.

Defined at line 198 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

template <typename T>

zx::result<uint64_t> CollectArg (T target_obj)

Collects a pointer after validating its accessibility.

Defined at line 211 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

zx::result<> prepArgs (std::vector<uint64_t> * args)

Allocates addressable memory to store the function arguments and then

returns them in |args|.

Defined at line 220 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h

template <typename T, typename... Args>

zx::result<> prepArgs (std::vector<uint64_t> * args, T t, Args... vargs)

Defined at line 222 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h