zx_profile_create

Summary

Create a scheduler profile.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_profile_create(zx_handle_t root_job,
                              uint32_t options,
                              const zx_profile_info_t* profile,
                              zx_handle_t* out);

Description

zx_profile_create() creates a new profile 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.

#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

root_job must be of type ZX_OBJ_TYPE_JOB and have ZX_RIGHT_MANAGE_PROCESS.

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 root_job is not a valid handle.

ZX_ERR_WRONG_TYPE root_job is not a job handle.

ZX_ERR_ACCESS_DENIED root_job does not have ZX_RIGHT_MANAGE_PROCESS right, or root_job is not a handle to the root job.

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.