// Copyright 2023 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.framework;

using fuchsia.url;

/// The type of Fuchsia package that a driver component is inside of.
/// More details about the various package categories are available at:
/// https://fuchsia.dev/fuchsia-src/concepts/packages/package#types_of_packages
@available(added=16)
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 if a full package
    /// resolver is available.
    CACHED = 2;
    /// UNIVERSE packages get onto the device only when resolved by the full package resolver.
    UNIVERSE = 3;
};

/// Device categories as provided in the driver's component manifest.
@available(added=16)
type DeviceCategory = table {
    1: category string:MAX;
    2: subcategory string:MAX;
};

/// General information for a driver, used with both composite and normal drivers.
@available(added=16)
type DriverInfo = table {
    /// URL of the driver component.
    1: url string:fuchsia.url.MAX_URL_LENGTH;

    /// Name of the driver, taken from the first field of the `ZIRCON_DRIVER`
    /// macro in the driver.
    2: name string:MAX;

    /// 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. Fallback drivers have a
    /// lesser priority for binding, so they will only be chosen for binding if there
    /// is no non-fallback driver that has matched.
    5: is_fallback bool;

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

    /// Bind rules which declare set of constraints to evaluate in order to
    /// determine whether the driver indexer should bind this driver to a
    /// device.
    7: bind_rules_bytecode vector<uint8>:MAX;

    /// The version of the driver framework that this driver is using.
    /// Supported values are 1 (DFv1) and 2 (DFv2).
    /// If not provided, 1 is the assumed version.
    8: driver_framework_version uint8;

    /// Whether the driver is disabled. If true, this driver is not chosen to bind to nodes.
    @available(added=17)
    9: is_disabled bool;

    // TODO(b/303084353): Add the merkle root when the type is available in the sdk.
};

/// Information for a composite driver.
@available(added=16)
type CompositeDriverInfo = table {
    /// The name of the composite as specified in the driver's composite bind rules.
    1: composite_name string:MAX;

    /// General information for the driver.
    2: driver_info DriverInfo;
};

/// Information for a composite driver that has matched with a composite.
@available(added=16)
type CompositeDriverMatch = table {
    /// Information for the composite driver that has matched.
    1: composite_driver CompositeDriverInfo;

    /// A list of all the parent names, ordered by index.
    /// These names come from the node definitions in the driver's composite bind rules.
    2: parent_names vector<string:MAX>:MAX;

    /// The primary node index. Identified by the primary node in the driver's
    /// composite bind rules.
    3: primary_parent_index uint32;
};

/// Information for a composite that is defined by a composite node spec.
@available(added=16)
type CompositeInfo = table {
    /// The spec information that this composite node spec was created with.
    1: spec CompositeNodeSpec;

    /// Information for the node spec that is available only when a driver
    /// has matched to the properties in this spec's parents.
    2: matched_driver CompositeDriverMatch;
};

/// A parent to a composite that is defined by a composite node spec.
@available(added=16)
type CompositeParent = table {
    /// Information about the composite that this is a parent of.
    1: composite CompositeInfo;

    /// The index of this parent in the spec's parents.
    2: index uint32;
};