// Copyright 2024 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=HEAD)
library fuchsia.hardware.suspend;

using zx;

/// Maximum number of suspend states supported by the system.
const MAX_SUSPEND_STATES uint32 = 256;

type SuspendState = table {
    /// The amount of time taken for the system to resume from this
    /// suspend state.
    1: resume_latency zx.Duration;
};

type WakeReason = table {
    /// A list of platform defined integers, each of which corresponds to
    /// a physical interrupt vector on the system. The simplest such mapping
    /// would be to map each interrupt number to a wake vector.
    1: wake_vectors vector<uint64>:MAX;

    /// A list of platform defined integers, each of which corresponds to
    /// a wake vector that is *not* backed by a hardware interrupt.
    2: soft_wake_vectors vector<uint64>:MAX;
};

open protocol Suspender {
    /// Returns a list of [`fuchsia.hardware.suspend/SuspendState`] supported.
    /// by the system. The system must return at least 1 suspend state which
    /// corresponds to the "suspend-to-idle" state but may return up to
    /// [`fuchsia.hardware.suspend/MAX_SUSPEND_STATES`] states.
    /// The suspend states must be ordered in order of decreasing
    /// `resume_latency` (and thereby increasing power consumption).
    /// A particular build of the system must always return the same set of
    /// suspend states.
    flexible GetSuspendStates() -> (table {
        1: suspend_states vector<SuspendState>:MAX_SUSPEND_STATES;
    }) error zx.Status;

    /// Instruct the system to suspend.
    /// This call may return a ZX_ERR_* if the system was unable to suspend.
    /// If the call succeeds, it will not return until the system has resumed.
    /// Being interrupted while suspending and resuming before fully suspending
    /// is not an error however `suspend_duration` must be None if the suspend
    /// was interrupted.
    flexible Suspend(table {
        /// This index corresponds to an entry in the vector returned by
        /// GetSuspendStates. Returns ZX_ERR_OUT_OF_RANGE if `state_index` is
        /// greater than the number of supported suspend states. Returns
        /// ZX_ERR_INVALID_ARGS if this field is unset.
        1: state_index uint64;
    }) -> (table {
        /// The `WakeReason` that caused the system to resume.
        /// See `type WakeReason` above for more details about wake reasons.
        1: reason WakeReason;

        /// The amount of time the system spent suspended. If the system is
        /// interrupted during suspend this field is unset.
        2: suspend_duration zx.Duration;

        /// The amount of time it took for the system to suspend and resume not
        /// including the duration that the system was suspended.
        3: suspend_overhead zx.Duration;
    }) error zx.Status;
};

service SuspendService {
    suspender client_end:Suspender;
};