zircon/vdso/restricted.fidl - fuchsia - Git at Google

 // 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/42077468): 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/42076957 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;
 };
	// 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/42077468): 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/42076957 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;
	};