// Copyright 2022 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.tracing.perfetto;

using fuchsia.io;
using zx;

/// An interface for exchanging trace data buffers between Providers and the
/// system tracing service.
closed protocol BufferReceiver {
    /// Sends a file to be used as a trace buffer.
    /// The file must support writable mmap() access.
    @available(added=9)
    strict ProvideBuffer(resource struct {
        buffer client_end:fuchsia.io.File;
    }) -> () error zx.Status;

    /// Called by the system tracing service, to provide a trace buffer
    /// to the Perfetto Producer. The buffer size is specified via
    /// the `ZX_PROP_VMO_CONTENT_SIZE` handle property.
    /// The Producer will invoke the callback when the buffer is
    /// received. The system tracing service must wait until the callback
    /// is signaled before continuing with trace session setup.
    /// Method should be called only once per BufferReceiver connection.
    /// The channel may be safely dropped once a buffer is received.
    @available(replaced=9)
    strict ProvideBuffer(resource struct {
        buffer zx.Handle:VMO;
    }) -> () error zx.Status;
};

/// Specifies how the trace buffer should be exchanged.
type TraceBuffer = strict resource union {
    /// Used to receive the trace buffer from the system tracing service.
    1: from_server client_end:<BufferReceiver>;
};

/// Interface for creating connections between Perfetto "Producers" and
/// a shared Perfetto service.
/// To learn more about Perfetto, see: https://www.perfetto.dev/docs/
/// and https://perfetto.dev/docs/concepts/service-model .
@discoverable
closed protocol ProducerConnector {
    /// Connects a Perfetto Producer to the Perfetto backend. Both sides
    /// will communicate over `producer_socket` using Perfetto's internal
    /// wire format "ProducerPort" (see
    /// //third_party/perfetto/protos/perfetto/ipc/producer_port.proto).
    ///
    /// `trace_buffer` either provides a buffer for communicating trace data
    /// from the client, or an interface for receiving a buffer from the
    /// server, depending on the client's needs.
    ///
    /// The lifetime of `producer_socket` may outlive the connection lifetime
    /// of ProducerConnector.
    /// Multiple Producers may be connected simultaneously.
    // TODO(https://fxbug.dev/42166474): Define error conditions and status codes.
    strict ConnectProducer(resource struct {
        producer_socket zx.Handle:SOCKET;
        buffer TraceBuffer;
    }) -> () error zx.Status;
};