sdk/fidl/fuchsia.tracing.controller/trace_controller.fidl

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

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

/// The maximum length of a provider's name.
const uint32 MAX_PROVIDER_NAME_LENGTH = 100;

/// The maximum number of categories supported.
const uint32 MAX_NUM_CATEGORIES = 100;

/// The maximum length of a category name.
const uint32 MAX_CATEGORY_NAME_LENGTH = 100;

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

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

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

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

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

// Individual providers can be tuned with this.
table ProviderSpec {
    1: string:MAX_PROVIDER_NAME_LENGTH 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:MAX_CATEGORY_NAME_LENGTH>:MAX_NUM_CATEGORIES 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>:MAX_NUM_PROVIDERS provider_specs;
};

/// Result of |GetProviders|.
table ProviderInfo {
    /// The provider's ID, assigned by trace-manager.
    1: uint32 id;

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

    /// The name of the provider.
    3: string:MAX_PROVIDER_NAME_LENGTH name;
};