| // 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; |
| }; |