blob: fb0abd96d38e32200f6be2e50db9528e67568053 [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 MAX_TREE_NAME_LENGTH uint64 = 2040;
/// Maximum number of children returned by a single read of the tree name iterator.
const MAX_TREE_NAME_LIST_SIZE uint64 = 64;
alias TreeName = string:MAX_TREE_NAME_LENGTH;
/// The content of a specific Inspect Tree.
type TreeContent = resource table {
/// Buffer containing the bytes of a tree in Inspect format.
1: buffer fuchsia.mem.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() -> (struct {
name vector<TreeName>:MAX_TREE_NAME_LIST_SIZE;
/// 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() -> (resource struct {
content TreeContent;
/// 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(resource struct {
tree_iterator server_end:TreeNameIterator;
/// Open a child Tree by name.
/// If the child cannot be opened, the given request is closed.
OpenChild(resource struct {
child_name TreeName;
tree server_end:Tree;