| // 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; | |
| using zx; | |
| // 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 |fifo| for signaling. | |
| // | |
| // |buffering_mode| specifies what happens when the buffer fills. | |
| // ONESHOT: The provider must stop tracing. | |
| // CIRCULAR: Continue tracing, dropping oldest records to make room | |
| // for new ones. | |
| // STREAMING: As the buffer fills notify TraceManager that it needs to be | |
| // saved so that tracing can continue without dropping records. Whether | |
| // records get dropped depends on how fast TraceManager is able to save | |
| // intermediate buffers. No guarantee is made that records won't be | |
| // dropped. Coordination of the saving of buffers is done via |fifo|. | |
| // See trace-provider/provider.h for details. | |
| // | |
| // When the trace provider observes |ZX_FIFO_PEER_CLOSED| on |fifo|, it must | |
| // assume the trace manager has terminated abnormally (since |Stop| was | |
| // not received as usual) and stop tracing automatically, discarding | |
| // any in-flight trace data. | |
| // | |
| // 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 send a | |
| // TRACE_PROVIDER_STARTED packet on |fifo|. | |
| // #include <trace-provider/provider.h> to get |TRACE_PROVIDER_STARTED|. | |
| // To indicate failure to start close |fifo|. | |
| 1: Start(BufferingMode buffering_mode, | |
| handle<vmo> buffer, handle<fifo> fifo, | |
| 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 |fifo| 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. | |
| // Note that one property of this interface is that once registration is made | |
| // the provider can drop this connection. | |
| [Discoverable, Layout="Simple"] | |
| interface Registry { | |
| // Registers the trace provider. | |
| // Note: Registration is asynchronous, it's only at some point after this | |
| // returns that the provider is actually registered. | |
| // To unregister, simply close the TraceProvider pipe. | |
| 1: RegisterTraceProviderDeprecated(Provider provider); | |
| // Registers the trace provider. | |
| // Note: Registration is asynchronous, it's only at some point after this | |
| // returns that the provider is actually registered. | |
| // To unregister, simply close the TraceProvider pipe. | |
| 2: RegisterTraceProvider(Provider provider, zx.koid pid, string:100 name); | |
| // Registers the trace provider synchronously. The call doesn't return | |
| // until the provider is registered. | |
| // On return |s| is ZX_OK if registration was successful. | |
| // |started| is true if tracing has already started, which is a hint to | |
| // the provider to wait for the Start() message before continuing if it | |
| // wishes to not drop trace records before Start() is received. | |
| // To unregister, simply close the TraceProvider pipe. | |
| 3: RegisterTraceProviderSynchronously(Provider provider, zx.koid pid, string:100 name) -> (zx.status s, bool started); | |
| }; | |
| // The trace buffering mode. | |
| enum BufferingMode : uint8 { | |
| // In oneshot mode there is only one buffer that is not reused. When the | |
| // buffer fills the provider just keeps dropping records, keeping a count, | |
| // and then when tracing stops the header is updated to record final state. | |
| ONESHOT = 0; | |
| // In circular mode, the buffer is effectively split into two pieces. | |
| // When a buffer fills writing immediately continues with the other | |
| // buffer, and this continues until tracing stops. | |
| CIRCULAR = 1; | |
| // In streaming mode, the buffer is effectively split into two pieces. | |
| // When a buffer fills the provider: | |
| // - TODO(dje): Say more here. | |
| // and then, when the buffer is saved, the manager: | |
| // - TODO(dje): Say more here. | |
| // If the manager hasn't saved the buffer in time, and the other buffer | |
| // fills, then the provider is required to keep dropping records until | |
| // the buffer is ready. | |
| STREAMING = 2; | |
| }; |