blob: 958a8a0c09aca9e68e0e767be67177f1af125889 [file] [log] [blame]
// 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;
using fuchsia.logger;
/// Maxmium length for a device name
const MAX_DEVICE_NAME_LEN uint64 = 32;
/// Maximum length of a device path
const MAX_DEVICE_PATH_LEN uint64 = 1024;
/// Maxmium length for a driver name
const MAX_DRIVER_NAME_LEN uint64 = 32;
/// Maximum length for a driver path
const MAX_DRIVER_PATH_LEN uint64 = 1024;
/// Maximum device power states. In future this should account
/// for performance states.
const MAX_DEVICE_POWER_STATES uint32 = 5;
const MIN_DEVICE_POWER_STATES uint32 = 2; // D0 & D3COLD
const MAX_DEVICE_PERFORMANCE_STATES uint32 = 20;
const MIN_DEVICE_PERFORMANCE_STATES uint32 = 1; // Fully performant state
@deprecated("devices will be services in the future")
type DeviceSignal = strict bits : uint32 {
/// Indicates the device is ready for reading.
READABLE = 0x01000000; // ZX_USER_SIGNAL_0
/// Indicates an out-of-band state transition has occurred.
OOB = 0x02000000; // ZX_USER_SIGNAL_1
/// Indicates the device is ready for writing.
WRITABLE = 0x04000000; // ZX_USER_SIGNAL_2
/// Indicates the device has encountered an error state.
ERROR = 0x08000000; // ZX_USER_SIGNAL_3
/// Indicates the device has hung up on the current connection.
HANGUP = 0x10000000; // ZX_USER_SIGNAL_4
};
type DevicePowerState = strict enum : uint8 {
/// Mandatory Working state. Device is fully functional, can take I/O,
/// issue interrupts. 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;
};
/// [MANDATORY] Default performance state when the device is in DEVICE_POWER_STATE_D0
const DEVICE_PERFORMANCE_STATE_P0 uint32 = 0;
// TODO(ravoorir): This should be table when the Controller protocol moves off of simple layout.
type DevicePowerStateInfo = struct {
state_id DevicePowerState;
/// Is this state supported?
is_supported bool;
/// Restore time for coming out of this state to working D0 state.
restore_latency int64;
/// Is this device wakeup_capable?
wakeup_capable bool;
/// Deepest system system sleep state that the device can wake the system from.
system_wake_state int32;
};
/// Performance state info for a device. A performance state is relevant only
/// when the device is in non-sleeping working device power state.
type DevicePerformanceStateInfo = struct {
state_id int32;
/// Restore time for coming out of this state to fully working performance state.
restore_latency int64;
/// Is this state supported?
is_supported bool;
// TODO(ravoorir): Explore how more device specific metadata can be saved here.
// Maybe a union of metadata coming from different devices.
};
type SystemPowerStateInfo = struct {
// TODO(ravoorir): This can be removed when all clients move away from the suspend_flag.
suspend_flag uint32;
/// Should wakeup be enabled from this system state?
wakeup_enable bool;
/// Device power state that the device should be in, for this system power state.
dev_state DevicePowerState;
/// Performance state that the device should be in, for this system power state.
/// Only applicable, if the dev_state is a working state (DEVICE_POWER_STATE_D0).
performance_state uint32;
};
/// Interface for manipulating a device in a devhost
protocol Controller {
/// Connect to the underlying device's FIDL protocol.
/// This connection will not be multiplexed with fuchsia.device.Controller
/// or fuchsia.io.Node.
ConnectToDeviceFidl(resource struct {
server zx.handle:CHANNEL;
});
/// Attempt to bind a driver to this device.
/// + request `driver` This represents the suffix of a driver URL (e.g: "fvm.cm").
/// If this is non-empty, then the only drivers that will try to bind
/// are ones that match this url suffix.
Bind(struct {
driver string:MAX_DRIVER_PATH_LEN;
}) -> () error zx.status;
/// Unbind all the children of this device, and then attempt to bind a driver to the device.
/// This will not return until the bind completes.
/// + request `driver` This represents the suffix of a driver URL (e.g: "fvm.cm").
/// If this is non-empty, then the only drivers that will try to bind
/// are ones that match this url suffix.
Rebind(struct {
driver string:MAX_DRIVER_PATH_LEN;
}) -> () error zx.status;
/// This api will unbind all the children of this device synchronously.
/// This will avoid watching for device removal by the clients.
UnbindChildren() -> () error zx.status;
/// Disconnect this device and allow its parent to be bound again.
/// This may not complete before it returns.
ScheduleUnbind() -> () error zx.status;
/// Return the topological path for this device
GetTopologicalPath() -> (struct {
path string:MAX_DEVICE_PATH_LEN;
}) error zx.status;
/// Return the current logging flags for this device's driver
GetMinDriverLogSeverity() -> (struct {
status zx.status;
severity fuchsia.logger.LogLevelFilter;
});
/// Set the logging flags for this device's driver.
SetMinDriverLogSeverity(struct {
severity fuchsia.logger.LogLevelFilter;
}) -> (struct {
status zx.status;
});
/// Gets the current performance state of the device.
GetCurrentPerformanceState() -> (struct {
out_state uint32;
});
/// Set the performance state of this device to the requested performance state. This is only
/// called for the current device and none of the descendants are aware of the state
/// transition.
/// Returns ZX_OK, if the device is in a working state and the performance state is changed to
/// requested_state successfully. out_state will be same as requested_state.
/// Returns error status, if switching to the requested_state was unsuccessful. out_state
/// is the state that the device is currently in.
SetPerformanceState(struct {
requested_state uint32;
}) -> (struct {
status zx.status;
out_state uint32;
});
};