blob: b1c092d73d88611095c7d5e5c5b5e19de286388b [file] [log] [blame]
// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library zx;
@transport("Syscall")
closed protocol Restricted {
/// ## Summary
///
/// Enter restricted mode
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls-next.h>
///
/// zx_status_t zx_restricted_enter(uint32_t options,
/// uintptr_t vector_table_ptr,
/// uintptr_t context);
/// ```
///
/// ## Description
///
/// Enters restricted mode from normal thread state. If successful, the current
/// thread will return to normal mode via an entry point passed in
/// *vector_table_ptr*.
///
/// *vector_table_ptr* must be within the current user address space.
/// *context* may be any value. It is used as a value to pass back to normal
/// mode when returning from restricted mode.
///
/// *options* is a bit vector that contains zero more of the following:
///
/// - **ZX_RESTRICTED_OPT_EXCEPTION_CHANNEL** indicates that any exceptions
/// encountered while in restricted mode should be delivered using exception
/// channels. If this option is not present then any exceptions not handled by a
/// process debugger will cause control to vector to `vector_table_ptr` in normal
/// mode with the *reason code* set to `ZX_RESTRICTED_REASON_EXCEPTION`.
///
/// Arguments to the function at *vector_table_ptr* are architecturally specific:
///
/// On x64, *context* is placed in *rdi* and a reason code is placed in *rsi*.
/// All other registers are currently undefined, including the stack pointer.
///
/// On arm64, *context* is placed in *x0* and a reason code is placed in *x1*.
/// All other registers are currently undefined, including the stack pointer.
///
/// On riscv64, *context* is placed in *a0* and a reason code is placed in *a1*.
/// All other registers are currently undefined, including the stack pointer.
///
/// The *reason code* specifies the reason that normal mode execution has resumed.
/// This *reason code* may be one of `ZX_RESTRICTED_REASON_SYSCALL`,
/// `ZX_RESTRICTED_REASON_EXCEPTION`.
///
/// ### Shared process
///
/// Processes created with the `ZX_PROCESS_SHARED` option, or via `zx_process_create_shared()`
/// have two distinct [address spaces]. One is shared between multiple processes, while the other
/// is restricted to the specific process. When a thread that is entering restrcited mode
/// belongs to such a process, the active address space for the thread is updated as follows:
///
/// - When entering restricted mode the active address space for the thread is set to the
/// restricted address space of the process.
/// - When exiting restricted mode the active address space for the thread is set to the
/// shared address space of the process.
///
/// ## Rights
///
/// None (currently)
///
/// ## Return value
///
/// No return value on success, since the current thread indirectly returns via
/// *vector_table_ptr*. In the event of failure, a negative error value is returned.
///
/// ## Errors
///
/// **ZX_ERR_INVALID_ARGS** *vector_table_ptr* is not a valid user address or *options*
/// is non-zero.
///
/// **ZX_ERR_BAD_STATE** restricted mode register state is invalid.
///
/// **ZX_ERR_NOT_SUPPORTED** `ZX_RESTRICTED_OPT_EXCEPTION_CHANNEL` is _not_ provided and
/// vectored exceptions are not implemented for the current architecture.
///
/// ## See also
///
/// - [`zx_restricted_bind_state()`]
/// - [`zx_restricted_unbind_state()`]
/// - [`zx_process_create_shared()`]
///
/// [`zx_restricted_bind_state()`]: restricted_bind_state.md
/// [`zx_restricted_unbind_state()`]: restricted_unbind_state.md
/// [`zx_process_create_shared()`]: process_create_shared.md
/// [address spaces]: /docs/concepts/memory/address_spaces.md
@next
// TODO(https://fxbug.dev/126791): This is not a blocking syscall in the
// normal sense of the word. We've annotated this as blocking so that we
// can use ZX_ERR_INTERNAL_INTR_RETRY and the vDSO retry logic. See
// https://fxbug.dev/126200 for details.
@blocking
strict Enter(struct {
options uint32;
vector_table_ptr uintptr64;
context uintptr64;
}) -> () error Status;
/// ## Summary
///
/// Create and bind a restricted state VMO to the current thread.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls-next.h>
///
/// zx_status_t zx_restricted_bind_state(uint32_t options, zx_handle_t* out_vmo);
/// ```
///
/// ## Description
///
/// Create a VMO to hold a `zx_restricted_state_t`. Bind the VMO to the current
/// thread so that subsequent calls to [`zx_restricted_enter()`] will use it to
/// restore/save the restricted mode state upon entering/leaving restricted mode.
///
/// While the returned VMO, `out_vmo`, is similar to one created by
/// [`zx_vmo_create()`], some operations are unsupported and may fail with an error.
/// For example, resizing and creating a child VMO are unsupported. Mapping,
/// unmapping, and reading/writing via [`zx_vmo_read()`]/[`zx_vmo_write()`] are
/// supported.
///
/// Only one restricted state VMO may be bound to a thread at a time. Attempting to
/// bind another one will replace the already bound VMO.
///
/// A bound VMO will be destroyed only after the last user handle is closed, the
/// last user mapping is removed, and one of the following occur:
///
/// - It is replaced via `zx_restricted_bind_state()`.
///
/// - It is explicitly removed via [`zx_restricted_unbind_state()`].
///
/// - The thread is destroyed.
///
/// Like any other VMO, once the VMO has been mapped it will be retained by its
/// mapping so the caller may close the handle and access the memory directly via
/// the mapping.
///
/// Upon entering restricted mode `zx_restricted_state_t` at offset 0 of the VMO
/// will be loaded and execution will resume accordingly. Upon leaving restricted
/// mode, the thread's restricted state will be saved at offset 0 of VMO.
///
/// *options* must be zero.
///
/// Note: If a handle to the newly created VMO cannot be returned because `out_vmo`
/// is an invalid pointer, the VMO may still be bound to the thread even when the
/// call returns **ZX_ERR_INVALID_ARGS**. A caller can recover from this state by
/// calling [`zx_restricted_unbind_state()`] or calling
/// [zx_restricted_bind_state()`] again with a valid `out_vmo`.
///
/// ## Rights
///
/// Caller's job policy must allow **ZX_POL_NEW_VMO**.
///
/// ## Errors
///
/// **ZX_ERR_INVALID_ARGS** *out_vmo* is an invalid pointer or NULL, or *options*
/// is any value other than 0.
///
/// **ZX_ERR_NO_MEMORY** Failure due to lack of memory.
/// There is no good way for userspace to handle this (unlikely) error.
/// In a future build this error will no longer occur.
///
/// ## See also
///
/// - [`zx_restricted_enter()`]
///
/// - [`zx_restricted_unbind_state()`]
///
/// [`zx_restricted_enter()`]: restricted_enter.md
/// [`zx_restricted_unbind_state()`]: restricted_unbind_state.md
/// [`zx_vmo_create()`]: vmo_create.md
/// [`zx_vmo_read()`]: vmo_read.md
/// [`zx_vmo_write()`]: vmo_write.md
@next
strict BindState(resource struct {
options uint32;
}) -> (resource struct {
out Handle:VMO;
}) error Status;
/// ## Summary
///
/// Unbind a restricted state VMO from the current thread.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls-next.h>
///
/// zx_status_t zx_restricted_unbind_state(uint32_t options);
/// ```
///
/// ## Description
///
/// Unbind any restricted state VMO that may be bound to the calling thread.
///
/// See also [`zx_restricted_bind_state`].
///
/// It is not an error to call unbind on a thread that has no bound VMO.
///
/// *options* must be zero.
///
/// ## Rights
///
/// None.
///
/// ## Errors
///
/// **ZX_ERR_INVALID_ARGS** *options* is any value other than 0.
///
/// ## See also
///
/// - [`zx_restricted_enter()`]
///
/// - [`zx_restricted_bind_state()`]
///
/// [`zx_restricted_enter()`]: restricted_enter.md
/// [`zx_restricted_bind_state()`]: restricted_bind_state.md
@next
strict UnbindState(resource struct {
options uint32;
}) -> () error Status;
/// ## Summary
///
/// Kick a thread out of restricted mode.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls-next.h>
///
/// zx_status_t zx_restricted_kick(zx_handle_t thread, uint32_t options);
/// ```
///
/// ## Description
///
/// Kicks a thread out of restricted mode if it is currently running in restricted
/// mode or saves a pending kick if it is not. If the target thread is running in
/// restricted mode, it will exit to normal mode through the entry point provided to
/// `zx_restricted_enter` with a reason code set to `ZX_RESTRICTED_REASON_KICK`.
/// Otherwise the next call to `zx_restricted_enter` will not enter restricted mode
/// and will instead dispatch to the provided entry point with reason
/// code `ZX_RESTRICTED_REASON_KICK`.
///
/// Multiple kicks on the same thread object are collapsed together. Thus if
/// multiple threads call `zx_restricted_kick` on the same target while it is
/// running or entering restricted mode, at least one but possibly multiple
/// `ZX_RESTRICTED_REASON_KICK` returns will be observed. The recommended way to use
/// this syscall is to first record a reason for kicking in a synchronized data
/// structure and then call `zx_restricted_kick`. The thread calling
/// `zx_restricted_enter` should consult this data structure whenever it observes
/// `ZX_RESTRICTED_REASON_KICK` and process any pending state before reentering
/// restricted mode.
///
/// *options* must be zero.
///
/// ## Rights
///
/// **ZX_RIGHT_MANAGE_THREAD** is required on *thread*.
///
/// ## Errors
///
/// **ZX_ERR_INVALID_ARGS** *options* is any value other than 0.
/// **ZX_ERR_WRONG_TYPE** *thread* is not a thread.
/// **ZX_ERR_ACCESS_DENIED** *thread* does not have ZX_RIGHT_MANAGE_THREAD.
/// **ZX_ERR_BAD_STATE** *thread* is dead.
@next
strict Kick(resource struct {
thread Handle:THREAD;
options uint32;
}) -> () error Status;
};