// Copyright 2024 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.memory.attribution;

using zx;

/// Provides memory attribution information under this principal.
///
/// The typical expected usage of this protocol is:
///  - Component Runners implement this protocol and declare it in their
///    manifest.
///  - A Component that wants to provide extra internal information may also
///    declare and implement this protocol;
///  - Clients connect to a `Provider`, and use the `Get` methods to
///    recursively explore the Principal hierarchy.
///
/// Clients will typically maintain the connection and start a hanging get to
/// retrieve attribution information. Runners need to inspect the manifest of
/// their runnees to determine if they serve this protocol, and proactively
/// create the connection. They can also proxy this protocol in case their
/// runnee provides attribution information in an unsuitable format.
// TODO(https://fxbug.dev/307580082): This protocol is under construction.
@discoverable
open protocol Provider {
    /// Returns the attribution information known to the provider.
    ///
    /// The first call returns immediately with the current information.
    /// Subsequent calls will be held if no additional information is
    /// available, and return only when there are changes to the attribution
    /// information to be reported.
    ///
    /// Runners will typically report the kernel resources (e.g. job, process,
    /// etc) associated with each component that they are responsible for
    /// running.
    ///
    /// Components may optionally report resource usage by different categories
    /// within their implementation.
    Get() -> (resource table {
        1: attributions vector<AttributionUpdate>:MAX;
    }) error Error;
};

type Error = flexible enum : uint32 {
    /// Internal error within the principal.
    INTERNAL = 1;
};

/// Describes a change affecting attribution of resources to a single principal.
type AttributionUpdate = flexible resource union {
    /// Reports a new principal managed by the reporter.
    ///
    /// Declaring a Principal means that the declarer/reporter is providing the
    /// resources for the Principal to run. Typically, Component Framework
    /// Runners will declare the components they run as Principals.
    1: add NewPrincipal;

    /// Replaces the attribution information for a Principal.
    ///
    /// When this is received, the client is should discard any attribution
    /// information received by this channel for the Principal, and replace it
    /// with this information.
    2: update UpdatedPrincipal;

    /// Removes a Principal.
    ///
    /// Declares that a Principal is no longer active on the system. All
    /// attribution information for this Principal can be removed after this
    /// message. Any remaining resources will still be attributed according to
    /// the default attribution rules.
    3: remove Identifier;
};

/// Represents a newly added principal.
type NewPrincipal = resource table {
    /// The identifier of this principal.
    1: identifier Identifier;

    /// The type of the principal.
    2: type flexible enum : uint32 {
        /// An independent unit of computation that can be described as
        /// running, such as a component or an application.
        ///
        /// Runnable principals will be shown in the default memory view.
        RUNNABLE = 1;

        /// A part of another principal that isn't independent, such as a
        /// cache.
        ///
        /// Part principals will be shown in the detailed memory view of the
        /// principal they are a part of.
        PART = 2;
    };

    /// If this principal provides attribution information, a channel to its
    /// provider.
    3: detailed_attribution client_end:<Provider>;
};

/// The complete set of Resources used by a Principal.
///
/// Upon receiving this message, the previous set of Resources attributed to the identified
/// Principal by this connection should be replaced. If, on another connection, another
/// Provider attributed resources to this principal, these attributions should be kept.
type UpdatedPrincipal = resource table {
    /// The name of this principal.
    1: identifier Identifier;

    /// The resources owned by this principal.
    ///
    /// If the size of the Resource vector is too big to fit in a FIDL message, `buffer` should
    /// contain a serialized vector of Resources.
    2: resources flexible resource union {
        1: data vector<Resource>:MAX;

        /// buffer is read-only.
        2: buffer zx.Handle:VMO;
    };
};

type Resource = flexible union {
    /// Identifies a kernel object whose memory is being attributed.
    ///
    /// Refers to all memory held by VMOs reachable from the object
    /// (currently a Job, Process or VMO).
    1: kernel_object zx.Koid;
};

/// [`Identifier`] identifies a principal.
type Identifier = flexible resource union {
    /// Represents the principal sending the claim. This is useful for a runner
    /// to claim a resource that is also shared with one of its children.
    1: self struct {};

    /// Token identifying the component instance run by this principal.
    ///
    /// This is the token defined in the component_instance field of
    /// fuchsia.component.runner.ComponentStartInfo.
    2: component zx.Handle:EVENT;

    /// A subpart of a component, which isn't a fully-blown Component within
    /// Component Framework but still represents a coherent unit of
    /// computation. This can be, for instance, a Linux process under Starnix.
    ///
    /// This name needs to be unique within the component this principal is
    /// part of.
    3: part string:MAX;
};