main/syscalls/system_set_processor_power_domain.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_system_set_processor_power_domain

## Summary

Informs the kernel of the processor power levels within a given power
domain for energy-aware scheduling.

## Declaration

```c
#include <zircon/syscalls-next.h>

zx_status_t zx_system_set_processor_power_domain(
    zx_handle_t resource,
    uint64_t options,
    const zx_power_domain_t* power_domain,
    zx_handle_t port,
    const zx_processor_power_level_t* power_levels,
    size_t num_power_levels,
    const zx_processor_power_level_transition_t* transitions,
    size_t num_transitions);
```

## Description

Enables energy-aware scheduling for a given processor power domain.

Power levels are implicitly enumerated as the indices of `power_levels`.

There are no ordering restrictions on `transformations` and the power
levels they encode correspond to those defined by `power_levels`. An
absent transformation between levels is assumed to indicate that there
is no energy cost borne by perfoming it.

The provided `power_domain_id` provides a unique identifier for requesting
operations on all CPUs that are part of `cpus` mask. Any power level
transition handler must understand the association.

This syscall shall have "set or update" semantics, such that any new data
replaces exisitng one. This applies for `power_domain_id` and `cpus`.

Provided `port` will be used for queueing power level transition requests.

## Rights

`resource` must be of `ZX_RSRC_KIND_SYSTEM` kind and
`ZX_RSRC_SYSTEM_CPU_BASE` base.

## Return value

`ZX_OK` is returned if and only if the processor power level domain
was successfully registered.

## Errors

`ZX_ERR_ACCESS_DENIED` if `resource` is not a valid handle.

`ZX_ERR_WRONG_TYPE` if `resource` is not a valid resource handle of
SYSTEM kind and CPU base.

`ZX_ERR_OUT_OF_RANGE` if `num_power_levels` exceeds
`ZX_MAX_POWER_LEVELS` or `num_transitions` exceeds
`ZX_MAX_POWER_LEVEL_TRANSITIONS`.