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

using fuchsia.component;

using zx;
alias NodePropertyKey = string:256;
alias NodePropertyValueUint = uint32;
alias NodePropertyValueString = string:256;
alias NodePropertyValueBool = bool;
alias NodePropertyValueEnum = string:256;

const uint8 MAX_OFFER_COUNT = 64;
const uint8 MAX_SYMBOL_COUNT = 64;
const uint8 MAX_PROPERTY_COUNT = 64;

const uint8 MAX_NODE_NAME_LENGTH = 128;
const uint8 MAX_SYMBOL_NAME_LENGTH = 128;

/// Definition of a symbol provided by a driver for a node. A symbol is local to
/// a driver host.
table NodeSymbol {
    /// Name of the symbol.
    1: string:MAX_SYMBOL_NAME_LENGTH name;

    /// Virtual address of the symbol, within a driver host's process.
    2: zx.vaddr address;
};

/// Definition of a property for a node. A property is commonly used to match a
/// node to a driver for driver binding.
table NodeProperty {
    /// Key for the property.
    1: uint32 key;

    /// Value for the property.
    2: uint32 value;
};

/// Arguments for adding a node.
table NodeAddArgs {
    /// Name of the node.
    1: string:MAX_NODE_NAME_LENGTH name;

    /// FIDL services to offer to the driver that is bound to this node.
    2: vector<fuchsia.component.name>:MAX_OFFER_COUNT offers;

    /// Functions to provide to the driver that is bound to this node.
    3: vector<NodeSymbol>:MAX_SYMBOL_COUNT symbols;

    /// Properties of the node.
    4: vector<NodeProperty>:MAX_PROPERTY_COUNT properties;
};

/// Protocol through which a parent node controls one of its children.
protocol NodeController {
    /// Removes the node and all of its children.
    Remove();
};

/// Protocol through which a driver manages a node that it is bound to.
protocol Node {
    /// Adds a child node to this node.
    ///
    /// If `node` is present, this driver takes responsibility for binding to
    /// the newly created child. Otherwise, the driver framework will locate an
    /// appropriate driver to bind the child to.
    AddChild(NodeAddArgs args,
             request<NodeController> controller,
             request<Node>? node);
};