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

library fuchsia.device;

using zx;

/// Maxmium length for a device name
const uint64 MAX_DEVICE_NAME_LEN = 32;
/// Maximum length of a device path
const uint64 MAX_DEVICE_PATH_LEN = 1024;
/// Maxmium length for a driver name
const uint64 MAX_DRIVER_NAME_LEN = 32;
/// Maximum length for a driver path
const uint64 MAX_DRIVER_PATH_LEN = 1024;
/// Maximum device power states. In future this should account
/// for performant states.
const uint32 MAX_DEVICE_POWER_STATES = 5;
const uint32 MIN_DEVICE_POWER_STATES = 2; // D0 & D3COLD

/// Signal that will be active on a device event handle if the device's read() method
/// will return data.
const uint32 DEVICE_SIGNAL_READABLE = 0x01000000; // ZX_USER_SIGNAL_0
/// Signal that will be active on a device event handle if the device has some out-of-band
/// mechanism that needs attention.
/// This is primarily used by the PTY support.
const uint32 DEVICE_SIGNAL_OOB = 0x02000000; // ZX_USER_SIGNAL_1
/// Signal that will be active on a device event handle if the device's write() method
/// will accept data.
const uint32 DEVICE_SIGNAL_WRITABLE = 0x04000000; // ZX_USER_SIGNAL_2
/// Signal that will be active on a device event handle if the device has encountered an error.
/// This is primarily used by the PTY support.
const uint32 DEVICE_SIGNAL_ERROR = 0x08000000; // ZX_USER_SIGNAL_3
/// Signal that will be active on a device event handle if the device has been disconnected.
/// This is primarily used by the PTY support.
const uint32 DEVICE_SIGNAL_HANGUP = 0x10000000; // ZX_USER_SIGNAL_4


enum DevicePowerState : uint8 {
  /// Mandatory Working state. Device is fully functional, can take I/O,
  /// issue interrrupts. This state is mandatory for all devices
  /// The device enters into this state by default, when powered on.
  DEVICE_POWER_STATE_D0 = 0;
  /// [OPTIONAL] Device is not working when in this state. It cannot process
  /// I/O nor issue interrupts, unless it is armed for some special interrupts
  /// that can wake up the system/device. When in this state, the restore time
  /// of getting back to working state is less than other low-power states
  /// Power savings in this state are lesser than other low power states.
  /// Device may retain some hardware context and full initialization
  /// may not be needed when resuming from this state.
  DEVICE_POWER_STATE_D1 = 1;
  /// [OPTIONAL] Device is not working when in this state. It cannot process
  /// I/O nor issue interrupts, unless it is armed for some special interrupts
  /// that can wake up the system/device. When in this state, the restore time
  /// of getting back to working state is more than DEVICE_POWER_STATE_D1 and
  /// less than restore time of getting back from DEVICE_POWER_STATE_D3HOT,
  /// DEVICE_POWER_STATE_D3COLD. Power savings in this state are lesser
  /// than DEVICE_POWER_STATE_D3COLD, DEVICE_POWER_STATE_D3HOT.
  /// Device may retain some hardware context and full initialization
  /// may not be needed when resuming from this state.
  DEVICE_POWER_STATE_D2 = 2;
  /// [OPTIONAL] Device is not working when in this state. It cannot process
  /// I/O nor issue interrupts, unless it is armed for some special interrupts
  /// that can wake up the system/device. When in this state, the restore time
  /// of getting back to working state is more than DEVICE_POWER_STATE_D1,
  /// DEVICE_POWER_STATE_D3HOT and less than restore time of getting back from
  /// DEVICE_POWER_STATE_D3COLD. Power savings in this state are lesser
  /// than DEVICE_POWER_STATE_D3COLD. Device has no context and full initialization
  /// by the device driver when resuming from this state.
  /// Although the device is completely off, it is still powered on and is enumerable.
  DEVICE_POWER_STATE_D3HOT = 3;
  /// [MANDATORY] Device is not working when in this state. It cannot process
  /// I/O nor issue interrupts, unless it is armed for some special interrupts
  /// that can wake up the system/device. When in this state, the restore time
  /// of getting back to working state is more than all other low power states.
  /// Power savings are more compared to all other low-power states.
  /// Device has no context and full initialization by the device driver when
  /// resuming from this state. In this state, the power to this device is turned off.
  /// Device may be powered by other auxiliary supplies to support wake capability.
  DEVICE_POWER_STATE_D3COLD = 4;
};

