// 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;

using fuchsia.tracing;
using zx;

/// The maximum number of providers supported.
const MAX_NUM_PROVIDERS uint32 = 100;

/// The maximum length of an alert name.
const MAX_ALERT_NAME_LENGTH uint32 = 14;

/// aliases
alias AlertName = string:MAX_ALERT_NAME_LENGTH;

/// The state of the tracing session.
/// A "session" is everything between `Initialize` and `Terminate`.
type SessionState = flexible enum {
    /// The tracing system is ready for a new session.
    /// There can be only one session at a time.
    READY = 1;
    /// A new tracing session has been initialized.
    INITIALIZED = 2;
    /// Tracing is in the midst of starting.
    STARTING = 3;
    /// Tracing has started.
    STARTED = 4;
    /// Tracing is in the midst of being stopped.
    STOPPING = 5;
    /// Tracing has fully stopped.
    STOPPED = 6;
    /// Tracing is in the midst of being terminated.
    /// Once the system has completely terminated the session it goes back
    /// to the READY state.
    TERMINATING = 7;
};

/// The controller interface used by the trace tool to initialize/start/stop/terminate tracing.
///
/// The trace controller may lightly validate the structure of
/// trace records as it copies them from trace buffers into the output.
/// In particular, it may 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 does not try to check argument lengths in
/// events.  This ensures that the trace format can be extended without needing
/// to modify the trace controller.
@discoverable
protocol Controller {
    /// Requests to initialize tracing with the specified `config`.
    ///
    /// A bad request will terminate the connection.
    ///
    /// 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.
    flexible InitializeTracing(resource struct {
        config TraceConfig;
        output zx.Handle:SOCKET;
    });

    /// Requests to terminate tracing.
    ///
    /// If tracing has not yet stopped it is stopped first.
    /// If `options.write_results` is true, then the trace controller
    /// continues to transfer any remaining data to the output socket
    /// until finished, then closes the output.
    flexible TerminateTracing(struct {
        options TerminateOptions;
    }) -> (struct {
        result TerminateResult;
    });

    /// Requests to start tracing with the specified `options`.
    ///
    /// If tracing has already started then the request is ignored,
    /// except to send back an error code.
    ///
    /// The trace controller acknowledges the request when all
    /// registered providers have been started or after
    /// `TraceConfig.start_timeout_milliseconds` milliseconds.
    /// One useful reason for the has-started acknowledgement is that the
    /// trace program can start a program to trace knowing that all the
    /// providers are started.
    flexible StartTracing(struct {
        options StartOptions;
    }) -> () error StartErrorCode;

    /// Requests to stop tracing.
    ///
    /// If tracing has already stopped then this does nothing.
    /// Returning a result lets callers know when it's ok to, for example,
    /// start tracing again.
    flexible StopTracing(struct {
        options StopOptions;
    }) -> ();

    /// Return the set of registered providers.
    flexible GetProviders() -> (struct {
        providers vector<ProviderInfo>:MAX_NUM_PROVIDERS;
    });

    // Gets the known categories.
    flexible GetKnownCategories() -> (struct {
        categories vector<fuchsia.tracing.KnownCategory>:fuchsia.tracing.MAX_NUM_KNOWN_CATEGORIES;
    });

    /// Event sent when the session state changes.
    flexible -> OnSessionStateChange(struct {
        state SessionState;
    });

    /// Returns the next alert when it arrives.
    flexible WatchAlert() -> (struct {
        alert_name AlertName;
    });
};

// Individual providers can be tuned with this.
type ProviderSpec = table {
    1: name fuchsia.tracing.ProviderName;
    2: buffer_size_megabytes_hint uint32;
    3: categories fuchsia.tracing.EnabledCategoryList;
};

/// Provides options for the trace.
type TraceConfig = table {
    /// The trace categories to record, or an empty array for all.
    1: categories fuchsia.tracing.EnabledCategoryList;

    /// Suggested size of trace buffer which each provider should receive.
    // If table defaults were supported, this would default to 4.
    2: buffer_size_megabytes_hint uint32;

    /// Acknowledge start request after at most `start_timeout_milliseconds`.
    // If table defaults were supported, this would default to 5000.
    3: start_timeout_milliseconds uint64;

    // If table defaults were supported, this would default to BufferingMode.ONESHOT.
    4: buffering_mode fuchsia.tracing.BufferingMode;

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

/// Options to be passed with the TerminateTracing request.
/// This determines whether any pending data is written to the output
/// socket before it is closed.
type TerminateOptions = table {
    /// If true then write trace results.
    /// If false then discard trace results.
    1: write_results bool;
};

/// Statistics data per provider collected over the course of the tracing session
/// that is returned once the session is terminated.
type ProviderStats = table {
    1: name fuchsia.tracing.ProviderName;
    2: pid zx.Koid;
    3: buffering_mode fuchsia.tracing.BufferingMode;
    4: buffer_wrapped_count uint32;
    5: records_dropped uint64;
    6: percentage_durable_buffer_used float32;
    7: non_durable_bytes_written uint64;
};

/// Result of a terminate request.
type TerminateResult = table {
    1: provider_stats vector<ProviderStats>:MAX_NUM_PROVIDERS;
};

/// Error codes from Start operations.
type StartErrorCode = flexible enum {
    /// Tracing hasn't been initialized, not ready to start.
    NOT_INITIALIZED = 1;
    /// Tracing has already been started.
    ALREADY_STARTED = 2;
    /// Tracing is currently being stopped.
    STOPPING = 3;
    /// Tracing is currently being terminated.
    TERMINATING = 4;
};

/// Additional options to control trace data collection.
type StartOptions = table {
    /// Whether and how to clear the buffer when starting data collection.
    /// This allows, for example, multiple Start/Stop trace runs to be
    /// collected in the same buffer.
    ///
    /// If the preceding `Stop()` request had `save_after_stopped=true`
    /// then this value is overridden to CLEAR_ENTIRE_BUFFER to avoid
    /// duplicate data being saved.
    1: buffer_disposition fuchsia.tracing.BufferDisposition;

    /// The trace categories to add to the initial set provided in
    /// `TraceConfig`. If the combined number of categories goes over the
    /// limit then the extra categories past the limit are discarded.
    2: additional_categories fuchsia.tracing.EnabledCategoryList;
};

/// Additional options to control stopping of a trace.
type StopOptions = table {
    /// If true then write all collected data after tracing has stopped.
    /// This is useful in situations where one wants to clear the buffer
    /// before starting the next trace, without having to first terminate the
    /// trace and start a new one.
    1: write_results bool;
};

/// Result of `GetProviders`.
type ProviderInfo = table {
    /// The provider's ID, assigned by trace-manager.
    1: id fuchsia.tracing.ProviderId;

    /// The provider's pid.
    2: pid zx.Koid;

    /// The name of the provider.
    3: name fuchsia.tracing.ProviderName;
};