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

/// The Inspect VMO Validator program starts and controls a "puppet" program to
/// exercise each Inspect library. This file defines the protocol to exercise
/// the library (and report the result of commands). (After executing some
/// commands, the Validator program will analyze the VMO contents for
/// correctness and memory-packing efficiency.)
library test.inspect.validate;

using fuchsia.inspect as inspect;

/// InitializationParams tells how to initialize the Inspect library.
table InitializationParams {
    1: uint64 vmoSize;
};

/// TestResult tells the result of executing an Initialize or Act command.
enum TestResult {
    /// The function call completed without error.
    OK = 0;
    /// The Inspect library doesn't implement a requested feature.
    UNIMPLEMENTED = 1;
    /// The Inspect library reported a failure executing the function.
    FAILED = 2;
    /// The driver and/or puppet-wrapper was in an illegal state.
    ILLEGAL = 3;
};

// One-to-one mapping flag used in LINK block
enum LinkDisposition {
    CHILD = 0;
    INLINE = 1;
};

/// The data in the VMO is tree-structured, and
/// ROOT_ID identifies the (virtual) root node.
const uint32 ROOT_ID = 0;

/// Tells the puppet to create a Node with the given name, parentage, and ID
/// (the id is specified so other nodes can later be created under it).
struct CreateNode {
    uint32 parent;
    uint32 id;
    string name;
};

/// Tells the puppet to delete the given node.
struct DeleteNode {
    uint32 id;
};

enum NumberType : uint8 {
    INT = 1;
    UINT = 2;
    DOUBLE = 3;
};

flexible union Number {
    1: int64 int_t;
    2: uint64 uint_t;
    3: float64 double_t;
};

/// Tells the puppet to create a property with the given numeric value.
struct CreateNumericProperty {
    uint32 parent;
    uint32 id;
    string name;
    Number value;
};

/// Tells the puppet to create a property with the given byte array value.
struct CreateBytesProperty {
    uint32 parent;
    uint32 id;
    string name;
    vector<uint8> value;
};

/// Tells the puppet to create a property with the given string value.
struct CreateStringProperty {
    uint32 parent;
    uint32 id;
    string name;
    string value;
};

/// Tells the puppet to create a property with the given bool value.
struct CreateBoolProperty {
    uint32 parent;
    uint32 id;
    string name;
    bool value;
};

/// Tells the puppet to delete an existing property.
struct DeleteProperty {
    uint32 id;
};

struct AddNumber {
    uint32 id;
    Number value;
};

struct SubtractNumber {
    uint32 id;
    Number value;
};

struct SetNumber {
    uint32 id;
    Number value;
};

struct SetBytes {
    uint32 id;
    vector<uint8> value;
};

struct SetString {
    uint32 id;
    string value;
};

struct SetBool {
    uint32 id;
    bool value;
};

struct CreateArrayProperty {
    uint32 parent;
    uint32 id;
    string name;
    uint64 slots;
    NumberType number_type;
};

struct ArraySet {
    uint32 id;
    uint64 index;
    Number value;
};

struct ArrayAdd {
    uint32 id;
    uint64 index;
    Number value;
};

struct ArraySubtract {
    uint32 id;
    uint64 index;
    Number value;
};

struct CreateLinearHistogram {
    uint32 parent;
    uint32 id;
    string name;
    Number floor;
    Number step_size;
    uint64 buckets;
};

struct CreateExponentialHistogram {
    uint32 parent;
    uint32 id;
    string name;
    Number floor;
    Number initial_step;
    Number step_multiplier;
    uint64 buckets;
};

struct Insert {
    uint32 id;
    Number value;
};

struct InsertMultiple {
    uint32 id;
    Number value;
    uint64 count;
};

// Action sent to instruct a Puppet to create a lazy node.
// TODO(fxbug.dev/49114): This should be modified to allow for creating lazy nodes past 1-level deep.
struct CreateLazyNode {
    // Unique id for parent block.
    uint32 parent;

    // Unique id used between Controller and Puppet to uniquely identify lazy node.
    uint32 id;

    // Name passed in to CreateLazy{Node,Values) method
    string name;

    // Disposition flag that determines appropriate method.
    LinkDisposition disposition;

    // Send a sequence of actions to execute within the lambda to create Inspect
    // tree.
    vector<Action> actions;
};

// Action sent to instruct a Puppet to delete a lazy node.
struct DeleteLazyNode {
    // Unique id used between Controller and Puppet to uniquely identify lazy node.
    uint32 id;
};

/// Tells the puppet to do something to modify the VMO.
flexible union Action {
    1: CreateNode create_node;
    2: DeleteNode delete_node;
    3: CreateNumericProperty create_numeric_property;
    4: CreateBytesProperty create_bytes_property;
    5: CreateStringProperty create_string_property;
    6: DeleteProperty delete_property;
    7: SetNumber set_number;
    8: SetString set_string;
    9: SetBytes set_bytes;
    10: AddNumber add_number;
    11: SubtractNumber subtract_number;
    12: CreateArrayProperty create_array_property;
    13: ArraySet array_set;
    14: ArrayAdd array_add;
    15: ArraySubtract array_subtract;
    16: CreateLinearHistogram create_linear_histogram;
    17: CreateExponentialHistogram create_exponential_histogram;
    18: Insert insert;
    19: InsertMultiple insert_multiple;
    20: CreateBoolProperty create_bool_property;
    21: SetBool set_bool;
};

/// Tells the puppet to do something to modify a lazy node.
flexible union LazyAction {
    1: CreateLazyNode create_lazy_node;
    2: DeleteLazyNode delete_lazy_node;
};

[Discoverable]
protocol Validate {
    /// Initializes the Inspect library being tested by the puppet.
    Initialize(InitializationParams params) -> (handle? vmo, TestResult result);

    /// Use instead of `Initialize` on puppets which support the Tree / Lazy method of getting VMOs.
    /// The root VMO can be obtained via the returned Tree protocol.
    [Transitional]
    InitializeTree(InitializationParams params) -> (inspect.Tree? tree, TestResult result);

    /// Instruct the puppet to expose its current data in its out/diagnostics directory.
    ///
    /// Note: It is an error for more than one Validate connection to
    /// Publish at once. Unpublish must be called to cleanup.
    [Transitional]
    Publish() -> (TestResult result);

    /// Instruct the puppet to unpublish any data it currently has present in out/diagnostics.
    [Transitional]
    Unpublish() -> (TestResult result);

    /// Modifies the contents of the VMO.
    Act(Action action) -> (TestResult result);

    /// Modifies the contents of a lazy node.
    [Transitional]
    ActLazy(LazyAction lazy_action) -> (TestResult result);
};