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

/// Driver matched by the driver index.
type MatchDriverResult = flexible union {
    /// Information for a normal driver.
    1: driver fuchsia.driver.framework.DriverInfo;

    /// Information for a parent spec.
    2: composite_parents vector<fuchsia.driver.framework.CompositeParent>:MAX;
};

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;

    // If this is present, only drivers with URLs that end with this suffix will be checked for
    // binding.
    3: driver_url_suffix string:MAX;
};

/// Protocol through which the driver index can be queried.
@discoverable
closed protocol DriverIndex {
    /// Match a set of device arguments to a driver package URL.
    strict MatchDriver(struct {
        args MatchDriverArgs;
    }) -> (MatchDriverResult) error zx.Status;

    /// Hanging get function that replies when a boot or base driver is loaded
    /// into the Driver Index.
    strict WatchForDriverLoad() -> ();

    /// Adds a composite node spec to the driver index. The driver index stores the
    /// composite node spec and maps it by the name. The stored composite node specs are
    /// included in the driver matching process.
    strict AddCompositeNodeSpec(fuchsia.driver.framework.CompositeNodeSpec) -> () error zx.Status;

    /// Rematch the composite node spec to a composite driver. If a driver url suffix is
    /// provided, the composite node spec will only be matched against drivers with URLS that
    /// end with the suffix.
    strict RebindCompositeNodeSpec(struct {
        spec string:MAX;
        driver_url_suffix string:<MAX, optional>;
    }) -> () error zx.Status;
};