sdk/fidl/fuchsia.memory.stacktrack.client/client.fidl

// Copyright 2026 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.stacktrack.client;

using zx;

const MAX_BUILD_ID_LENGTH uint32 = 32;

/// The reason why a method failed.
type CollectorError = flexible enum {
    /// The given ProcessSelector value is not supported.
    PROCESS_SELECTOR_UNSUPPORTED = 1;

    /// The given ProcessSelector value does not match any process.
    PROCESS_SELECTOR_NO_MATCH = 2;

    /// The given ProcessSelector value matches more than one process but the
    /// requested operation needs a unique match.
    PROCESS_SELECTOR_AMBIGUOUS = 3;

    /// Failed to get stack traces.
    GET_STACK_TRACES_FAILED = 4;
};

/// Filter to restrict an operation to a subset of the available processes.
type ProcessSelector = flexible union {
    /// Matches any process with the given ZX_PROP_NAME.
    1: by_name string:zx.MAX_NAME_LEN;

    /// Matches the process with the given koid.
    2: by_koid zx.Koid;
};

/// A level in the call stack.
type CallFrame = struct {
    /// The program counter (PC) corresponding to this frame.
    program_address uint64;

    /// The value of the frame pointer (FP) register for this frame.
    frame_pointer uint64;
};

/// A stack trace and the identifier of the thread it belongs to.
type StackTrace = table {
    /// The koid of the thread.
    1: thread_koid zx.Koid;

    /// The stack frames, listed bottom-to-top.
    ///
    /// The first frame has the lowest frame pointer (FP) value, and subsequent
    /// frames have increasing FPs. The difference between the FP of the last
    /// frame and the FP of the first frame represents the (approximate) overall
    /// stack size consumed by this trace.
    2: frames vector<CallFrame>:MAX;
};

/// An ELF build ID.
type BuildId = struct {
    value vector<uint8>:MAX_BUILD_ID_LENGTH;
};

/// A memory region containing code loaded from an ELF file.
type ExecutableRegion = table {
    /// The address of the memory region.
    1: address uint64;

    /// Region size, in bytes.
    2: size uint64;

    /// The build ID of the ELF file.
    3: build_id BuildId;

    /// The address of the memory region relative to the file's load address.
    4: vaddr uint64;

    /// Description of the memory region (e.g. ELF soname or VMO name).
    5: name string:MAX;
};

/// An element that is part of a snapshot.
type SnapshotElement = flexible union {
    1: page_size uint64;
    2: stack_trace StackTrace;
    3: executable_region ExecutableRegion;
};

/// Protocol to transmit snapshot(s) as a stream of elements.
closed protocol SnapshotReceiver {
    /// Delivers a batch of snapshot elements.
    strict Batch(struct {
        batch vector<SnapshotElement>:MAX;
    }) -> ();

    /// Reports an error. No other batches or errors will follow.
    strict ReportError(struct {
        error CollectorError;
    }) -> ();
};

@discoverable
open protocol Collector {
    /// Returns stack traces for the specified process.
    flexible GetStackTraces(resource table {
        /// The process to gather data about.
        ///
        /// If not set, any process will be considered a match.
        1: process_selector ProcessSelector;

        /// The receiver that will accept the stack traces.
        ///
        /// Required.
        2: receiver client_end:SnapshotReceiver;
    });
};