// 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.runner;
using fuchsia.data;
using fuchsia.io;
using fuchsia.url;
using zx;

const MAX_NAMESPACE_COUNT uint32 = fuchsia.component.runner.MAX_NAMESPACE_COUNT;

/// Contains the node properties that belong to a node.
@available(added=19)
type NodePropertyEntry = struct {
    /// Name of the node that has |node_properties|.
    name NodeName;

    /// Node properties that belong to the node whose name is |node_name|. If
    /// the node is a composite then |properties| is empty and does not contain
    /// its parents' properties.
    properties NodePropertyVector;
};

@available(added=19)
alias NodePropertyDictionary = vector<NodePropertyEntry>:MAX;

/// Arguments for starting a driver.
type DriverStartArgs = resource table {
    /// Node that the driver is bound to.
    1: node client_end:Node;

    /// The name of the node the driver is bound to.
    8: node_name string:MAX;

    /// Node properties of the node the driver is bound to. If the node is
    /// non-composite then the "default" entry will contain the node's own
    /// properties. If the node is a composite then there is an entry for each
    /// of its parents and the "default" entry will reference the primary
    /// composite parent node's properties.
    @available(added=19)
    9: node_properties NodePropertyDictionary;

    /// Symbols provided to the driver, for |node|. These come from the driver
    /// that added |node|, and are filtered to the symbols requested in the bind
    /// program.
    2: symbols vector<NodeSymbol>:MAX_SYMBOL_COUNT;

    /// URL of the package containing the driver. This is purely informational,
    /// used only to provide data for inspect.
    3: url fuchsia.url.Url;

    /// Information about the driver to start. Currently, we support the
    /// following entries:
    ///   1. "binary": a string containing the package-relative path to the
    ///      driver binary.
    ///   2. "colocate" (optional): a string containing "true" or "false"
    ///      specifying whether the driver should be colocated in the same
    ///      driver host as the driver that added |node|. If not specified, the
    ///      driver will be launched in a new driver host.
    ///   3. "default_dispatcher_opts" (optional): an array of strings specifying
    ///      the options for creating the default dispatcher. A string can be one
    ///      of the following:
    ///      * `allow_sync_calls`: allows synchronous calls to be done on the
    ///      default dispatcher's thread.
    ///   4. "default_dispatcher_scheduler_role" (optional): the scheduler role to
    ///      set for the default dispatcher created for the driver.
    4: program fuchsia.data.Dictionary;

    /// Incoming namespace provided to the driver.
    5: incoming vector<fuchsia.component.runner.ComponentNamespaceEntry>:MAX_NAMESPACE_COUNT;

    /// Outgoing directory served by the driver.
    6: outgoing_dir server_end:fuchsia.io.Directory;

    // TODO(https://fxbug.dev/42176642) add link to reference for the contents
    /// Configuration passed to the driver.
    7: config zx.Handle:VMO;
};