sdk/fidl/fuchsia.hardware.interconnect/interconnect.fidl

// Copyright 2025 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.hardware.interconnect;

using zx;

/// The longest allowed length for an interconnect or node name.
const NAME_MAX_LENGTH uint32 = 64;
/// The largest allowed number of edges from one node to another.
const EDGES_MAX uint32 = 64;

type BandwidthRequest = table {
    1: average_bandwidth_bps uint64;
    2: peak_bandwidth_bps uint64;
};

type NodeBandwidth = table {
    /// Unique ID that refers to the node this bandwidth is requested for.
    1: node_id uint32;
    /// Set of requests for all edges to this node.
    2: requests vector<BandwidthRequest>:EDGES_MAX;
};

type AggregatedBandwidth = table {
    /// Unique ID that refers to the node this bandwidth is requested for.
    1: node_id uint32;
    /// The computed aggregate average bandwidth value, derived from requests.
    2: average_bandwidth_bps uint64;
    /// The computed aggregate peak bandwidth value, derived from requests.
    3: peak_bandwidth_bps uint64;
};

type Node = table {
    /// Unique ID that refers to this node in other structs.
    1: id uint32;
    /// The name of the node.
    2: name string:NAME_MAX_LENGTH;
    /// An optional name of the interconnect the node lives on.
    3: interconnect_name string:NAME_MAX_LENGTH;
    /// Optional average bandwidth value to start with. If not provided, defaults to 0.
    4: initial_avg_bandwidth_bps uint64;
    /// Optional peak bandwidth value to start with. If not provided, defaults to 0.
    5: initial_peak_bandwidth_bps uint64;
};

type Edge = table {
    /// Source where bus traffic may originate.
    1: src_node_id uint32;
    /// Destination where bus traffic may travel to.
    2: dst_node_id uint32;
    /// An optional weight to apply to the edge. Used for calculating the optimal
    /// path from between two nodes. If there are multiple paths from one node to
    /// another, the path will be calculated by optimizing for the smallest sum of
    /// all edge weights along the path. If not provided, the weight is assumed to
    /// be 1.
    3: weight uint32;
};

type PathEndpoints = table {
    /// Name for the path which is used for binding.
    1: name string:NAME_MAX_LENGTH;
    /// Id for the path which is used for binding.
    2: id uint32;
    /// Source where bus traffic may originate.
    3: src_node_id uint32;
    /// Destination where bus traffic may travel to.
    4: dst_node_id uint32;
};

@serializable
type Metadata = table {
    /// Paths need not be between adjacent nodes, but a valid path from source node
    /// to destination node must exist in the node graph.
    1: paths vector<PathEndpoints>:MAX;
};

@discoverable(client="platform", server="external")
open protocol Device {
    flexible SetNodesBandwidth(struct {
        nodes vector<NodeBandwidth>:MAX;
    }) -> (struct {
        aggregated_bandwidth vector<AggregatedBandwidth>:MAX;
    }) error zx.Status;

    /// Returns a list of all nodes and edges between those nodes.
    /// Edges are directional, so if an interconnect allows bidirectional traffic,
    /// it should be listed twice, once for each direction of traffic flow.
    /// Edges must only be specified for directly adjacent nodes.
    flexible GetNodeGraph() -> (struct {
        nodes vector<Node>:MAX;
        edges vector<Edge>:MAX;
    });

    /// The paths within the interconnect node graph which see bus traffic
    /// and need to have constraints applied to by drivers. Each path will have
    /// a device node instantiated for it.
    flexible GetPathEndpoints() -> (struct {
        /// Paths need not be between adjacent nodes, but a valid path from source node
        /// to destination node must exist in the node graph.
        paths vector<PathEndpoints>:MAX;
    });
};

service Service {
    device client_end:Device;
};

/// Represents a path from a node in one interconnect to another.
@discoverable(client="external", server="platform")
open protocol Path {
    /// Sets the bandwidth interconnect path.
    flexible SetBandwidth(BandwidthRequest) -> () error zx.Status;
};

service PathService {
    path client_end:Path;
};