sdk/fidl/fuchsia.memory.inspection/inspection.fidl

// Copyright 2023 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=12)
library fuchsia.memory.inspection;

using zx;

/// Obtains the memory usage of a fuchsia device.
@discoverable
closed protocol Collector {
    /// Writes to `socket` a JSON capture of the memory usage and the memory
    /// bucket definition, as a well-formed UTF-8 string.
    /// The socket is closed by the server after all the data is written into
    /// it.
    ///
    /// TODO(https://fxbug.dev/42073090): Document the schema of the JSON.
    ///
    /// Sample output:
    /// {"Capture":
    ///      {
    ///        "Time":28477260758625,
    ///        "Kernel":{
    ///           "total":1610612736,
    ///           "free":170565632,
    ///           "wired":67395584,
    ///           "total_heap":30904320,
    ///           "free_heap":1873728,
    ///           "vmo":1276194816,
    ///           "mmu":65294336,
    ///           "ipc":196608,
    ///           "other":61440
    ///         },
    ///         "Processes":[
    ///           ["koid","name","vmos"],
    ///           [47325,"fonts.cm",[47353, ...]],
    ///           ...
    ///         ],
    ///         "VmoNames":["scudo:primary", ...],
    ///         "Vmos":[
    ///           ["koid","name","parent_koid","committed_bytes","allocated_bytes"],
    ///           [47440,38,47437,4096,4096],
    ///           ...
    ///         ]
    ///      }
    ///   "Buckets":
    ///      [
    ///         {
    ///            "event_code": 29,
    ///            "name": "BlobfsInactive",
    ///            "process": "blobfs\\.cm",
    ///            "vmo": "inactive-blob-.*"
    ///         },
    ///         ...
    ///      ]
    /// }
    ///
    ///  For size reasons:
    ///    - Processes and Vmos have an initial entry that contains the names of the the fields in
    ///      the rest of the entries.
    ///    - The names of the VMOs are an index into the VMONames array.
    @available(deprecated=14, note="Use CollectJsonStatsWithOptions instead")
    strict CollectJsonStats(resource struct {
        socket zx.Handle:<SOCKET, zx.Rights.WRITE | zx.Rights.WAIT>;
    });

    // See |CollectJsonStats| for details.
    @available(added=14)
    strict CollectJsonStatsWithOptions(resource table {
        // Mandatory. Socket used to return the requested statistics in JSON format.
        1: socket zx.Handle:<SOCKET, zx.Rights.WRITE | zx.Rights.WAIT>;
        // Optional. Also include starnix processes in the output. This may make this call much
        // slower. Defaults to false.
        2: include_starnix_processes bool;
    });
};