sdk/fidl/fuchsia.debugdata/debugdata.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.
library fuchsia.debugdata;

using zx;

/// The maximum length, in bytes, of data sink or configuration name.
/// TODO(mcgrathr): Align this with file name limits in some fs protocol.
const MAX_NAME uint64 = 1024;

/// DebugData defines the interface for instrumentation configuration and data
/// publishing.
@for_deprecated_c_bindings
@discoverable
protocol DebugData {
    /// The program runtime sends a string naming a `data_sink` and transfers
    /// the sole handle to a VMO containing the `data` it wants published
    /// there.  The `data_sink` string identifies a type of data, and the
    /// VMO's object name can specifically identify the data set in this VMO.
    /// The ZX_PROP_VMO_CONTENT_SIZE property should be set on the VMO to
    /// indicate the precise size of the data in case that is not whole pages;
    /// however, leaving it unset (i.e. 0) is acceptable when the whole-page
    /// size of the VMO is the intended size of dump.  The client must
    /// transfer the only handle to the VMO (which prevents the VMO being
    /// resized without the receiver's knowledge), but it might still have the
    /// VMO mapped in and continue to write data to it.  Code instrumentation
    /// runtimes use this to deliver large binary trace results. In such cases,
    /// the client should use the `vmo_token` channel to signal when the VMO
    /// is ready for processing by the recipient.  The receiver will not
    /// process the VMO until the `vmo_token` channel is closed. Therefore,
    /// the client should retain the `vmo_token` channel until it has
    /// completed all writes to the VMO.
    Publish(resource struct {
        data_sink string:MAX_NAME;
        data zx.handle:VMO;
        vmo_token server_end:DebugDataVmoToken;
    });

    /// The program runtime names a `config_name` referring to a debug
    /// configuration of some kind and gets back a VMO to read configuration
    /// data from.  The sanitizer runtimes use this to allow large options
    /// text to be stored in a file rather than passed directly in environment
    /// strings.
    LoadConfig(struct {
        config_name string:MAX_NAME;
    }) -> (resource struct {
        config zx.handle:<VMO, optional>;
    });
};

/// DebugDataVmoToken is an empty protocol used by a client calling
/// `DebugData.Publish` to indicate when the reciever may begin processing a
/// VMO. See `DebugData.Publish` for more details.
protocol DebugDataVmoToken {};