// 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;

type ProfileInfoType = strict enum {
    ZX_PROFILE_INFO_SCHEDULER = 1;
};

type ProfileScheduler = strict union {
    1: priority int32;
    2: boost uint32;
    3: deboost uint32;
    4: quantum uint32;
};

const ZX_PRIORITY_LOWEST int32 = 0;
const ZX_PRIORITY_LOW int32 = 8;
const ZX_PRIORITY_DEFAULT int32 = 16;
const ZX_PRIORITY_HIGH int32 = 24;
const ZX_PRIORITY_HIGHEST int32 = 31;

type ProfileInfoData = strict union {
    1: scheduler ProfileScheduler;
};

type ProfileInfo = struct {
    type ProfileInfoType;
    // TODO(scottmg): This needs to be presented as an unnamed union in C, and
    // ProfileInfoData doesn't really need a name. Not sure if the semantics of
    // fidl unions make sense here.
    unnamed ProfileInfoData;
};

@transport("Syscall")
closed protocol Profile {
    /// ## Summary
    ///
    /// Create a scheduler profile.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_profile_create(zx_handle_t profile_rsrc,
    ///                               uint32_t options,
    ///                               const zx_profile_info_t* profile,
    ///                               zx_handle_t* out);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_profile_create()` creates a new [profile](/docs/reference/kernel_objects/profile.md) object.
    ///
    /// The parameter *profile* specifies the settings in the profile, which in turn
    /// will be applied to threads when [`zx_object_set_profile()`] is called. The
    /// fields of *profile* are shown below. *options* must be zero.
    ///
    /// ```c
    /// #define ZX_PROFILE_INFO_FLAG_PRIORITY (1 << 0)
    /// #define ZX_PROFILE_INFO_FLAG_CPU_MASK (1 << 1)
    /// #define ZX_PROFILE_INFO_FLAG_DEADLINE (1 << 2)
    /// #define ZX_PROFILE_INFO_FLAG_NO_INHERIT (1 << 3)
    /// #define ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY (1 << 4)
    ///
    /// typedef struct zx_profile_info {
    ///   // A bitmask of ZX_PROFILE_INFO_FLAG_* values. Controls overall profile
    ///   // options as well as determining which other fields below have been specified.
    ///   // Other fields are considered unset.
    ///   uint32_t flags;
    ///
    ///   uint8_t padding1[4];
    ///
    ///   union {
    ///     struct {
    ///       // Scheduling priority. |flags| must have ZX_PROFILE_INFO_FLAG_PRIORITY or
    ///       // ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY set.
    ///       int32_t priority;
    ///       uint8_t padding2[20];
    ///     };
    ///
    ///     // Scheduling deadline. |flags| must have ZX_PROFILE_INFO_FLAG_DEADLINE set.
    ///     zx_sched_deadline_params_t deadline_params;
    ///   };
    ///
    ///   // CPUs that threads may be scheduled on. |flags| must have
    ///   // ZX_PROFILE_INFO_FLAG_CPU_MASK set.
    ///   zx_cpu_set_t cpu_affinity_mask;
    /// } zx_profile_info_t;
    /// ```
    ///
    /// The `flags` field controls overall profile options in addition to specifying
    /// which fields in the `zx_profile_info_t` structure contain valid values. Values
    /// in fields without a corresponding `flag` bit set will be ignored. This allows
    /// fields with values of `0` and unset fields to be distinguished, even if
    /// additional fields are added in future.
    ///
    /// `ZX_PROFILE_INFO_FLAG_PRIORITY` and `ZX_PROFILE_INFO_FLAG_DEADLINE` specify the
    /// `scheduling discipline` for the profile, either "fair scheduling" (for
    /// `PRIORITY`) or "deadline scheduling" (for `DEADLINE`.  No more than one of these
    /// disciplines may be selected at the same time.
    ///
    /// `ZX_PROFILE_INFO_FLAG_MEMORY_PRIORITY` allows for creating a profile that can be applied to
    /// VMARs and is incompatible with any flags related scheduling. When selecting a memory
    /// priority only `ZX_PRIORITY_DEFAULT` and `ZX_PRIORITY_HIGH` currently have meaning, with the
    /// former being the default all VMARs initially have, and the latter indicating that all kernel
    /// initiated reclamation on objects the profile is applied to should be avoided.
    ///
    /// By default, profiles participate in profile inheritance when assigned to a
    /// thread which blocks in a futex with an assigned owner (see `zx_futex_wait()`).
    /// Profiles created with the `ZX_PROFILE_INFO_FLAG_NO_INHERIT` do not.  When
    /// threads assigned with such a profile block in a futex with an owner, the
    /// owner of the futex receives no direct profile pressure from the blocking
    /// thread (however, they may receive pressure from a different thread
    /// blocked behind the blocking thread).
    ///
    /// Deadline profiles must always be inheritable.  Attempts to create a
    /// non-inheritable deadline profile will fail with ZX_ERR_INVALID_ARGS.
    ///
    ///
    /// Upon success a handle for the new profile is returned.
    ///
    /// ## Rights
    ///
    /// *profile_rsrc* must have resource kind `ZX_RESOURCE_KIND_SYSTEM` with base
    /// `ZX_RSRC_SYSTEM_PROFILE_BASE`.
    ///
    /// Caller job policy must allow `ZX_POL_NEW_PROFILE`.
    ///
    /// ## Return value
    ///
    /// Returns `ZX_OK` and a handle to the new profile (via *out*) on success. In the
    /// event of failure, a negative error value is returned.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_BAD_HANDLE`  *profile_rsrc* is not a valid handle.
    ///
    /// `ZX_ERR_ACCESS_DENIED`  *profile_rsrc* is not the profile resource.
    ///
    /// `ZX_ERR_INVALID_ARGS`  One or more of the arguments provided were invalid:
    ///
    ///   * *profile* or *out* was an invalid pointer
    ///   * *flags* contains an unknown option
    ///   * *flags* either failed to specify a scheduling discipline, a cpu affinity mask, or a
    ///             memory priority.
    ///   * *flags* specified more than one scheduling discipline at once.
    ///   * *flags* specified the scheduling discipline as deadline, but the profile
    ///             was also marked as "no inherit".
    ///   * *flags* specified a scheduling discipline and a memory priority.
    ///   * *options* was not zero
    ///   * *priority* was an invalid priority
    ///
    /// `ZX_ERR_NO_MEMORY`  Failure due to lack of memory.
    ///
    /// ## See also
    ///
    ///  - [`zx_object_set_profile()`]
    ///  - [`zx_futex_wait()`]
    ///
    /// [`zx_object_set_profile()`]: object_set_profile.md
    /// [`zx_futex_wait()`]: futex_wait.md
    strict Create(resource struct {
        profile_rsrc Handle:RESOURCE;
        options uint32;
        profile ProfileInfo;
    }) -> (resource struct {
        out Handle:PROFILE;
    }) error Status;
};