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

/// Represents a bind rule condition.
type Condition = strict enum {
    UNKNOWN = 0;
    ACCEPT = 1;
    REJECT = 2;
};

/// Represents a bind rule in a parent specification.
type BindRule = struct {
    /// Property key. Only string-based keys are supported.
    key NodePropertyKey;

    /// Condition for evaluating the property values in
    /// the matching process. The values must be ACCEPT
    /// or REJECT.
    condition Condition;

    /// A list of property values. Must not be empty. The property
    /// values must be the same type.
    values vector<NodePropertyValue>:MAX_PROPERTY_COUNT;
};

/// Represents a bind rule in a parent specification.
@available(added=27)
type BindRule2 = struct {
    /// Property key.
    key NodePropertyKeyString;

    /// Condition for evaluating the property values in
    /// the matching process. The values must be ACCEPT
    /// or REJECT.
    condition Condition;

    /// A list of property values. Must not be empty. The property
    /// values must be the same type.
    values vector<NodePropertyValue>:MAX_PROPERTY_COUNT;
};

/// Specification for a node that parents the composite node created from the
/// composite node specification.
type ParentSpec = struct {
    /// Parent's bind rules. Property keys must be unique. Must not be empty.
    bind_rules vector<BindRule>:MAX_PROPERTY_COUNT;

    /// Properties for matching against a composite driver's bind rules.
    /// Keys must be unique and string-based.
    properties vector<NodeProperty>:MAX_PROPERTY_COUNT;
};

/// Specification for a node that parents the composite node created from the
/// composite node specification.
@available(added=27)
type ParentSpec2 = struct {
    /// Parent's bind rules. Property keys must be unique. Must not be empty.
    bind_rules vector<BindRule2>:MAX_PROPERTY_COUNT;

    /// Properties for matching against a composite driver's bind rules.
    /// Keys must be unique and string-based.
    properties vector<NodeProperty2>:MAX_PROPERTY_COUNT;
};

/// Struct that represents a composite node specification.
type CompositeNodeSpec = table {
    /// The composite node spec's name.
    1: name string:MAX;

    /// The nodes in the composite node spec. Must not be empty. The first node is
    /// the primary node.
    2: parents vector<ParentSpec>:MAX;

    /// The nodes in the composite node spec. Must not be empty. The first node is
    /// the primary node.
    @available(added=27)
    3: parents2 vector<ParentSpec2>:MAX;
};

/// Error codes for the CompositeNodeManager protocol.
type CompositeNodeSpecError = flexible enum {
    /// An argument of the composite node spec was not provided.
    MISSING_ARGS = 1;
    /// The given composite node spec's `nodes` is empty.
    EMPTY_NODES = 2;
    /// The `name` in the given composite node spec is a duplicate of an already
    /// created composite node spec.
    ALREADY_EXISTS = 3;
    /// The spec failed to be added to the driver index.
    @available(added=20)
    DRIVER_INDEX_FAILURE = 4;
    /// The `parents` and `parents2` fields were both specified.
    @available(added=27)
    DUPLICATE_PARENTS = 5;
};

/// Protocol through which board drivers can create composite node specs.
///
/// Composite node specs are created at runtime to dynamically bridge the
/// static bind rules of a composite driver with the dynamic bind properties
/// of nodes in the system so that the driver bind rules are more generic and reusable.
@discoverable
open protocol CompositeNodeManager {
    /// Adds the given composite node specification to the driver framework.
    flexible AddSpec(CompositeNodeSpec) -> () error CompositeNodeSpecError;
};