src/diagnostics/inspect_validator/fidl/validate.test.fidl

// 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;

/// 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;
};

/// 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;
};

xunion Number {
    int64 int_t;
    uint64 uint_t;
    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 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 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;
};

/// Tells the puppet to do something to modify the VMO.
xunion Action {
    CreateNode create_node;
    DeleteNode delete_node;
    CreateNumericProperty create_numeric_property;
    CreateBytesProperty create_bytes_property;
    CreateStringProperty create_string_property;
    DeleteProperty delete_property;
    SetNumber set_number;
    SetString set_string;
    SetBytes set_bytes;
    AddNumber add_number;
    SubtractNumber subtract_number;
    CreateArrayProperty create_array_property;
    ArraySet array_set;
    ArrayAdd array_add;
    ArraySubtract array_subtract;
    CreateLinearHistogram create_linear_histogram;
    CreateExponentialHistogram create_exponential_histogram;
    Insert insert;
    InsertMultiple insert_multiple;
};

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

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