sdk/fidl/fuchsia.driver.index/driver_index.fidl

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

type DeviceCategory = table {
    1: category string:MAX;
    2: subcategory string:MAX;
};

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

    /// Device categories
    6: device_categories vector<DeviceCategory>:MAX;
};

/// 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 node group that contains a matched node.
type MatchedNodeGroupInfo = table {
    /// The name of the node's node group.
    1: name string:MAX;

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

    /// The composite info of the driver that matches to the transform of this node group.
    3: composite MatchedCompositeInfo;

    /// Total number of nodes in the node group.
    4: num_nodes uint32;

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

    /// The primary node index.
    6: primary_index uint32;
};

/// Information for a node group node that's matched by the driver index.
type MatchedNodeRepresentationInfo = table {
    /// A list of node groups that contain the matched node.
    1: node_groups vector<MatchedNodeGroupInfo>: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 node group node.
    3: node_representation MatchedNodeRepresentationInfo;
};

type MatchDriverArgs = table {
    /// Properties of the node to be matched.
    1: properties fuchsia.driver.framework.NodePropertyVector;

    /// The name of the node to be matched. Used for debugging purposes.
    2: name fuchsia.driver.framework.NodeName;
};

/// 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 MatchDriverArgs;
    }) -> (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 MatchDriverArgs;
    }) -> (struct {
        drivers vector<MatchedDriver>:MAX;
    }) error zx.status;

    /// Adds a node group to the driver index. The driver index stores the
    /// node group and maps it by the name. The stored node groups are
    /// included in the driver matching process.
    // TODO(fxbug.dev/111076): Return just the status.
    AddNodeGroup(fuchsia.driver.framework.NodeGroup) -> (struct {
        composite_driver MatchedCompositeInfo;
        node_names vector<string:MAX>:MAX;
    }) error zx.status;
};