//TODO(ravoorir): This should be table when the Controller protocol moves off of
//simple layout.
struct DevicePowerStateInfo {
  DevicePowerState state_id;

  /// Is this state supported?
  bool is_supported;

  /// Restore time for coming out of this state to working D0 state.
  int64 restore_latency;

  /// Is this device wakeup_capable?
  bool wakeup_capable;

  /// Deepest system system sleep state that the device can wake the system from.
  int32 system_wake_state;
};

/// Interface for manipulating a device in a devhost
[Layout = "Simple"]
protocol Controller {
    /// Attempt to bind the requested driver to this device
    Bind(string:MAX_DRIVER_PATH_LEN driver) -> (zx.status status);
    /// Disconnect this device and allow its parent to be bound again.
    /// This may not complete before it returns.
    ScheduleUnbind() -> (zx.status status);

    /// Return the name of the driver managing this the device
    GetDriverName() -> (zx.status status, string:MAX_DRIVER_NAME_LEN? name);
    /// Return the name of the device
    GetDeviceName() -> (string:MAX_DEVICE_NAME_LEN name);

    /// Return the topological path for this device
    GetTopologicalPath() -> (zx.status status, string:MAX_DEVICE_PATH_LEN? path);

    /// Get an event for monitoring device conditions (see `DEVICE_SIGNAL_*` constants)
    GetEventHandle() -> (zx.status status, handle<event>? event);

    /// Return the current logging flags for this device's driver
    GetDriverLogFlags() -> (zx.status status, uint32 flags);
    /// Set the logging flags for this device's driver.
    /// Each set bit in `clear_flags` will be cleared in the log flags state.
    /// Each set bit in `set_flags` will then be set in the log flags state.
    SetDriverLogFlags(uint32 clear_flags, uint32 set_flags) -> (zx.status status);

    /// Debug command: execute the device's suspend hook
    DebugSuspend() -> (zx.status status);
    /// Debug command: execute the device's resume hook
    DebugResume() -> (zx.status status);

    /// Runs compatibility tests for the driver that binds to this device.
    /// The |hook_wait_time| is the time that the driver expects to take for
    /// each device hook in nanoseconds.
    /// Returns whether the driver passed the compatibility check.
    RunCompatibilityTests(int64 hook_wait_time) -> (uint32 status);

    /// Gets the device power capabilities. Used by the system wide power manager
    /// to manage power for this device.
    GetDevicePowerCaps() -> (array<DevicePowerStateInfo>:MAX_DEVICE_POWER_STATES dpstates) error zx.status;

    /// Transition this device from a working to a sleep state or from a sleep state to a deeper sleep
    /// state. TODO(ravoorir): At the moment, this will call the suspend hook only on this device.
    /// In a future change, this api will result in suspend hook being called on all the children and
    /// descendants before transitioning this device.
    /// On success, the out_state is same as requested_state.
    /// On failure, the out_state is the state the device can go into at this point, depending
    /// on the configuration of its children. For example, a device cannot go into the
    /// requested_state, if the requested_state does not support a descendant's wake configuration.
    Suspend(DevicePowerState requested_state) -> (zx.status status, DevicePowerState out_state);
    /// Transition this device from a sleep state to a working state.
    /// TODO(ravoorir): At the moment, this will call the resume hook only on this device.
    /// In a future change, this api will result in resume hook being called on all the children
    /// after the current device is transitioned.
    /// On success, the out_state has the actual state of the device. The out_state could be
    /// different from the requested_state, if the device could not resume to the requested
    /// performant state, but the device could resume to a working state.
    //  Just because the device is not able to transition to a particular performant state,
    //  we do not want to suspend the device back.
    Resume(DevicePowerState requested_state) -> (DevicePowerState out_state) error zx.status;
};