class Machine

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

register state for entering and leaving restricted mode.

Public Members

static const uint64_t kDefaultStackBytes

Public Methods

bool Initialize (uint64_t reserved_stack_size)

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.

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 79 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 79 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 87 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 116 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 127 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 192 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 202 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 178 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 169 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 133 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 92 of file ../../src/bringup/lib/restricted-machine/machine.cc

RegisterState * registers ()

Provides access to the register state without taking ownership.

Defined at line 174 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 177 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 186 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 192 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 205 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 214 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 216 of file ../../src/bringup/lib/restricted-machine/include/bringup/lib/restricted-machine/machine.h