// 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.
@available(added=20)
library fuchsia.scheduler;

using zx;

const MAX_NAME_LENGTH int32 = 2048;
const MAX_PARAMETER_KEY_LENGTH int32 = 512;
const MAX_PARAMETER_VALUE_LENGTH int32 = 2048;
const MAX_PARAMETER_COUNT int32 = 512;

// The value type used by input/output parameters.
type ParameterValue = flexible union {
    1: float_value float64;
    2: int_value int64;
    3: string_value string:MAX_PARAMETER_VALUE_LENGTH;
};

// Input/output parameter type used by SetRole.
type Parameter = struct {
    key string:MAX_PARAMETER_KEY_LENGTH;
    value ParameterValue;
};

// The string name of a role.
// TODO(https://fxbug.dev/42158155): Ideally this would just be an alias of
// `string:MAX_NAME_LENGTH`, but that is not supported in FIDL yet; see
// https://fuchsia.dev/error/fi-0062 for more information.
type RoleName = struct {
    role string:MAX_NAME_LENGTH;
};

/// A Zircon object to which a profile can be applied.
/// Currently, only threads and vmars are supported.
type RoleTarget = flexible resource union {
    1: thread zx.Handle:THREAD;
    2: vmar zx.Handle:VMAR;
};

/// Allows callers to modify the runtime profiles of zircon objects.
@discoverable
open protocol RoleManager {
    /// Sets the given object's performance parameters based on the requested
    /// role. The exact parameters of the role are system dependent and may
    /// vary based on device-specific tuning and/or runtime system goals.
    ///
    /// + request `target` is a handle to a zircon object to which a profile
    ///     can be applied.
    /// + request `role` is the name of the role to apply to the target.
    /// + request `input_parameters` is a vector of key/value pairs used to
    ///     distinguish between multiple variants of the same role.
    /// - response `output_parameters` is a vector of key/value pairs that
    ///     roles can be configured to emit.
    /// * error a zx_status value indicating success or failure.
    flexible SetRole(resource table {
        1: target RoleTarget;
        2: role RoleName;
        3: input_parameters vector<Parameter>:MAX_PARAMETER_COUNT;
    }) -> (resource table {
        1: output_parameters vector<Parameter>:MAX_PARAMETER_COUNT;
    }) error zx.Status;
};