// Copyright 2020 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.

library fuchsia.fuzzer;

using zx;

/// Details about an instrumented process.
///
/// See also:
///
/// * https://fuchsia.dev/fuchsia-src/reference/syscalls/object_get_info#zx_info_task_stats
/// * https://fuchsia.dev/fuchsia-src/reference/syscalls/object_get_info#zx_info_task_runtime
type ProcessStats = struct {
    /// The kernel object identifier of the task.
    koid uint64;

    /// The total size of mapped memory ranges in this process.
    mem_mapped_bytes uint64;

    /// Committed memory that is only mapped into this process.
    mem_private_bytes uint64;

    /// Committed memory that is mapped into this and at least one other
    /// process.
    mem_shared_bytes uint64;

    /// Estimate of how much of |mem_shared_bytes| that this process owns.
    mem_scaled_shared_bytes uint64;

    /// The total amount of time this process was running on a CPU and not
    /// blocked.
    cpu_time zx.Duration;

    /// The total amount of time this process was ready but not actually using a
    /// CPU.
    queue_time zx.Duration;

    /// The total amount of time this process spent handling page faults.
    page_fault_time zx.Duration;

    /// The total amount of time this process spent waiting on contended kernel
    /// locks.
    lock_contention_time zx.Duration;
};

/// See `Controller.Monitor`. Used to indicate why an update was sent.
type UpdateReason = flexible enum : uint8 {
    /// Represents an otherwise unspecified update. Useful when integrating
    /// other engines as runners, e.g. libFuzzer.
    MISC = 1;

    /// A fuzzing action is starting. See, e.g. `Controller.Fuzz`,
    /// `Controller.Merge`, etc.
    INIT = 2;

    /// An input produced new feedback.
    NEW = 3;

    /// Periodic status update, configured with `Options.pulse_interval`.
    PULSE = 4;

    /// A shorter input for some particular feedback has been found.
    REDUCE = 5;

    /// A fuzzing action is complete.
    DONE = 6;
};

/// The maximum number of processes for which stats will be returned via
/// `Status`.
const MAX_PROCESS_STATS uint16 = 256;

/// See `Controller.GetStatus`.
//
// TODO(https://fxbug.dev/42074956): Include workflow enum.
type Status = table {
    /// True if the fuzzer is working on a commands, e.g. it is fuzzing.
    1: running bool;

    /// Number of runs performed so far.
    2: runs uint32;

    /// Time spent so far.
    3: elapsed zx.Duration;

    /// Number of program edges covered so far.
    4: covered_pcs uint64;

    /// Number of opaque features encountered so far.
    5: covered_features uint64;

    /// Number of inputs in the "live" corpus.
    6: corpus_num_inputs uint64;

    /// Total size of the inputs in the "live" corpus.
    7: corpus_total_size uint64;

    /// Information about the instrumented processes attached to the engine.
    8: process_stats vector<ProcessStats>:MAX_PROCESS_STATS;
};

/// See `Status`. This protocol is used to push status from the `Controller` to
/// callers.
closed protocol Monitor {
    /// Sends the current status.
    ///
    /// + request `reason` the cause of a status change.
    /// + status `status` the reported fuzzing metrics.
    strict Update(struct {
        reason UpdateReason;
        status Status;
    }) -> ();
};