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

/// `PowerElementConfiguration` and types contained in that struct define
/// the configuration that drivers can expect from board drivers. This
/// configuration information is intended to be reflected into the
/// power management system by the receivers of that configuration.
///
/// `PowerTokenService` is what drivers should implement to provide their
/// children with access to the driver's power elements.
library fuchsia.hardware.power;

using zx;

const MAX_NAME_LENGTH uint16 = 63;

/// This means we could have up to 128 power levels, which seems like more than
/// enough.
const MAX_TRANSITIONS uint16 = 127;

/// Should be MAX_TRANSITIONS + 1
const MAX_LEVELS uint16 = 128;

const MAX_DEPENDENCIES uint16 = 128;

/// The length of time it takes to move to a power level.
/// + `target_level` is the power level we're moving to.
/// + `latency_us` is the time it takes to move to the level in microseconds.
type Transition = table {
    1: target_level uint8;
    2: latency_us uint32;
};

/// A zero-indexed set of levels that a device can assume.
/// + `level` is the zero-indexed level of this `PowerLevel`.
/// + `name` is a human-readable label for this `PowerLevel`, used only for
///   debugging.
/// + `transitions` describes the levels that are valid transitions from this
///   `PowerLevel`.
type PowerLevel = table {
    1: level uint8;
    2: name string:MAX_NAME_LENGTH;
    3: transitions vector<Transition>:MAX_TRANSITIONS;
};

/// Set of `PowerLevel`s and a human-readable identifier. A `PowerLevel` itself
/// contains information about valid transitions out of that level.
type PowerElement = table {
    1: name string:MAX_NAME_LENGTH;
    2: levels vector<PowerLevel>:MAX_LEVELS;
};

/// Represents a dependency between two power levels of two different
/// `PowerElement`s.
type LevelTuple = table {
    1: child_level uint8;
    2: parent_level uint8;
};

type RequirementType = strict enum {
    ACTIVE = 1;
    PASSIVE = 2;
};

/// Describes the relationship between the `PowerLevel`s of two
/// `PowerElement`s. `child` is the name of the `PowerElement` which has
/// `PowerLevel`s that depend on `parent`.
/// + `child` is the name for a `PowerElement` which a driver owns.
/// + `parent` is the name for a `PowerElement` which a driver has access to
/// + `level_deps` is the map of level dependencies from `child` to `parent`.
type PowerDependency = table {
    1: child string:MAX_NAME_LENGTH;
    2: parent ParentElement;
    3: level_deps vector<LevelTuple>:MAX_LEVELS;
    4: strength RequirementType;
};

/// Contains the `PowerElement` description and any dependencies it has on
/// other `PowerElement`s.
type PowerElementConfiguration = table {
    1: element PowerElement;
    2: dependencies vector<PowerDependency>:MAX_DEPENDENCIES;
};

// NOTE: This is _not_ a complete list of SAG elements. This enum only lists
// the elements supported by the power support library. For a complete list
// of SAG elements, see `fuchsia.power.system.PowerElements`.
type SagElement = strict enum {
    EXECUTION_STATE = 1;
    EXECUTION_RESUME_LATENCY = 2;
    WAKE_HANDLING = 3;
    APPLICATION_ACTIVITY = 4;
};

/// Identifier for an element that is another element's parent, in other words
/// an element that the other element depends upon.
type ParentElement = strict union {
    /// The parent element's access token should be available from a
    /// `PowerTokenProvider` capability in the incoming namespace and should
    /// provide this same string in the `GetToken` response.
    1: name string:MAX_NAME_LENGTH;
    /// The parent element is one of SAG's elements and the access token should
    /// be obtained from the appropriate SAG-related protocol.
    2: sag SagElement;
};

@discoverable
open protocol PowerTokenProvider {
    /// Returns a token which can be used with `fuchsia.power.broker` APIs to
    /// create a relationship between this driver's power element(s) and the
    /// power element this token is associated with.
    flexible GetToken() -> (resource struct {
        handle zx.Handle:EVENT;
        name string:MAX_NAME_LENGTH;
    }) error zx.Status;
};

@available(added=HEAD)
service PowerTokenService {
    token_provider client_end:PowerTokenProvider;
};