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