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