// Copyright 2016 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.controller;

// The controller interface used by the trace tool to start/stop tracing.
[Discoverable]
protocol Controller {
    // Requests to start tracing with the specified |options|.
    //
    // The trace controller acknowledges the request when all
    // registered providers have been started or after |options.start_timeout_milliseconds| milliseconds.
    //
    // The trace controller emits trace data to |output| as a sequence of
    // binary formatted trace records.  Traces obtained from different providers
    // are delimited by metadata records within the stream.
    //
    // The trace controller is responsible for lightly validating the structure of
    // trace records as it copies them from trace buffers into the output.
    // In particular, it must verify the size of each record header to ensure
    // that the framing of trace records in the data stream is maintained.
    //
    // The trace controller does not validate the contents of the trace records
    // themselves.  For example, it should not try to check argument lengths in
    // events.  This ensures that the trace format can be extended without needing
    // to modify the trace controller.
    StartTracing(TraceOptions options, handle<socket> output) -> ();

    // Requests to stop tracing.
    //
    // The trace controller continues to transfer any remaining data to the
    // output until finished, then closes the output.
    StopTracing();

    // Gets the known categories.
    GetKnownCategories() -> (vector<KnownCategory> categories);
};

struct KnownCategory {
    string:100 name;
    string description;
};

// This is a copy of tracelink.fidl:BufferingMode.
enum BufferingMode : uint8 {
    ONESHOT = 0;
    CIRCULAR = 1;
    STREAMING = 2;
};

// Individual providers can be tuned with this.
table ProviderSpec {
    1: string:100 name;
    2: uint32 buffer_size_megabytes_hint;
};

/// Provides options for the trace.
table TraceOptions {
    /// The trace categories to record, or an empty array for all.
    1: vector<string:100>:100 categories;

    /// Suggested size of trace buffer which each provider should receive.
    // TODO(FIDL-609): Default to 4.
    2: uint32 buffer_size_megabytes_hint;

    /// Acknowledge start request after at most |start_timeout_milliseconds|.
    // TODO(FIDL-609): Default to 5000.
    3: uint64 start_timeout_milliseconds;

    // TODO(FIDL-609), TODO(FIDL-486): Default to BufferingMode.ONESHOT.
    4: BufferingMode buffering_mode;

    /// Overrides for particular providers.
    5: vector<ProviderSpec>:100 provider_specs;
};