blob: 73dd7662c44d08d3c5408dac5ea4a2392d78302b [file] [log] [blame]
// 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.
library fuchsia.inspect;
using fuchsia.mem;
/// Maximum length of an Inspect Tree, specified by the format.
const uint64 MAX_TREE_NAME_LENGTH = 2040;
/// Maximum number of children returned by a single read of the tree name iterator.
const uint64 MAX_TREE_NAME_LIST_SIZE = 64;
using TreeName = string:MAX_TREE_NAME_LENGTH;
/// The content of a specific Inspect Tree.
table TreeContent {
/// Buffer containing the bytes of a tree in Inspect format.
1: fuchsia.mem.Buffer buffer;
/// Iterator protocol for listing the names of children of a particular Tree.
protocol TreeNameIterator {
/// Get the next batch of names.
/// Returns an empty vector and closes the channel when no more names are present.
/// Implementors may eagerly close the channel after sending the last batch.
GetNext() -> (vector<TreeName>:MAX_TREE_NAME_LIST_SIZE name);
/// The Tree protocol represents a hierarchy of Inspect VMOs.
/// Link values stored in an Inspect file contain references to new
/// named files that contain a continuation of the data for the overall
/// hierarchy. Protocol Tree allows clients to request these named files so
/// long as the hosting component is still alive.
/// Connecting to a particular tree keeps the content for that Tree resident
/// in memory. Clients are recommended to traverse the trees in depth-first
/// order to reduce memory usage. Serving components are free to deny
/// connections to avoid unbounded memory usage.
protocol Tree {
/// Get the content for the Inspect VMO backing this tree.
/// So long as the Tree connection is still maintained, the contents
/// of the tree are guaranteed to still be live. Once the connection is
/// lost, the serving component is free to clear the contents of returned
/// shared buffers.
/// Serving components may return different buffers to GetContent
/// requests for the same Tree.
GetContent() -> (TreeContent content);
/// Iterate over the names of Trees that are children of this Tree.
/// The underlying list of children may change in between calls to
/// ListChildNames and OpenChild.
ListChildNames(request<TreeNameIterator> tree_iterator);
/// Open a child Tree by name.
/// If the child cannot be opened, the given request is closed.
OpenChild(TreeName child_name, request<Tree> tree);