docs/reference/syscalls/profile_create.md

<!--
Copyright 2023 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.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# zx_profile_create

## Summary

Create a scheduler profile.

## Declaration

```c
#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](/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

*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.

## See also

 - [`zx_object_set_profile()`]
 - [`zx_futex_wait()()`]

[`zx_object_set_profile()`]: object_set_profile.md
[`zx_futex_wait()`]: futex_wait.md