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.
@available(added=HEAD)
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.NodeProperties;

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

/// This is served by the driver manager for the driver index to use to notify it of new
/// drivers that are available on the driver index.
///
/// We are making this a separate protocol so that the DriverIndex protocol can be marked as
/// delivery: on_readable. This way no matter what protocol caused the index to wake up, we can
/// send notifications to the driver manager.
closed protocol DriverNotifier {
    /// One-way method called from the driver index to the driver manager to notify it of
    /// new drivers.
    strict NewDriverAvailable();
};

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

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

    /// Sets the DriverNotifier which is used for reverse communication.
    strict SetNotifier(resource struct {
        notifier client_end:DriverNotifier;
    });
};