zircon/vdso/job.fidl

// Copyright 2019 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 Job {
    /// ## Summary
    ///
    /// Create a new job.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_job_create(zx_handle_t parent_job,
    ///                           uint32_t options,
    ///                           zx_handle_t* out);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_job_create()` creates a new child [job object](/docs/reference/kernel_objects/job.md) given a
    /// parent job.
    ///
    /// Upon success a handle for the new job is returned.
    ///
    /// The kernel keeps track of and restricts the "height" of a job, which is its
    /// distance from the root job. It is illegal to create a job under a parent whose
    /// height exceeds an internal "max height" value. (It is, however, legal to create
    /// a process under such a job.)
    ///
    /// Job handles may be waited on (TODO(cpu): expand this)
    ///
    /// ## Rights
    ///
    /// *parent_job* must be of type **ZX_OBJ_TYPE_JOB** and have **ZX_RIGHT_MANAGE_JOB**.
    ///
    /// ## Return value
    ///
    /// `zx_job_create()` returns **ZX_OK** and a handle to the new job
    /// (via *out*) on success.  In the event of failure, a negative error value
    /// is returned.
    ///
    /// ## Errors
    ///
    /// **ZX_ERR_BAD_HANDLE**  *parent_job* is not a valid handle.
    ///
    /// **ZX_ERR_WRONG_TYPE**  *parent_job* is not a job handle.
    ///
    /// **ZX_ERR_INVALID_ARGS**  *options* is nonzero, or *out* is an invalid pointer.
    ///
    /// **ZX_ERR_ACCESS_DENIED**  *parent_job* does not have the **ZX_RIGHT_WRITE** or
    /// **ZX_RIGHT_MANAGE_JOB** right.
    ///
    /// **ZX_ERR_OUT_OF_RANGE**  The height of *parent_job* is too large to create a child job.
    ///
    /// **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.
    ///
    /// **ZX_ERR_BAD_STATE**  The parent job object is in the dead state.
    ///
    /// ## See also
    ///
    ///  - [`zx_object_get_property()`]
    ///  - [`zx_process_create()`]
    ///  - [`zx_task_kill()`]
    ///
    /// [`zx_object_get_property()`]: object_get_property.md
    /// [`zx_process_create()`]: process_create.md
    /// [`zx_task_kill()`]: task_kill.md
    strict Create(resource struct {
        parent_job Handle:JOB;
        options uint32;
    }) -> (resource struct {
        out Handle:JOB;
    }) error Status;

    /// ## Summary
    ///
    /// Set job security and resource policies.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_job_set_policy(zx_handle_t handle,
    ///                               uint32_t options,
    ///                               uint32_t topic,
    ///                               const void* policy,
    ///                               uint32_t policy_size);
    /// ```
    ///
    /// ## Description
    ///
    /// Sets one or more security and/or resource policies to an empty job. The job's
    /// effective policies is the combination of the parent's effective policies and
    /// the policies specified in *policy*. The effect in the case of conflict between
    /// the existing policies and the new policies is controlled by *options* values:
    ///
    /// + **ZX_JOB_POL_RELATIVE** : policy is applied for the conditions not specifically
    ///   overridden by the parent policy.
    /// + **ZX_JOB_POL_ABSOLUTE** : policy is applied for all conditions in *policy* or
    ///   the syscall fails.
    ///
    /// After this call succeeds any new child process or child job will have the new
    /// effective policy applied to it.
    ///
    /// *topic* indicates the *policy* format. Supported values are **ZX_JOB_POL_BASIC_V1**,
    /// **ZX_JOB_POL_BASIC_V2** and **ZX_JOB_POL_TIMER_SLACK**.
    ///
    /// ### **ZX_JOB_POL_BASIC_V2 and V1**
    ///
    /// A *topic* of **ZX_JOB_POL_BASIC_V2** indicates that *policy* is an array of *count*
    /// entries of:
    ///
    /// ```
    /// typedef struct zx_policy_basic {
    ///     uint32_t condition;
    ///     uint32_t action;
    ///     uint32_t flags;
    /// } zx_policy_basic_v2_t;
    ///
    /// ```
    ///
    /// A *topic* of **ZX_JOB_POL_BASIC_V1** indicates that *policy* is an array of *count*
    /// entries of:
    ///
    /// ```
    /// // Deprecated. Use zx_policy_basic_v2_t.
    /// typedef struct zx_policy_basic {
    ///     uint32_t condition;
    ///     uint32_t policy;
    /// } zx_policy_basic_v1_t;
    ///
    /// ```
    ///
    /// Where *condition* is one of
    ///
    /// + **ZX_POL_BAD_HANDLE** a process under this job is attempting to
    ///   issue a syscall with an invalid handle.  In this case,
    ///   **ZX_POL_ACTION_ALLOW** and **ZX_POL_ACTION_DENY** are equivalent:
    ///   if the syscall returns, it will always return the error
    ///   **ZX_ERR_BAD_HANDLE**.
    /// + **ZX_POL_WRONG_OBJECT** a process under this job is attempting to
    ///   issue a syscall with a handle that does not support such operation.
    /// + **ZX_POL_VMAR_WX** a process under this job is attempting to map an
    ///   address region with write-execute access.
    /// + **ZX_POL_NEW_VMO** a process under this job is attempting to create
    ///   a new vm object.
    /// + **ZX_POL_NEW_CHANNEL** a process under this job is attempting to create
    ///   a new channel.
    /// + **ZX_POL_NEW_EVENT** a process under this job is attempting to create
    ///   a new event.
    /// + **ZX_POL_NEW_EVENTPAIR** a process under this job is attempting to create
    ///   a new event pair.
    /// + **ZX_POL_NEW_PORT** a process under this job is attempting to create
    ///   a new port.
    /// + **ZX_POL_NEW_SOCKET** a process under this job is attempting to create
    ///   a new socket.
    /// + **ZX_POL_NEW_FIFO** a process under this job is attempting to create
    ///   a new fifo.
    /// + **ZX_POL_NEW_TIMER** a process under this job is attempting to create
    ///   a new timer.
    /// + **ZX_POL_NEW_PROCESS** a process under this job is attempting to create
    ///   a new process.
    /// + **ZX_POL_NEW_PROFILE** a process under this job is attempting to create
    ///   a new profile.
    /// + **ZX_POL_NEW_PAGER** a process under this job is attempting to create
    ///   a new VMO pager.
    /// + **ZX_POL_AMBIENT_MARK_VMO_EXEC** a process under this job is attempting
    ///   to use [`zx_vmo_replace_as_executable()`] with a **ZX_HANDLE_INVALID**
    ///   as the second argument rather than a valid **ZX_RSRC_KIND_SYSTEM** resource with base
    ///   **ZX_RSRC_SYSTEM_VMEX_BASE**.
    /// + **ZX_POL_NEW_ANY** is a special *condition* that stands for all of
    ///   the above **ZX_NEW** conditions such as **ZX_POL_NEW_VMO**,
    ///   **ZX_POL_NEW_CHANNEL**, **ZX_POL_NEW_EVENT**, **ZX_POL_NEW_EVENTPAIR**,
    ///   **ZX_POL_NEW_PORT**, **ZX_POL_NEW_SOCKET**, **ZX_POL_NEW_FIFO**,
    ///   and any future **ZX_NEW** policy. This will include any new
    ///   kernel objects that do not require a parent object for creation.
    /// + **ZX_POL_NEW_IOB** a process under this job is attempting to create
    ///   a new IOBuffer.
    ///
    /// Where *policy* for **ZX_JOB_POL_BASIC_V1** or *action* for **ZX_JOB_POL_BASIC_V2**
    /// is one of
    ///
    /// + **ZX_POL_ACTION_ALLOW**  allow *condition*.
    /// + **ZX_POL_ACTION_DENY**  prevent *condition*.
    /// + **ZX_POL_ACTION_ALLOW_EXCEPTION**  generate an exception via the debug port.
    ///   An exception generated this way acts as a breakpoint. The thread may be
    ///   resumed after the exception. Once resumed, the *condition* triggering the
    ///   exception will be allowed to complete as if no policy violation occurred.
    /// + **ZX_POL_ACTION_DENY_EXCEPTION**  just like **ZX_POL_ACTION_ALLOW_EXCEPTION**,
    ///   but after resuming, the *condition* will be denied, usually resulting in
    ///   **ZX_ERR_ACCESS_DENIED**.
    /// + **ZX_POL_ACTION_KILL**  terminate the process.
    ///
    /// Where *flags* is one of
    ///
    /// + **ZX_POL_OVERRIDE_ALLOW** Allow to change this policy on child Jobs.
    /// + **ZX_POL_OVERRIDE_DENY** Don't allow to change this policy on child jobs.
    ///
    /// Regardless of the override mode, as long a Job has any children its policy cannot
    /// be mutated.
    ///
    /// ### **ZX_JOB_POL_TIMER_SLACK**
    ///
    /// A *topic* of **ZX_JOB_POL_TIMER_SLACK** indicates that *policy* is:
    ///
    /// ```
    /// typedef struct zx_policy_timer_slack {
    ///     zx_duration_t min_slack;
    ///     uint32_t default_mode;
    /// } zx_policy_timer_slack_t;
    ///
    /// ```
    ///
    /// *min_slack* specifies the minimum amount of slack applied to timers and
    /// deadline-based events created by the job.
    ///
    /// If the parent job's *min_slack* is greater than the specified *min_slack* then
    /// the parent job's value is used instead. In other words, a job's *min_slack* is
    /// the maximum of the specified value and its parent job's *min_slack*.
    ///
    /// *default_mode* specifies how slack will be applied when not otherwise indicated
    /// by the syscall arguments. A job's *default_mode* may be set regardless of its
    /// parent job's *default_mode*. The possible values for *default_mode* are:
    ///
    /// + **ZX_TIMER_SLACK_CENTER**
    /// + **ZX_TIMER_SLACK_EARLY**
    /// + **ZX_TIMER_SLACK_LATE**
    ///
    /// See [timer slack](/docs/concepts/kernel/timer_slack.md) for more information.
    ///
    /// When setting timer slack policy, *options* must be **ZX_JOB_POL_RELATIVE** and
    /// **count** must be 1.
    ///
    /// ## Rights
    ///
    /// *handle* must be of type **ZX_OBJ_TYPE_JOB** and have **ZX_RIGHT_SET_POLICY**.
    ///
    /// ## Return value
    ///
    /// `zx_job_set_policy()` returns **ZX_OK** on success.  In the event of failure,
    /// a negative error value is returned.
    ///
    /// ## Notes
    ///
    /// The **ZX_POL_BAD_HANDLE** policy never applies when calling [`zx_object_get_info()`]
    /// with the topic **ZX_INFO_HANDLE_VALID**.  All other topics and all other syscalls that
    /// take handles are subject to the policy if active.
    ///
    /// ## Errors
    ///
    /// **ZX_ERR_INVALID_ARGS**  *policy* was not a valid pointer, or *count* was 0,
    /// or *policy* was not **ZX_JOB_POL_RELATIVE** or **ZX_JOB_POL_ABSOLUTE**, or
    /// *topic* was not **ZX_JOB_POL_BASIC**.
    ///
    /// **ZX_ERR_BAD_HANDLE**  *handle* is not valid handle.
    ///
    /// **ZX_ERR_WRONG_TYPE**  *handle* is not a job handle.
    ///
    /// **ZX_ERR_ACCESS_DENIED**  *handle* does not have **ZX_POL_RIGHT_SET** right.
    ///
    /// **ZX_ERR_BAD_STATE**  the job has existing jobs or processes alive.
    ///
    /// **ZX_ERR_OUT_OF_RANGE** *count* is bigger than **ZX_POL_MAX** or *condition* is
    /// bigger than **ZX_POL_MAX**.
    ///
    /// **ZX_ERR_ALREADY_EXISTS** existing policy conflicts with the new policy.
    ///
    /// **ZX_ERR_NOT_SUPPORTED** an entry in *policy* has an invalid value.
    ///
    /// **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_job_create()`]
    ///  - [`zx_object_get_info()`]
    ///  - [`zx_process_create()`]
    ///
    /// [`zx_job_create()`]: job_create.md
    /// [`zx_object_get_info()`]: object_get_info.md
    /// [`zx_process_create()`]: process_create.md
    /// [`zx_vmo_replace_as_executable()`]: vmo_replace_as_executable.md
    strict SetPolicy(resource struct {
        handle Handle:JOB;
        options uint32;
        topic uint32;
        @voidptr
        @size32
        policy vector<byte>:MAX;
    }) -> () error Status;

    /// ## Summary
    ///
    /// Set a process as critical to a job.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_job_set_critical(zx_handle_t job,
    ///                                 uint32_t options,
    ///                                 zx_handle_t process);
    /// ```
    ///
    /// ## Description
    ///
    /// Sets *process* as critical to *job*. When *process* terminates, *job* will be
    /// terminated as if [`zx_task_kill()`] was called on it. The return code used will
    /// be **ZX_TASK_RETCODE_CRITICAL_PROCESS_KILL**.
    ///
    /// The *job* specified must be the parent of *process*, or an ancestor.
    ///
    /// If *options* is **ZX_JOB_CRITICAL_PROCESS_RETCODE_NONZERO**, then *job* will
    /// only be terminated if *process* has a non-zero return code.
    ///
    /// ## Rights
    ///
    /// *job* must have **ZX_RIGHT_DESTROY**.
    ///
    /// *process* must have **ZX_RIGHT_WAIT**.
    ///
    /// ## Return value
    ///
    /// `zx_job_set_critical()` returns **ZX_OK** on success. In the event of failure, a
    /// negative error value is returned.
    ///
    /// ## Errors
    ///
    /// **ZX_ERR_BAD_HANDLE**  *job* or *process* is not a valid handle.
    ///
    /// **ZX_ERR_WRONG_TYPE**  *job* or *process* is not a job handle.
    ///
    /// **ZX_ERR_INVALID_ARGS**  *options* is not 0 or
    /// **ZX_JOB_CRITICAL_PROCESS_RETCODE_NONZERO**, or *job* is not the parent of
    /// *process*, or an ancestor.
    ///
    /// **ZX_ERR_ALREADY_BOUND**  *process* has already been set as critical to a job.
    ///
    /// **ZX_ERR_ACCESS_DENIED**  *job* does not have **ZX_RIGHT_DESTROY** or *process*
    /// does not have **ZX_RIGHT_WAIT**.
    ///
    /// ## See also
    ///
    ///  - [`zx_job_create()`]
    ///  - [`zx_process_create()`]
    ///  - [`zx_task_kill()`]
    ///
    /// [`zx_job_create()`]: job_create.md
    /// [`zx_process_create()`]: process_create.md
    /// [`zx_task_kill()`]: task_kill.md
    strict SetCritical(resource struct {
        job Handle:JOB;
        options uint32;
        process Handle:PROCESS;
    }) -> () error Status;
};