sdk/fidl/fuchsia.process.explorer/process_explorer.fidl

// Copyright 2022 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.process.explorer;

using zx;

@discoverable
open protocol Query {
    // Writes to `socket` a JSON containing process information as a
    // well-formed UTF-8 string with the following format:
    // {
    //     "Processes":[
    //         {
    //             "koid":1097,
    //             "name":"bin/component_manager",
    //             "objects":[
    //                 {
    //                     "type":17,
    //                     "koid":41903,
    //                     "related_koid":1033,
    //                     "peer_owner_koid":0
    //                 },
    //                 ...
    //             ]
    //         },
    //         ...
    //     ]
    // }
    //
    // The schema of this JSON data is depended upon by the ffx process command, which means
    // we need to keep the schema stable.
    flexible WriteJsonProcessesData(resource struct {
        socket zx.Handle:<SOCKET, zx.Rights.WRITE | zx.Rights.WAIT>;
    });

    // Writes to `socket` a JSON containing task hierarchy information as a
    // well-formed UTF-8 string with the following format:
    // {
    //     "Tasks":[
    //         {
    //             "koid":1097,
    //             "parent_koid":781,
    //             "name":"bin/component_manager",
    //             "type":"process"
    //         },
    //         ...
    //     ]
    // }
    //
    // The schema of this JSON data is depended upon by the ffx process command, which means
    // we need to keep the schema stable.
    flexible WriteJsonTaskHierarchyData(resource struct {
        socket zx.Handle:<SOCKET, zx.Rights.WRITE | zx.Rights.WAIT>;
    });
};

type Task = flexible union {
    1: job Job;
    2: process Process;
    3: thread Thread;
};

closed protocol TaskIterator {
    /// Intended to be called in a loop to retrieve all tasks.
    /// Will return a task with 0 elements to indicate iterator has been exhausted.
    strict GetTasks() -> (struct {
        tasks vector<Task>:MAX;
    }) error zx.Status;
};

type VmapType = flexible enum {
    NONE = 0;
    ASPACE = 1;
    VMAR = 2;
    MAPPING = 3;
};

type Vmap = table {
    1: name string:zx.MAX_NAME_LEN;
    2: base_address uint64;
    3: size uint64;
    4: depth uint64;
    5: type VmapType;
    /// Only set if |type| is `VmapType.MAPPING`.
    6: mapping Mapping;
};

type MmuFlags = flexible bits {
    READ = 0x0001;
    WRITE = 0x0002;
    EXECUTE = 0x0004;
};

type Mapping = table {
    1: mmu_flags MmuFlags;
    2: vmo_koid zx.Koid;
    3: vmo_offset uint64;
    4: committed_pages uint64;
};

@discoverable
open protocol ProcessExplorer {
    /// Errors will be propogated via epitaph on TaskIterator.
    flexible GetTaskInfo(resource table {
        1: iterator server_end:TaskIterator;
    });

    flexible GetHandleInfo(flexible union {
        /// Must be an exact match.
        1: process_name string:zx.MAX_NAME_LEN;
        /// Must be the koid for a process.
        2: koid zx.Koid;
    }) -> (struct {
        handle_info vector<Handle>:MAX;
    }) error zx.Status;

    flexible GetVmaps(flexible union {
        /// Must be an exact match.
        1: process_name string:zx.MAX_NAME_LEN;
        /// Must be the koid for a process.
        2: koid zx.Koid;
    }) -> (struct {
        vmaps vector<Vmap>:MAX;
    }) error zx.Status;

    flexible GetStackTrace(flexible union {
        /// Must be an exact match.
        1: process_name string:zx.MAX_NAME_LEN;
        /// Must be the koid for a process.
        2: koid zx.Koid;
    }) -> (struct {
        stack_trace string:MAX;
    }) error zx.Status;

    flexible KillTask(flexible union {
        /// Must be an exact match.
        1: process_name string:zx.MAX_NAME_LEN;
        /// May be the koid for a process or job.
        2: koid zx.Koid;
    }) -> (struct {
        koid zx.Koid;
    }) error zx.Status;
};