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

@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
};

/// Interface for manipulating a device in a devhost
///
/// # Deprecation
///
/// This interface is moving to fuchsia.device.fs.
/// Tracking bug: https://fxbug.dev/340316138
/// Please use that version of this protocol.
/// Also, see //sdk/fidl/fuchsia.device.fs/README.md
/// for future plans for DevFS.
closed protocol Controller {
    /// Connect to the underlying device's FIDL protocol.
    /// This connection will not be multiplexed with fuchsia.device.Controller
    /// or fuchsia.io.Node.
    strict ConnectToDeviceFidl(resource struct {
        server zx.Handle:CHANNEL;
    });

    /// Connect to the same Controller FIDL protocol.
    strict ConnectToController(resource struct {
        server server_end:Controller;
    });

    /// 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.
    strict 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.
    strict 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.
    strict UnbindChildren() -> () error zx.Status;

    /// Disconnect this device and allow its parent to be bound again.
    /// This may not complete before it returns.
    strict ScheduleUnbind() -> () error zx.Status;

    /// Return the topological path for this device
    strict GetTopologicalPath() -> (struct {
        path string:MAX_DEVICE_PATH_LEN;
    }) error zx.Status;
};