// Copyright 2020 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.driver.index;

using fuchsia.driver.framework;
using fuchsia.url;

using zx;

/// The type of Fuchsia package that a driver component is inside of.
type DriverPackageType = flexible enum : uint8 {
    /// BOOT packages are inside the Zircon boot image.
    BOOT = 0;
    /// BASE packages are included in the Fuchsia build as static local packages.
    BASE = 1;
    /// CACHED packages are BASE packages that can be updated during a resolve.
    CACHED = 2;
    /// UNIVERSE packages get onto the device only when resolved by the package resolver.
    UNIVERSE = 3;
};

/// Information for a driver matched by the driver index. This is used by
/// normal and composite drivers.
type MatchedDriverInfo = table {
    /// URL of the driver component.
    1: url string:fuchsia.url.MAX_URL_LENGTH;

    /// URL of the driver library. This should only be used by DriverManager
    /// before Drivers-As-Components.
    2: driver_url string:fuchsia.url.MAX_URL_LENGTH;

    /// If this is true then the driver should be colocated in its parent's DriverHost.
    3: colocate bool;

    /// The type of package this driver is in.
    4: package_type DriverPackageType;

    /// If this is true then the driver is a fallback driver.
    5: is_fallback bool;
};

/// Information for a composite driver matched by the driver index.
type MatchedCompositeInfo = table {
    /// The name of the composite device.
    1: composite_name string:MAX;

    /// Node index for a composite driver.
    2: node_index uint32;

    /// Total number of nodes for a composite driver.
    3: num_nodes uint32;

    /// A list of all the node names for this composite driver.
    /// These are ordered according to index.
    4: node_names vector<string:MAX>:MAX;

    /// Information of the driver info.
    5: driver_info MatchedDriverInfo;
};

/// Information for a device group that contains a matched node.
type MatchedDeviceGroupInfo = table {
    /// Topological path of the node's device group.
    1: topological_path string:MAX;

    /// The node's index in its device group.
    2: node_index uint32;
};

/// Information for a device group node that's matched by the driver index.
type MatchedDeviceGroupNodeInfo = table {
    /// A list of device groups that contain the matched node.
    1: device_groups vector<MatchedDeviceGroupInfo>:MAX;
};

/// Driver matched by the driver index.
type MatchedDriver = flexible union {
    /// Information for a normal driver.
    1: driver MatchedDriverInfo;

    /// Information for a composite driver.
    2: composite_driver MatchedCompositeInfo;

    /// Information for a device group node.
    3: device_group_node MatchedDeviceGroupNodeInfo;
};

/// Protocol through which the driver index can be queried.
@discoverable
protocol DriverIndex {
    /// Match a set of device arguments to a driver package URL.
    MatchDriver(struct {
        args fuchsia.driver.framework.NodeAddArgs;
    }) -> (struct {
        driver MatchedDriver;
    }) error zx.status;

    /// This function will block until base drivers are loaded.
    WaitForBaseDrivers() -> ();

    // TODO(fxbug.dev/81175): Remove V1 APIs
    /// This function returns a vector of drivers that match a device.
    /// This should only be used by DFv1 and should be removed.
    /// If more than MAX drivers match, only MAX drivers will be returned.
    MatchDriversV1(struct {
        args fuchsia.driver.framework.NodeAddArgs;
    }) -> (struct {
        drivers vector<MatchedDriver>:MAX;
    }) error zx.status;

    /// Adds a device group to the driver index. The driver index stores the
    /// device group and maps it by the topological path. The stored device
    /// groups are included in the driver matching process.
    AddDeviceGroup(struct {
        topological_path string:MAX;
        nodes vector<fuchsia.driver.framework.DeviceGroupNode>:MAX;
    }) -> (struct {}) error zx.status;
};