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

// The provider interface which applications must implement and register
// with the |TraceRegistry| to participate in tracing.
//
// See //zircon/system/ulib/trace-provider/ for a C++ implementation of
// this interface which can easily be configured by an application.
interface Provider {
    // Starts writing trace records for events in the specified |categories|
    // into |buffer| using |fence| for signaling.
    //
    // When the trace provider fills the buffer completely, it must stop tracing
    // and close both |buffer| and |fence| to indicate to the trace manager
    // that tracing is finished.
    //
    // When the trace provider observes |ZX_EVENTPAIR_CLOSED| on |fence|, it must
    // assume the trace manager has terminated abnormally (since |Stop| was
    // not received as usual) and stop tracing automatically.
    //
    // At most one trace can be running at a time.  If the trace provider
    // receives a request to start tracing while already tracing, it must
    // ignore the request.
    //
    // There is no result. If the provider successfully starts it must call
    // zx_object_signal_peer() on |fence| passing |TRACE_PROVIDER_SIGNAL_STARTED|.
    // #include <trace-provider/provider.h> to get |TRACE_PROVIDER_SIGNAL_STARTED|.
    // To indicate failure to start close |fence|.
    //
    // If the provider drops a record because its buffer is full it must call
    // zx_object_signal_peer() on |fence| passing
    // |TRACE_PROVIDER_SIGNAL_BUFFER_OVERFLOW|.
    //
    // TODO(jeffbrown): Implement half-full signal and streaming protocol.
    // TODO(jeffbrown): We should make Zircon constants visible to fidl in some
    // way so that we can define constants with meaningful names like
    // TRACE_PROVIDER_SIGNAL_STARTED = ZX_USER_SIGNAL_1.
    1: Start(handle<vmo> buffer, handle<eventpair> fence, vector<string:100>:100 categories);

    // Stops tracing.
    //
    // Once the provider has finished writing any final events to the trace
    // buffer, it must close both |buffer| and |fence| to indicate to the trace
    // manager that tracing is finished.
    2: Stop();
};

// The service which trace providers use to register themselves with
// the tracing system.
[Discoverable]
interface Registry {
    // Registers the trace provider.
    // To unregister, simply close the TraceProvider pipe.
    1: RegisterTraceProvider(Provider provider);
};